1Thread(3pm)            Perl Programmers Reference Guide            Thread(3pm)
2
3
4

NAME

6       Thread - Manipulate threads in Perl (for old code only)
7

DEPRECATED

9       The "Thread" module served as the frontend to the old-style thread
10       model, called 5005threads, that was introduced in release 5.005.  That
11       model was deprecated, and has been removed in version 5.10.
12
13       For old code and interim backwards compatibility, the "Thread" module
14       has been reworked to function as a frontend for the new interpreter
15       threads (ithreads) model.  However, some previous functionality is not
16       available.  Further, the data sharing models between the two thread
17       models are completely different, and anything to do with data sharing
18       has to be thought differently.  With ithreads, you must explicitly
19       "share()" variables between the threads.
20
21       You are strongly encouraged to migrate any existing threaded code to
22       the new model (i.e., use the "threads" and "threads::shared" modules)
23       as soon as possible.
24

HISTORY

26       In Perl 5.005, the thread model was that all data is implicitly shared,
27       and shared access to data has to be explicitly synchronized.  This
28       model is called 5005threads.
29
30       In Perl 5.6, a new model was introduced in which all is was thread
31       local and shared access to data has to be explicitly declared.  This
32       model is called ithreads, for "interpreter threads".
33
34       In Perl 5.6, the ithreads model was not available as a public API; only
35       as an internal API that was available for extension writers, and to
36       implement fork() emulation on Win32 platforms.
37
38       In Perl 5.8, the ithreads model became available through the "threads"
39       module, and the 5005threads model was deprecated.
40
41       In Perl 5.10, the 5005threads model was removed from the Perl
42       interpreter.
43

SYNOPSIS

45           use Thread qw(:DEFAULT async yield);
46
47           my $t = Thread->new(\&start_sub, @start_args);
48
49           $result = $t->join;
50           $t->detach;
51
52           if ($t->done) {
53               $t->join;
54           }
55
56           if($t->equal($another_thread)) {
57               # ...
58           }
59
60           yield();
61
62           my $tid = Thread->self->tid;
63
64           lock($scalar);
65           lock(@array);
66           lock(%hash);
67
68           my @list = Thread->list;
69

DESCRIPTION

71       The "Thread" module provides multithreading support for Perl.
72

FUNCTIONS

74       $thread = Thread->new(\&start_sub)
75       $thread = Thread->new(\&start_sub, LIST)
76               "new" starts a new thread of execution in the referenced
77               subroutine. The optional list is passed as parameters to the
78               subroutine. Execution continues in both the subroutine and the
79               code after the "new" call.
80
81               "Thread->new" returns a thread object representing the newly
82               created thread.
83
84       lock VARIABLE
85               "lock" places a lock on a variable until the lock goes out of
86               scope.
87
88               If the variable is locked by another thread, the "lock" call
89               will block until it's available.  "lock" is recursive, so
90               multiple calls to "lock" are safe--the variable will remain
91               locked until the outermost lock on the variable goes out of
92               scope.
93
94               Locks on variables only affect "lock" calls--they do not affect
95               normal access to a variable. (Locks on subs are different, and
96               covered in a bit.)  If you really, really want locks to block
97               access, then go ahead and tie them to something and manage this
98               yourself.  This is done on purpose.  While managing access to
99               variables is a good thing, Perl doesn't force you out of its
100               living room...
101
102               If a container object, such as a hash or array, is locked, all
103               the elements of that container are not locked. For example, if
104               a thread does a "lock @a", any other thread doing a
105               "lock($a[12])" won't block.
106
107               Finally, "lock" will traverse up references exactly one level.
108               "lock(\$a)" is equivalent to "lock($a)", while "lock(\\$a)" is
109               not.
110
111       async BLOCK;
112               "async" creates a thread to execute the block immediately
113               following it.  This block is treated as an anonymous sub, and
114               so must have a semi-colon after the closing brace. Like
115               "Thread->new", "async" returns a thread object.
116
117       Thread->self
118               The "Thread->self" function returns a thread object that
119               represents the thread making the "Thread->self" call.
120
121       Thread->list
122               Returns a list of all non-joined, non-detached Thread objects.
123
124       cond_wait VARIABLE
125               The "cond_wait" function takes a locked variable as a
126               parameter, unlocks the variable, and blocks until another
127               thread does a "cond_signal" or "cond_broadcast" for that same
128               locked variable. The variable that "cond_wait" blocked on is
129               relocked after the "cond_wait" is satisfied.  If there are
130               multiple threads "cond_wait"ing on the same variable, all but
131               one will reblock waiting to re-acquire the lock on the
132               variable.  (So if you're only using "cond_wait" for
133               synchronization, give up the lock as soon as possible.)
134
135       cond_signal VARIABLE
136               The "cond_signal" function takes a locked variable as a
137               parameter and unblocks one thread that's "cond_wait"ing on that
138               variable. If more than one thread is blocked in a "cond_wait"
139               on that variable, only one (and which one is indeterminate)
140               will be unblocked.
141
142               If there are no threads blocked in a "cond_wait" on the
143               variable, the signal is discarded.
144
145       cond_broadcast VARIABLE
146               The "cond_broadcast" function works similarly to "cond_signal".
147               "cond_broadcast", though, will unblock all the threads that are
148               blocked in a "cond_wait" on the locked variable, rather than
149               only one.
150
151       yield   The "yield" function allows another thread to take control of
152               the CPU. The exact results are implementation-dependent.
153

METHODS

155       join    "join" waits for a thread to end and returns any values the
156               thread exited with.  "join" will block until the thread has
157               ended, though it won't block if the thread has already
158               terminated.
159
160               If the thread being "join"ed "die"d, the error it died with
161               will be returned at this time. If you don't want the thread
162               performing the "join" to die as well, you should either wrap
163               the "join" in an "eval" or use the "eval" thread method instead
164               of "join".
165
166       detach  "detach" tells a thread that it is never going to be joined
167               i.e.  that all traces of its existence can be removed once it
168               stops running.  Errors in detached threads will not be visible
169               anywhere - if you want to catch them, you should use
170               $SIG{__DIE__} or something like that.
171
172       equal   "equal" tests whether two thread objects represent the same
173               thread and returns true if they do.
174
175       tid     The "tid" method returns the tid of a thread. The tid is a
176               monotonically increasing integer assigned when a thread is
177               created. The main thread of a program will have a tid of zero,
178               while subsequent threads will have tids assigned starting with
179               one.
180
181       done    The "done" method returns true if the thread you're checking
182               has finished, and false otherwise.
183

DEFUNCT

185       The following were implemented with 5005threads, but are no longer
186       available with ithreads.
187
188       lock(\&sub)
189               With 5005threads, you could also "lock" a sub such that any
190               calls to that sub from another thread would block until the
191               lock was released.
192
193               Also, subroutines could be declared with the ":locked"
194               attribute which would serialize access to the subroutine, but
195               allowed different threads non-simultaneous access.
196
197       eval    The "eval" method wrapped an "eval" around a "join", and so
198               waited for a thread to exit, passing along any values the
199               thread might have returned and placing any errors into $@.
200
201       flags   The "flags" method returned the flags for the thread - an
202               integer value corresponding to the internal flags for the
203               thread.
204

SEE ALSO

206       threads, threads::shared, Thread::Queue, Thread::Semaphore
207
208
209
210perl v5.36.3                      2023-11-30                       Thread(3pm)
Impressum