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
=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
=head1 SEE ALSO
-L<threads> L<threads::shared>
+L<threads>, L<threads::shared>
=cut
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
=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.
=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
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({});
=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.
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>.
=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.
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
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
=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!
projects / p5sagit/p5-mst-13.2.git / commitdiff