[DOC PATCH] ext/threads/shared/shared.pm

[p5sagit/p5-mst-13.2.git] / ext / threads / shared / shared.pm

diff --git a/ext/threads/shared/shared.pm b/ext/threads/shared/shared.pm
index f98ca7d..c799889 100644 (file)
--- a/ext/threads/shared/shared.pm
+++ b/ext/threads/shared/shared.pm
@@ -3,36 +3,13 @@ package threads::shared;
 use 5.007_003;
 use strict;
 use warnings;
-use Config;
-
-BEGIN {
-    unless ($Config{useithreads}) {
-       my @caller = caller(2);
-        die <<EOF;
-$caller[1] line $caller[2]:
-
-This Perl hasn't been configured and built properly for the threads
-module to work.  (The 'useithreads' configuration option hasn't been used.)
-
-Having threads support requires all of Perl and all of the modules in
-the Perl installation to be rebuilt, it is not just a question of adding
-the threads module.  (In other words, threaded and non-threaded Perls
-are binary incompatible.)
-
-If you want to the use the threads module, please contact the people
-who built your Perl.
-
-Cannot continue, aborting.
-EOF
-    }
-}
 
 require Exporter;
 our @ISA = qw(Exporter);
 our @EXPORT = qw(share cond_wait cond_broadcast cond_signal _refcnt _id _thrcnt);
 our $VERSION = '0.90';
 
-if ($Config{'useithreads'}) {
+if ($threads::threads) {
        *cond_wait = \&cond_wait_enabled;
        *cond_signal = \&cond_signal_enabled;
        *cond_broadcast = \&cond_broadcast_enabled;
@@ -54,7 +31,6 @@ sub share_disabled { return @_}
 
 $threads::shared::threads_shared = 1;
 
-sub _thrcnt { 42 }
 
 sub threads::shared::tie::SPLICE
 {
@@ -78,8 +54,8 @@ threads::shared - Perl extension for sharing data structures between threads
   share($scalar);
   share(@array);
   share(%hash);
-  my $bar = share([]);
-  $hash{bar} = share({});
+  my $bar = &share([]);
+  $hash{bar} = &share({});
 
   { lock(%hash); ...  }
 
@@ -98,14 +74,20 @@ win32). It is used together with the threads module.
 
 C<share>, C<lock>, C<cond_wait>, C<cond_signal>, C<cond_broadcast>
 
+Note that if this module is imported when C<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.
+
 =head1 FUNCTIONS
 
 =over 4
 
 =item share VARIABLE
 
-C<share> takes a value and marks it as shared. You can share a scalar, array,
-hash, scalar ref, array ref or hash ref. C<share> will return the shared value.
+C<share> takes a value and marks it as shared. You can share a scalar,
+array, hash, scalar ref, array ref or hash ref.  C<share> will return
+the shared rvalue.
 
 C<share> will traverse up references exactly I<one> level.
 C<share(\$a)> is equivalent to C<share($a)>, while C<share(\\$a)> is not.
@@ -113,6 +95,10 @@ C<share(\$a)> is equivalent to C<share($a)>, while C<share(\\$a)> is not.
 A variable can also be marked as shared at compile time by using the
 C<shared> attribute: C<my $var : shared>.
 
+If you want to share a newly created reference unfortunately you
+need to use C<&share([])> and C<&share({})> syntax due to problems
+with Perl's prototyping.
+
 =item lock VARIABLE
 
 C<lock> places a lock on a variable until the lock goes out of scope.  If
@@ -191,16 +177,20 @@ implemented in a future version of Perl.
 
 Does not support splice on arrays!
 
+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.
+
 =head1 AUTHOR
 
 Arthur Bergman E<lt>arthur at contiller.seE<gt>
 
 threads::shared is released under the same license as Perl
 
-Documentation borrowed from Thread.pm
+Documentation borrowed from the old Thread.pm
 
 =head1 SEE ALSO
 
-L<threads>, L<perlthrtut>
+L<threads>, L<perlthrtut>, L<http://www.perl.com/pub/a/2002/06/11/threads.html>
 
 =cut