1Thread(3pm) Perl Programmers Reference Guide Thread(3pm)
2
6 Thread - manipulate threads in Perl (for old code only)
7
9 Perl has two thread models.
10 In Perl 5.005 the thread model was that all data is implicitly shared
12 and shared access to data has to be explicitly synchronized. This
13 model is called "5005threads".
14 In Perl 5.6 a new model was introduced in which all is was thread local
16 and shared access to data has to be explicitly declared. This model is
17 called "ithreads", for "interpreter threads".
18 In Perl 5.6 the ithreads model was not available as a public API, only
20 as an internal API that was available for extension writers, and to
21 implement fork() emulation on Win32 platforms.
22 In Perl 5.8 the ithreads model became available through the "threads"
24 module.
25 Neither model is configured by default into Perl (except, as mentioned
27 above, in Win32 ithreads are always available.) You can see your
28 Perl's threading configuration by running "perl -V" and looking for the
29 use...threads variables, or inside script by "use Config;" and testing
30 for $Config{use5005threads} and $Config{useithreads}.
31 For old code and interim backwards compatibility, the Thread module has
33 been reworked to function as a frontend for both 5005threads and
34 ithreads.
35 Note that the compatibility is not complete: because the data sharing
37 models are directly opposed, anything to do with data sharing has to be
38 thought differently. With the ithreads you must explicitly share()
39 variables between the threads.
40 For new code the use of the "Thread" module is discouraged and the
42 direct use of the "threads" and "threads::shared" modules is encouraged
43 instead.
44 Finally, note that there are many known serious problems with the
46 5005threads, one of the least of which is that regular expression match
47 variables like $1 are not threadsafe, that is, they easily get cor‐
48 rupted by competing threads. Other problems include more insidious
49 data corruption and mysterious crashes. You are seriously urged to use
50 ithreads instead.
51
53 use Thread;
54 my $t = Thread->new(\&start_sub, @start_args);
56 $result = $t->join;
58 $result = $t->eval;
59 $t->detach;
60 if ($t->done) {
62 $t->join;
63 }
64 if($t->equal($another_thread)) {
66 # ...
67 }
68 yield();
70 my $tid = Thread->self->tid;
72 lock($scalar);
74 lock(@array);
75 lock(%hash);
76 lock(\&sub); # not available with ithreads
78 $flags = $t->flags; # not available with ithreads
80 my @list = Thread->list; # not available with ithreads
82 use Thread 'async';
84
86 The "Thread" module provides multithreading support for perl.
87
89 $thread = Thread->new(\&start_sub)
90 $thread = Thread->new(\&start_sub, LIST)
91 "new" starts a new thread of execution in the referenced sub‐
92 routine. The optional list is passed as parameters to the sub‐
93 routine. Execution continues in both the subroutine and the
94 code after the "new" call.
95 "Thread->new" returns a thread object representing the newly
97 created thread.
98 lock VARIABLE
100 "lock" places a lock on a variable until the lock goes out of
101 scope.
102 If the variable is locked by another thread, the "lock" call
104 will block until it's available. "lock" is recursive, so mul‐
105 tiple calls to "lock" are safe--the variable will remain locked
106 until the outermost lock on the variable goes out of scope.
107 Locks on variables only affect "lock" calls--they do not affect
109 normal access to a variable. (Locks on subs are different, and
110 covered in a bit.) If you really, really want locks to block
111 access, then go ahead and tie them to something and manage this
112 yourself. This is done on purpose. While managing access to
113 variables is a good thing, Perl doesn't force you out of its
114 living room...
115 If a container object, such as a hash or array, is locked, all
117 the elements of that container are not locked. For example, if
118 a thread does a "lock @a", any other thread doing a
119 "lock($a[12])" won't block.
120 With 5005threads you may also "lock" a sub, using "lock &sub".
122 Any calls to that sub from another thread will block until the
123 lock is released. This behaviour is not equivalent to declaring
124 the sub with the "locked" attribute. The "locked" attribute
125 serializes access to a subroutine, but allows different threads
126 non-simultaneous access. "lock &sub", on the other hand, will
127 not allow any other thread access for the duration of the lock.
128 Finally, "lock" will traverse up references exactly one level.
130 "lock(\$a)" is equivalent to "lock($a)", while "lock(\\$a)" is
131 not.
132 async BLOCK;
134 "async" creates a thread to execute the block immediately fol‐
135 lowing it. This block is treated as an anonymous sub, and so
136 must have a semi-colon after the closing brace. Like
137 "Thread->new", "async" returns a thread object.
138 Thread->self
140 The "Thread->self" function returns a thread object that repre‐
141 sents the thread making the "Thread->self" call.
142 cond_wait VARIABLE
144 The "cond_wait" function takes a locked variable as a parame‐
145 ter, unlocks the variable, and blocks until another thread does
146 a "cond_signal" or "cond_broadcast" for that same locked vari‐
147 able. The variable that "cond_wait" blocked on is relocked
148 after the "cond_wait" is satisfied. If there are multiple
149 threads "cond_wait"ing on the same variable, all but one will
150 reblock waiting to reaquire the lock on the variable. (So if
151 you're only using "cond_wait" for synchronization, give up the
152 lock as soon as possible.)
153 cond_signal VARIABLE
155 The "cond_signal" function takes a locked variable as a parame‐
156 ter and unblocks one thread that's "cond_wait"ing on that vari‐
157 able. If more than one thread is blocked in a "cond_wait" on
158 that variable, only one (and which one is indeterminate) will
159 be unblocked.
160 If there are no threads blocked in a "cond_wait" on the vari‐
162 able, the signal is discarded.
163 cond_broadcast VARIABLE
165 The "cond_broadcast" function works similarly to "cond_signal".
166 "cond_broadcast", though, will unblock all the threads that are
167 blocked in a "cond_wait" on the locked variable, rather than
168 only one.
169 yield The "yield" function allows another thread to take control of
171 the CPU. The exact results are implementation-dependent.
172
174 join "join" waits for a thread to end and returns any values the
175 thread exited with. "join" will block until the thread has
176 ended, though it won't block if the thread has already termi‐
177 nated.
178 If the thread being "join"ed "die"d, the error it died with
180 will be returned at this time. If you don't want the thread
181 performing the "join" to die as well, you should either wrap
182 the "join" in an "eval" or use the "eval" thread method instead
183 of "join".
184 eval The "eval" method wraps an "eval" around a "join", and so waits
186 for a thread to exit, passing along any values the thread might
187 have returned. Errors, of course, get placed into $@. (Not
188 available with ithreads.)
189 detach "detach" tells a thread that it is never going to be joined
191 i.e. that all traces of its existence can be removed once it
192 stops running. Errors in detached threads will not be visible
193 anywhere - if you want to catch them, you should use
194 $SIG{__DIE__} or something like that.
195 equal "equal" tests whether two thread objects represent the same
197 thread and returns true if they do.
198 tid The "tid" method returns the tid of a thread. The tid is a
200 monotonically increasing integer assigned when a thread is cre‐
201 ated. The main thread of a program will have a tid of zero,
202 while subsequent threads will have tids assigned starting with
203 one.
204 flags The "flags" method returns the flags for the thread. This is
206 the integer value corresponding to the internal flags for the
207 thread, and the value may not be all that meaningful to you.
208 (Not available with ithreads.)
209 done The "done" method returns true if the thread you're checking
211 has finished, and false otherwise. (Not available with
212 ithreads.)
213
215 The sequence number used to assign tids is a simple integer, and no
216 checking is done to make sure the tid isn't currently in use. If a
217 program creates more than 2**32 - 1 threads in a single run, threads
218 may be assigned duplicate tids. This limitation may be lifted in a
219 future version of Perl.
220
222 threads::shared (not available with 5005threads)
223 attributes, Thread::Queue, Thread::Semaphore, Thread::Specific (not
225 available with ithreads)
226perl v5.8.8 2001-09-21 Thread(3pm)