use Scalar::Util qw(reftype refaddr blessed);
-our $VERSION = '1.35';
+our $VERSION = '1.41';
my $XS_VERSION = $VERSION;
$VERSION = eval $VERSION;
# Declare that we have been loaded
$threads::shared::threads_shared = 1;
+# Method of complaint about things we can't clone
+$threads::shared::clone_warn = undef;
+
# Load the XS code, if applicable
if ($threads::threads) {
require XSLoader;
} else {
require Carp;
- Carp::croak("Unsupported ref type: ", $ref_type);
+ if (! defined($threads::shared::clone_warn)) {
+ Carp::croak("Unsupported ref type: ", $ref_type);
+ } elsif ($threads::shared::clone_warn) {
+ Carp::carp("Unsupported ref type: ", $ref_type);
+ }
+ return undef;
}
# If input item is an object, then bless the copy into the same class
=head1 VERSION
-This document describes threads::shared version 1.34
+This document describes threads::shared version 1.41
=head1 SYNOPSIS
$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,
+C<shared_clone> will L<croak|Carp> if it encounters such items. To change
+this behaviour to a warning, then set the following:
+
+ $threads::shared::clone_warn = 1;
+
+In this case, C<undef> will be substituted for the item to be cloned. If
+set to zero:
+
+ $threads::shared::clone_warn = 0;
+
+then the C<undef> substitution will be performed silently.
+
=item is_shared VARIABLE
C<is_shared> checks if the specified variable is shared or not. If shared,
The C<cond_wait> function takes a B<locked> variable as a parameter, unlocks
the variable, and blocks until another thread does a C<cond_signal> or
C<cond_broadcast> for that same locked variable. The variable that
-C<cond_wait> blocked on is relocked after the C<cond_wait> is satisfied. If
+C<cond_wait> blocked on is re-locked after the C<cond_wait> is satisfied. If
there are multiple threads C<cond_wait>ing on the same variable, all but one
will re-block waiting to reacquire the lock on the variable. (So if you're only
-using C<cond_wait> for synchronisation, give up the lock as soon as possible).
+using C<cond_wait> for synchronization, give up the lock as soon as possible).
The two actions of unlocking the variable and entering the blocked wait state
are atomic, the two actions of exiting from the blocked wait state and
re-locking the variable are not.
=item cond_timedwait CONDVAR, ABS_TIMEOUT, LOCKVAR
In its two-argument form, C<cond_timedwait> takes a B<locked> variable and an
-absolute timeout as parameters, unlocks the variable, and blocks until the
+absolute timeout in I<epoch> seconds (see L<time() in perlfunc|perlfunc/time>
+for more) as parameters, unlocks the variable, and blocks until the
timeout is reached or another thread signals the variable. A false value is
returned if the timeout is reached, and a true value otherwise. In either
case, the variable is re-locked upon return.
mentioned limitation. See F<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 C<splice> on arrays. Does not support explicitly changing
array lengths via $#array -- use C<push> and C<pop> instead.
Using L<refaddr()|Scalar::Util/"refaddr EXPR">) is unreliable for testing
whether or not two shared references are equivalent (e.g., when testing for
-circular references). Use L<is_shared()/"is_shared VARIABLE">, instead:
+circular references). Use L<is_shared()|/"is_shared VARIABLE">, instead:
use threads;
use threads::shared;
L<threads::shared> Discussion Forum on CPAN:
L<http://www.cpanforum.com/dist/threads-shared>
-Annotated POD for L<threads::shared>:
-L<http://annocpan.org/~JDHEDDEN/threads-shared-1.34/shared.pm>
-
-Source repository:
-L<http://code.google.com/p/threads-shared/>
-
L<threads>, L<perlthrtut>
L<http://www.perl.com/pub/a/2002/06/11/threads.html> and
L<http://www.perl.com/pub/a/2002/09/04/threads.html>
Perl threads mailing list:
-L<http://lists.cpan.org/showlist.cgi?name=iThreads>
+L<http://lists.perl.org/list/ithreads.html>
=head1 AUTHOR