/ 
Patro-0.16
River stage zero No dependents
++
 / threadsx::shared

NAME

threadsx::shared - useful extensions to threads::shared

VERSION

0.16

DESCRIPTION

NAME

threadsx::shared - extension to threads::shared, the Perl extension for sharing data structures between threads

VERSION

This document describes threadsx::shared version 0.16

DESCRIPTION

See threads::shared for the synopsis and API of the threads::shared module. This module extends threads::shared to give it three new capabilities:

1. Support the SPLICE operation on shared arrays
2. Provide a workaround to share CODE references between threads
3. Provide a workaround to share GLOB references between threads

SPLICE operation on shared arrays

Current versions of threads::shared do not support splice operationss on arrays that have been shared.

    $ perl -Mthreads -Mthreads::shared -e \
        'share(@a);@a=(1..10);print splice @a,3,3'
    Splice not implemented for shared arrays at -e line 1.

The threadsx::shared module works around this restriction by hijacking the threads::shared::tie::SPLICE method and emulating the splice operation without a call to the builtin splice function. The performance isn't as good as a native splice call, but it is better than a sharp stick in the eye.

    $ perl -Mthreads -Mthreadsx::shared -e \
        'share(@a);@a=(1..10);print splice @a,3,3'
    456

Sharing CODE references

Current versions of threads::shared do not support sharing of code references or data structures that contain code references

    $ perl -Mthreads -Mthreads::shared -e \
        '$dispatch=shared_clone( {bar=>sub{42}, baz=>\&CORE::warn} )'
    Unsupported ref type: CODE at -e line 1.

The threadsx::shared module employs a workaround, hijacking the method used by threads::shared::shared_clone to identify and share references. The new method substitutes each CODE reference with a shareable, overloaded object that behaves like the underlying CODE reference.

    $ perl -Mthreads -Mthreadsx::shared -e \
        '$dispatch=shared_clone( {bar=>sub{42}, baz=>\&CORE::warn} );
         print $dispatch->{bar}->()'
    42

This feature requires perl v5.18 or better.

Sharing GLOB references

Current versions of threads::shared do not support sharing of GLOB references or data structures that contain GLOB references

    $ perl -Mthreads -Mthreads::shared -e \
         'open my $fh,">foo";$x=shared_clone({foo=>$fh})'
    Unsupported ref type: GLOB at -e line 1.

The threadsx::shared module employs a workaround, hijacking the method used by threads::shared::shared_clone to identify and share referemces. The new method substitutes each GLOB reference with a shareable, overloaded object that behaves like the underlying GLOB reference.

    $ perl -Mthreads -Mthreadsx::shared -e \
         'open $fh,">foo";$x=shared_clone({foo=>$fh});
          print {$x->{foo}} "Hello world\n";close $x->{foo};
          print `cat foo`'
    Hello world

This feature requires perl 5.18 or better.

EXPORT

Like threads::shared, the following functions are exported by this module: share, shared_clone, is_shared, cond_wait, cond_timedwait, cond_signal and cond_broadcast

Note that if this module is imported when threads has not yet been loaded, then these functions all become no-ops. This makes it possible to write modules that will work in both threaded and non-threaded environments.

FUNCTIONS

See "FUNCTIONS" in threads::shared. The features implemented in threadsx::shared do not define any new functions.

NOTES

Like threads::shared, threadsx::shared is designed to disable itself silently if threads are not available. This allows you to write modules and packages that can be used in both threaded and non-threaded applications.

If you want access to threads, you must use threads before you use threadsx::shared. threads will emit a warning if you use it after threadsx::shared.

WARNINGS

The warnings emitted by threadsx::shared are the same as those produced by threads::shared.

cond_broadcast() called on unlocked variable
cond_signal() called on unlocked variable

See "cond_signal VARIABLE", above.

BUGS AND LIMITATIONS

Treat shared CODE and GLOB references in shared data structures as read-only.

When share is used on arrays, hashes, array refs or hash refs, any data they contain will be lost.

  my @arr = qw(foo bar baz);
  share(@arr);
  # @arr is now empty (i.e., == ());

  # Create a 'foo' object
  my $foo = { 'data' => 99 };
  bless($foo, 'foo');

  # Share the object
  share($foo);        # Contents are now wiped out
  print("ERROR: \$foo is empty\n")
      if (! exists($foo->{'data'}));

Therefore, populate such variables after declaring them as shared. (Scalar and scalar refs are not affected by this problem.)

It is often not wise to share an object unless the class itself has been written to support sharing. For example, an object's destructor may get called multiple times, once for each thread's scope exit. Another danger is that the contents of hash-based objects will be lost due to the above mentioned limitation. See examples/class.pl (in the CPAN distribution of this module) for how to create a class that supports object sharing.

Destructors may not be called on objects if those objects still exist at global destruction time. If the destructors must be called, make sure there are no circular references and that nothing is referencing the objects, before the program ends.

Does not support splice on arrays. Does not support explicitly changing array lengths via $#array -- use push and pop instead.

Taking references to the elements of shared arrays and hashes does not autovivify the elements, and neither does slicing a shared array/hash over non-existent indices/keys autovivify the elements.

share() allows you to share($hashref->{key}) and share($arrayref->[idx]) without giving any error message. But the $hashref->{key} or $arrayref->[idx] is not shared, causing the error "lock can only be used on shared values" to occur when you attempt to lock($hashref->{key}) or lock($arrayref->[idx]) in another thread.

Using refaddr() is unreliable for testing whether or not two shared references are equivalent (e.g., when testing for circular references). Use is_shared(), instead:

    use threads;
    use threads::shared;
    use Scalar::Util qw(refaddr);

    # If ref is shared, use threads::shared's internal ID.
    # Otherwise, use refaddr().
    my $addr1 = is_shared($ref1) || refaddr($ref1);
    my $addr2 = is_shared($ref2) || refaddr($ref2);

    if ($addr1 == $addr2) {
        # The refs are equivalent
    }

each() does not work properly on shared references embedded in shared structures. For example:

    my %foo :shared;
    $foo{'bar'} = shared_clone({'a'=>'x', 'b'=>'y', 'c'=>'z'});

    while (my ($key, $val) = each(%{$foo{'bar'}})) {
        ...
    }

Either of the following will work instead:

    my $ref = $foo{'bar'};
    while (my ($key, $val) = each(%{$ref})) {
        ...
    }

    foreach my $key (keys(%{$foo{'bar'}})) {
        my $val = $foo{'bar'}{$key};
        ...
    }

This module supports dual-valued variables created using dualvar() from Scalar::Util. However, while $! acts like a dualvar, it is implemented as a tied SV. To propagate its value, use the follow construct, if needed:

    my $errno :shared = dualvar($!,$!);

View existing bug reports at, and submit any new bugs, problems, patches, etc. to: http://rt.cpan.org/Public/Dist/Display.html?Name=threadsx-shared

For bugs in the underlying threads::shared distribution, use http://rt.cpan.org/Public/Dist/Display.html?Name=threads-shared

SEE ALSO

threads::shared, threads, perlthrtut

http://www.perl.com/pub/a/2002/06/11/threads.html and http://www.perl.com/pub/a/2002/09/04/threads.html

Perl threads mailing list: http://lists.perl.org/list/ithreads.html

AUTHOR

Additional features for threadsx::shared by Marty O'Brien <mob@cpan.org>.

Original threads::shared by Artur Bergman <sky AT crucially DOT net>

CPAN version of threads::shared produced by Jerry D. Hedden <jdhedden AT cpan DOT org>.

LICENSE

threadsx::shared and threads::shared are released under the same license as Perl.