revised warnings + more tests + docs

Message-ID: <20020518222451.E7275@fdgroup.com>

p4raw-id: //depot/perl@16685

1 files changed, 28 insertions, 20 deletions

diff --git a/ext/threads/shared/shared.pm b/ext/threads/shared/shared.pm
index 4ffe261a93..7536495437 100644
--- a/ext/threads/shared/shared.pm
+++ b/ext/threads/shared/shared.pm
@@ -72,6 +72,8 @@ threads::shared - Perl extension for sharing data structures between threads
   use threads;
   use threads::shared;
 
+  my $var : shared;
+
   my($scalar, @array, %hash);
   share($scalar);
   share(@array);
@@ -79,21 +81,22 @@ threads::shared - Perl extension for sharing data structures between threads
   my $bar = share([]);
   $hash{bar} = share({});
 
-  lock(%hash);
-  unlock(%hash);
+  { lock(%hash); ...  }
+
   cond_wait($scalar);
   cond_broadcast(@array);
   cond_signal(%hash);
 
 =head1 DESCRIPTION
 
-This modules allows you to share() variables. These variables will
-then be shared across different threads (and pseudoforks on
-win32). They are used together with the threads module.
+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 pseudoforks on
+win32). It is used together with the threads module.
 
 =head1 EXPORT
 
-C<share>, C<lock>, C<unlock>, C<cond_wait>, C<cond_signal>, C<cond_broadcast>
+C<share>, C<lock>, C<cond_wait>, C<cond_signal>, C<cond_broadcast>
 
 =head1 FUNCTIONS
 
@@ -107,14 +110,16 @@ hash, scalar ref, array ref or hash ref. C<share> will return the shared value.
 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.
 
+A variable can also be marked as shared at compile time by using the
+C<shared> attribute: C<my $var : shared>.
+
 =item lock VARIABLE
 
 C<lock> places a lock on a variable until the lock goes out of scope.  If
 the variable is locked by another thread, the C<lock> call will block until
 it's available. C<lock> is recursive, so multiple calls to C<lock> are
 safe -- the variable will remain locked until the outermost lock on the
-variable goes out of scope or C<unlock> is called enough times to match
-the number of calls to <lock>.
+variable goes out of scope.
 
 If a container object, such as a hash or array, is locked, all the elements
 of that container are not locked. For example, if a thread does a C<lock
@@ -123,15 +128,9 @@ of that container are not locked. For example, if a thread does a C<lock
 C<lock> will traverse up references exactly I<one> level.
 C<lock(\$a)> is equivalent to C<lock($a)>, while C<lock(\\$a)> is not.
 
-
-=item unlock VARIABLE
-
-C<unlock> takes a B<locked> variable and decrements the lock count.
-If the lock count is zero the variable is unlocked. It is not necessary
-to call C<unlock> but it can be useful to reduce lock contention.
-
-C<unlock> will traverse up references exactly I<one> level.
-C<unlock(\$a)> is equivalent to C<unlock($a)>, while C<unlock(\\$a)> is not.
+Note that you cannot explicitly unlock a variable; you can only wait for
+the lock to go out of scope. If you need more fine-grained control, see
+L<threads::shared::semaphore>.
 
 =item cond_wait VARIABLE
 
@@ -141,8 +140,10 @@ 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 there are multiple threads C<cond_wait>ing on the same variable, all but
 one will reblock waiting to reacquire the lock on the variable. (So if
-you're only using C<cond_wait> for synchronization, give up the lock as
-soon as possible)
+you're only using C<cond_wait> for synchronisation, 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 relocking the variable are not.
 
 It is important to note that the variable can be notified even if no
 thread C<cond_signal> or C<cond_broadcast> on the variable. It is therefore
@@ -157,7 +158,14 @@ one thread is blocked in a C<cond_wait> on that variable, only one (and
 which one is indeterminate) will be unblocked.
 
 If there are no threads blocked in a C<cond_wait> on the variable, the
-signal is discarded.
+signal is discarded. By always locking before signaling, you can (with
+care), avoid signaling before another thread has entered cond_wait().
+
+C<cond_signal> will normally generate a warning if you attempt to use it
+on an unlocked variable. On the rare occasions where doing this may be
+sensible, you can skip the warning with
+
+    { no warnings 'threads'; cond_signal($foo) }
 
 =item cond_broadcast VARIABLE