forks::shared(3) User Contributed Perl Documentation forks::shared(3)NAMEforks::shared - drop-in replacement for Perl threads::shared with
forks()SYNOPSIS
use forks;
use forks::shared;
my $variable : shared;
my @array : shared;
my %hash : shared;
share( $variable );
share( @array );
share( %hash );
$variable = shared_clone($non_shared_ref_value);
$variable = shared_clone({'foo' => [qw/foo bar baz/]});
lock( $variable );
cond_wait( $variable );
cond_wait( $variable, $lock_variable );
cond_timedwait( $variable, abs time );
cond_timedwait( $variable, abs time, $lock_variable );
cond_signal( $variable );
cond_broadcast( $variable );
bless( $variable, class name );
# Enable deadlock detection and resolution
use forks::shared deadlock => {
detect => 1,
resolve => 1
);
# or
threads::shared->set_deadlock_option(
detect => 1,
resolve => 1
);
DESCRIPTION
The "forks::shared" pragma allows a developer to use shared variables
with threads (implemented with the "forks" pragma) without having to
have a threaded perl, or to even run 5.8.0 or higher.
"forks::shared" is currently API compatible with CPAN threads::shared
version 1.05.
EXPORT
"share", "shared_clone", "cond_wait", "cond_timedwait", "cond_signal",
"cond_broadcast", "is_shared", "bless"
See "EXPORT" in threads::shared for more information.
OBJECTSforks::shared exports a version of bless() that works on shared
objects, such that blessings propagate across threads. See
threads::shared for usage information and the forks test suite for
additional examples.
EXTRA FEATURES
Deadlock detection and resolution
In the interest of helping programmers debug one of the most common
bugs in threaded application software, forks::shared supports a full
deadlock detection and resolution engine.
Automated detection and resolution
There are two ways to enable these features: either at import time in a
use statement, such as:
use forks::shared deadlock => { OPTIONS }
or during runtime as a class method call to "set_deadlock_option",
like:
forks::shared->set_deadlock_option( OPTIONS );
#or
threads::shared->set_deadlock_option( OPTIONS );
where "OPTIONS" may be a combination of any of the following:
detect => 1 (enable) or 0 (disable)
period => number of seconds between asynchronous polls
resolve => 1 (enable) or 0 (disable)
The "detect" option enables deadlock detection. By itself, this option
enabled synchronous deadlock detection, which efficiently checks for
potential deadlocks at lock() time. If any are detected and warnings
are enabled, it will print out details to "STDERR" like the following
example:
Deadlock detected:
TID SV LOCKED SV LOCKING Caller
1 3 4 t/forks06.t at line 41
2 4 3 t/forks06.t at line 46
The "period" option, if set to a value greater than zero, is the number
of seconds between asynchronous deadlock detection checks.
Asynchronous detection is useful for debugging rare, time-critical race
conditions leading to deadlocks that may be masked by the slight time
overhead introduced by synchronous detection on each lock() call.
Overall, it is less CPU intensive than synchronous deadlock detection.
The "resolve" option enables auto-termination of one thread in each
deadlocked thread pair that has been detected. As with the "detect"
option, "resolve" prints out the action it performs to STDERR, if
warnings are enabled. NOTE: "resolve" uses SIGKILL to break deadlocks,
so this feature should not be used in environments where stability of
the rest of your application may be adversely affected by process death
in this manner.
For example:
use forks;
use forks::shared
deadlock => {detect=> 1, resolve => 1};
Manual detection
If you wish to check for deadlocks without enabling automated deadlock
detection, forks provides an additonal thread object method,
$thr->is_deadlocked()
that reports whether the thread in question is currently deadlocked.
This method may be used in conjunction with the "resolve" deadlock
option to auto-terminate offending threads.
Splice on shared array
As of at least threads::shared 1.05, the splice function has not been
implememted for arrays; however, forks::shared fully supports splice on
shared arrays.
share() doesn't lose value for arrays and hashes
In the standard Perl threads implementation, arrays and hashes are re-
initialized when they become shared (with the share()) function. The
share() function of forks::shared does not initialize arrays and hashes
when they become shared with the share() function.
This could be considered a bug in the standard Perl implementation. In
any case this is an inconsistency of the behaviour of threads.pm and
forks.pm.
If you do not have a natively threaded perl and you have installed and
are using forks in "threads.pm" override mode (where "use threads"
loads forks.pm), then this module will explicitly emulate the behavior
of standard threads::shared and lose value for arrays and hashes with
share(). Additionally, array splice function will become a no-op with
a warning.
You may also enable this mode by setting the environment variable
"THREADS_NATIVE_EMULATION" to a true value before running your script.
See "Native threads 'to-the-letter' emulation mode" in forks for more
information.
CAVIATS
Some caveats that you need to be aware of.
Storing CODE refs in shared variables
Since forks::shared requires Storable to serialize shared data
structures, storing CODE refs in shared variables is not enabled by
default (primarily for security reasons).
If need share CODE refs between threads, the minimum you must do
before storing CODE refs is:
$Storable::Deparse = $Storable::Eval = 1;
See "CODE_REFERENCES" in Storable for detailed information, including
potential security risks and ways to protect yourself against them.
test-suite exits in a weird way
Although there are no errors in the test-suite, the test harness
sometimes thinks there is something wrong because of an unexpected
exit() value. This is an issue with Test::More's END block, which
wasn't designed to co-exist with a threads environment and forked
processes. Hopefully, that module will be patched in the future, but
for now, the warnings are harmless and may be safely ignored.
CURRENT AUTHOR AND MAINTAINER
Eric Rybski <rybskej@yahoo.com>. Please send all module inquries to
me.
ORIGINAL AUTHOR
Elizabeth Mattijsen, <liz@dijkmat.nl>.
COPYRIGHT
Copyright (c)
2005-2009 Eric Rybski <rybskej@yahoo.com>,
2002-2004 Elizabeth Mattijsen <liz@dijkmat.nl>. All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSO
threads::shared, forks, forks::BerkeleyDB::shared.
perl v5.10.1 2009-03-27 forks::shared(3)
