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.
+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<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
+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
=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.
+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.
-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
-@a>, any other thread doing a C<lock($a[12])> won't block.
+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 @a>, any other thread doing a C<lock($a[12])> won't block.
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.
-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>.
+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
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 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 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
+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 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). 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
-important to check the value of the variable and go back to waiting if the
-requirement is not fulfilled.
+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 requirement is not fulfilled.
=item cond_signal VARIABLE
-The C<cond_signal> function takes a B<locked> variable as a parameter and
-unblocks one thread that's C<cond_wait>ing on that variable. If more than
-one thread is blocked in a C<cond_wait> on that variable, only one (and
-which one is indeterminate) will be unblocked.
+The C<cond_signal> function takes a B<locked> variable as a parameter
+and unblocks one thread that's C<cond_wait>ing on that variable. If
+more than 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. By always locking before signaling, you can (with
-care), avoid signaling before another thread has entered cond_wait().
+If there are no threads blocked in a C<cond_wait> on the variable,
+the 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
=item cond_broadcast VARIABLE
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.
+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
package threads;
-use 5.007_003;
+use 5.008;
use strict;
use warnings;
use Config;
Perl 5.6 introduced something called interpreter threads. Interpreter
threads are different from "5005threads" (the thread model of Perl
5.005) by creating a new perl interpreter per thread and not sharing
-any data or state between threads.
+any data or state between threads by default.
Prior to perl 5.8 this has only been available to people embedding
perl and for emulating fork() on windows.
=item $thread->join
-This will wait for the corresponding thread to join. When the thread finishes,
-join() will return the return values of the entry point function. If the
-thread has been detached, an error will be thrown. If the program
-exits without all other threads having been either joined or detached,
-then a warning will be issued. (A program exits either because one of its
-threads explicitly calls exit(), or in the case of the main thread, reaches
-the end of the main program file.)
+This will wait for the corresponding thread to join. When the thread
+finishes, join() will return the return values of the entry point
+function. If the thread has been detached, an error will be thrown.
+If the program exits without all other threads having been either
+joined or detached, then a warning will be issued. (A program exits
+either because one of its threads explicitly calls exit(), or in the
+case of the main thread, reaches the end of the main program file.)
=item $thread->detach
-Will make the thread unjoinable, and cause any eventual return value to be
-discarded.
+Will make the thread unjoinable, and cause any eventual return value
+to be discarded.
=item threads->self
=item $thread->tid
-This will return the id of the thread. Thread IDs are integers, with the
-main thread in a program being 0. Currently Perl assigns a unique tid to
-every thread ever created in your program, assigning the first thread to
-be created a tid of 1, and increasing the tid by 1 for each new thread
-that's created.
+This will return the id of the thread. Thread IDs are integers, with
+the main thread in a program being 0. Currently Perl assigns a unique
+tid to every thread ever created in your program, assigning the first
+thread to be created a tid of 1, and increasing the tid by 1 for each
+new thread that's created.
NB the class method C<< threads->tid() >> is a quick way to get the
current thread id if you don't have your thread object handy.
A thread (not necessarily the main thread) exited while there were
still other threads running. Usually it's a good idea to first collect
the return values of the created threads by joining them, and only then
-exit from then main thread.
+exit from the main thread.
=back
=item tid is I32
-The tid is a 32 bit integer, it can potentially overflow.
+The thread id is a 32 bit integer, it can potentially overflow.
This might be fixed in a later version of perl.
=item Returning objects
When you return an object the entire stash that the object is blessed
-as well. This will lead to a large memory usage.
-The ideal situation would be to detect the original stash if it existed.
+as well. This will lead to a large memory usage. The ideal situation
+would be to detect the original stash if it existed.
=item PERL_OLD_SIGNALS are not threadsafe, will not be.
projects / p5sagit/p5-mst-13.2.git / commitdiff