threadsx::shared - useful extensions to threads::shared
0.16
threadsx::shared - extension to threads::shared, the Perl extension for sharing data structures between threads
threads::shared
This document describes threadsx::shared version 0.16
See threads::shared for the synopsis and API of the threads::shared module. This module extends threads::shared to give it three new capabilities:
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.
threadsx::shared
threads::shared::tie::SPLICE
splice
$ perl -Mthreads -Mthreadsx::shared -e \ 'share(@a);@a=(1..10);print splice @a,3,3' 456
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.
threads::shared::shared_clone
$ 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.
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.
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
share
shared_clone
is_shared
cond_wait
cond_timedwait
cond_signal
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.
See "FUNCTIONS" in threads::shared. The features implemented in threadsx::shared do not define any new functions.
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.
use threads
use threadsx::shared
The warnings emitted by threadsx::shared are the same as those produced by threads::shared.
See "cond_signal VARIABLE", above.
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.
push
pop
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.
share()
share($hashref->{key})
share($arrayref->[idx])
$hashref->{key}
$arrayref->[idx]
lock($hashref->{key})
lock($arrayref->[idx])
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:
refaddr()
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:
dualvar()
$!
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
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
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>.
threadsx::shared and threads::shared are released under the same license as Perl.
To install Patro, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Patro
CPAN shell
perl -MCPAN -e shell install Patro
For more information on module installation, please visit the detailed CPAN module installation guide.