This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[DOC PATCH] Minor threads::shared nits
authorSimon Glover <scog@roe.ac.uk>
Wed, 8 May 2002 17:23:16 +0000 (13:23 -0400)
committerJarkko Hietaniemi <jhi@iki.fi>
Wed, 8 May 2002 22:25:01 +0000 (22:25 +0000)
Message-ID: <Pine.GSO.4.43.0205081719050.26360-100000@egg.amnh.org>

p4raw-id: //depot/perl@16500

ext/threads/shared/queue.pm
ext/threads/shared/semaphore.pm
ext/threads/shared/shared.pm

index 542c000..557833a 100644 (file)
@@ -64,7 +64,7 @@ A queue, as implemented by C<threads::shared::queue> is a thread-safe
 data structure much like a list.  Any number of threads can safely 
 add elements to the end of the list, or remove elements from the head 
 of the list. (Queues don't permit adding or removing elements from 
-the middle of the list)
+the middle of the list).
 
 =head1 FUNCTIONS AND METHODS
 
@@ -77,7 +77,7 @@ The C<new> function creates a new empty queue.
 =item enqueue LIST
 
 The C<enqueue> method adds a list of scalars on to the end of the queue.
-The queue will grow as needed to accomodate the list.
+The queue will grow as needed to accommodate the list.
 
 =item dequeue
 
@@ -100,7 +100,7 @@ The C<pending> method returns the number of items still in the queue.
 
 =head1 SEE ALSO
 
-L<threads> L<threads::shared>
+L<threads>, L<threads::shared>
 
 =cut
 
index 91a1f27..bb114dc 100644 (file)
@@ -28,8 +28,8 @@ unlike locks, aren't tied to particular scalars, and so may be used to
 control access to anything you care to use them for.
 
 Semaphores don't limit their values to zero or one, so they can be used to
-control access to some resource that may have more than one of. (For
-example, filehandles) Increment and decrement amounts aren't fixed at one
+control access to some resource that there may be more than one of. (For
+example, filehandles). Increment and decrement amounts aren't fixed at one
 either, so threads can reserve or return multiple resources at once.
 
 =head1 FUNCTIONS AND METHODS
@@ -48,7 +48,7 @@ number. If no number is passed, the semaphore's count is set to one.
 =item down NUMBER
 
 The C<down> method decreases the semaphore's count by the specified number,
-or one if no number has been specified. If the semaphore's count would drop
+or by one if no number has been specified. If the semaphore's count would drop
 below zero, this method will block until such time that the semaphore's
 count is equal to or larger than the amount you're C<down>ing the
 semaphore's count by.
@@ -58,9 +58,9 @@ semaphore's count by.
 =item up NUMBER
 
 The C<up> method increases the semaphore's count by the number specified,
-or one if no number's been specified. This will unblock any thread blocked
+or by one if no number has been specified. This will unblock any thread blocked
 trying to C<down> the semaphore if the C<up> raises the semaphore count
-above what the C<down>s are trying to decrement it by.
+above the amount that the C<down>s are trying to decrement it by.
 
 =back
 
index 03949cb..ef1aeff 100644 (file)
@@ -80,9 +80,9 @@ threads::shared - Perl extension for sharing data structures between threads
   use threads;
   use threads::shared;
 
-  my($foo, @foo, %foo);
-  share($foo);
-  share(@foo);
+  my($scalar, @array, %hash);
+  share($scalar);
+  share(@array);
   share(%hash);
   my $bar = share([]);
   $hash{bar} = share({});
@@ -109,8 +109,8 @@ C<share>, C<lock>, C<unlock>, C<cond_wait>, C<cond_signal>, C<cond_broadcast>
 
 =item share VARIABLE
 
-C<share> takes a value and marks it as shared, you can share a scalar, array, hash
-scalar ref, array ref and 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 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.
@@ -120,7 +120,7 @@ C<share(\$a)> is equivalent to C<share($a)>, while C<share(\\$a)> is not.
 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
+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>.
 
@@ -134,9 +134,9 @@ C<lock(\$a)> is equivalent to C<lock($a)>, while C<lock(\\$a)> is not.
 
 =item unlock VARIABLE
 
-C<unlock> takes a locked shared value and decrements the lock count.
+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 usefull to reduce lock contention.
+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.
@@ -148,14 +148,14 @@ 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 there are multiple threads C<cond_wait>ing on the same variable, all but
-one will reblock waiting to reaquire the lock on the variable. (So if
+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)
 
 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
 important to check the value of the variable and go back to waiting if the
-requirment is not fullfilled.
+requirement is not fulfilled.
 
 =item cond_signal VARIABLE
 
@@ -173,6 +173,7 @@ The C<cond_broadcast> function works similarly to C<cond_signal>.
 C<cond_broadcast>, though, will unblock B<all> the threads that are blocked
 in a C<cond_wait> on the locked variable, rather than only one.
 
+=back
 
 =head1 NOTES
 
@@ -183,10 +184,10 @@ use it after threads::shared.
 
 =head1 BUGS
 
-C<bless> is not supported on shared references, in the current version
+C<bless> is not supported on shared references. In the current version,
 C<bless> will only bless the thread local reference and the blessing
-will not propagate to the other threads, this is expected to be implmented
-in the future.
+will not propagate to the other threads. This is expected to be
+implemented in a future version of Perl.
 
 Does not support splice on arrays!