threads::shared - Perl extension for sharing data structures between threads
This document describes threads::shared version 1.68
use threads;
use threads::shared;
my $var :shared;
my %hsh :shared;
my @ary :shared;
my ($scalar, @array, %hash);
share($scalar);
share(@array);
share(%hash);
$var = $scalar_value;
$var = $shared_ref_value;
$var = shared_clone($non_shared_ref_value);
$var = shared_clone({'foo' => [qw/foo bar baz/]});
$hsh{'foo'} = $scalar_value;
$hsh{'bar'} = $shared_ref_value;
$hsh{'baz'} = shared_clone($non_shared_ref_value);
$hsh{'quz'} = shared_clone([1..3]);
$ary[0] = $scalar_value;
$ary[1] = $shared_ref_value;
$ary[2] = shared_clone($non_shared_ref_value);
$ary[3] = shared_clone([ {}, [] ]);
{ lock(%hash); ... }
cond_wait($scalar);
cond_timedwait($scalar, time() + 30);
cond_broadcast(@array);
cond_signal(%hash);
my $lockvar :shared;
# condition var != lock var
cond_wait($var, $lockvar);
cond_timedwait($var, time()+30, $lockvar);By default, variables are private to each thread, and each newly created thread gets a private copy of each existing variable. This module allows you to share variables across different threads (and pseudo-forks on Win32). It is used together with the threads module.
This module supports the sharing of the following data types only: scalars and scalar refs, arrays and array refs, and hashes and hash refs.
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.
share takes a variable and marks it as shared:
my ($scalar, @array, %hash);
share($scalar);
share(@array);
share(%hash);share will return the shared rvalue, but always as a reference.
Variables can also be marked as shared at compile time by using the :shared attribute:
my ($var, %hash, @array) :shared;Shared variables can only store scalars, refs of shared variables, or refs of shared data (discussed in next section):
my ($var, %hash, @array) :shared;
my $bork;
# Storing scalars
$var = 1;
$hash{'foo'} = 'bar';
$array[0] = 1.5;
# Storing shared refs
$var = \%hash;
$hash{'ary'} = \@array;
$array[1] = \$var;
# The following are errors:
# $var = \$bork; # ref of non-shared variable
# $hash{'bork'} = []; # non-shared array ref
# push(@array, { 'x' => 1 }); # non-shared hash refshared_clone takes a reference, and returns a shared version of its argument, performing a deep copy on any non-shared elements. Any shared elements in the argument are used as is (i.e., they are not cloned).
my $cpy = shared_clone({'foo' => [qw/foo bar baz/]});Object status (i.e., the class an object is blessed into) is also cloned.
my $obj = {'foo' => [qw/foo bar baz/]};
bless($obj, 'Foo');
my $cpy = shared_clone($obj);
print(ref($cpy), "\n"); # Outputs 'Foo'For cloning empty array or hash refs, the following may also be used:
$var = &share([]); # Same as $var = shared_clone([]);
$var = &share({}); # Same as $var = shared_clone({});Not all Perl data types can be cloned (e.g., globs, code refs). By default, shared_clone will croak if it encounters such items. To change this behaviour to a warning, then set the following:
$threads::shared::clone_warn = 1;In this case, undef will be substituted for the item to be cloned. If set to zero:
$threads::shared::clone_warn = 0;then the undef substitution will be performed silently.
is_shared checks if the specified variable is shared or not. If shared, returns the variable's internal ID (similar to refaddr() (see Scalar::Util). Otherwise, returns undef.
if (is_shared($var)) {
print("\$var is shared\n");
} else {
print("\$var is not shared\n");
}When used on an element of an array or hash, is_shared checks if the specified element belongs to a shared array or hash. (It does not check the contents of that element.)
my %hash :shared;
if (is_shared(%hash)) {
print("\%hash is shared\n");
}
$hash{'elem'} = 1;
if (is_shared($hash{'elem'})) {
print("\$hash{'elem'} is in a shared hash\n");
}lock places a advisory lock on a variable until the lock goes out of scope. If the variable is locked by another thread, the lock call will block until it's available. Multiple calls to lock by the same thread from within dynamically nested scopes are safe -- the variable will remain locked until the outermost lock on the variable goes out of scope.
lock follows references exactly one level:
my %hash :shared;
my $ref = \%hash;
lock($ref); # This is equivalent to lock(%hash)Note that you cannot explicitly unlock a variable; you can only wait for the lock to go out of scope. This is most easily accomplished by locking the variable inside a block.
my $var :shared;
{
lock($var);
# $var is locked from here to the end of the block
...
}
# $var is now unlockedAs locks are advisory, they do not prevent data access or modification by another thread that does not itself attempt to obtain a lock on the variable.
You cannot lock the individual elements of a container variable:
my %hash :shared;
$hash{'foo'} = 'bar';
#lock($hash{'foo'}); # Error
lock(%hash); # WorksIf you need more fine-grained control over shared variable access, see Thread::Semaphore.