Commit | Line | Data |
---|---|---|
43d3ddbe JH |
1 | package Thread; |
2 | ||
4038bebf | 3 | use strict; |
9f015efb | 4 | use warnings; |
014e6b2c | 5 | no warnings 'redefine'; |
4038bebf | 6 | |
191050aa | 7 | our $VERSION = '3.04'; |
9f015efb | 8 | $VERSION = eval $VERSION; |
4038bebf | 9 | |
43d3ddbe JH |
10 | BEGIN { |
11 | use Config; | |
9f015efb JH |
12 | if (! $Config{useithreads}) { |
13 | die("This Perl not built to support threads\n"); | |
14 | } | |
43d3ddbe JH |
15 | } |
16 | ||
9f015efb JH |
17 | use threads 'yield'; |
18 | use threads::shared; | |
19 | ||
43d3ddbe | 20 | require Exporter; |
9f015efb JH |
21 | our @ISA = qw(Exporter threads); |
22 | our @EXPORT = qw(cond_wait cond_broadcast cond_signal); | |
23 | our @EXPORT_OK = qw(async yield); | |
43d3ddbe | 24 | |
014e6b2c | 25 | sub async (&;@) { return Thread->new(shift); } |
43d3ddbe | 26 | |
9f015efb | 27 | sub done { return ! shift->is_running(); } |
43d3ddbe | 28 | |
9f015efb JH |
29 | sub eval { die("'eval' not implemented with 'ithreads'\n"); }; |
30 | sub flags { die("'flags' not implemented with 'ithreads'\n"); }; | |
31 | ||
32 | 1; | |
43d3ddbe | 33 | |
9f015efb | 34 | __END__ |
43d3ddbe | 35 | |
9f015efb | 36 | =head1 NAME |
43d3ddbe | 37 | |
9f015efb | 38 | Thread - Manipulate threads in Perl (for old code only) |
43d3ddbe | 39 | |
9f015efb | 40 | =head1 DEPRECATED |
43d3ddbe | 41 | |
9f015efb JH |
42 | The C<Thread> module served as the frontend to the old-style thread model, |
43 | called I<5005threads>, that was introduced in release 5.005. That model was | |
44 | deprecated, and has been removed in version 5.10. | |
43d3ddbe | 45 | |
9f015efb JH |
46 | For old code and interim backwards compatibility, the C<Thread> module has |
47 | been reworked to function as a frontend for the new interpreter threads | |
48 | (I<ithreads>) model. However, some previous functionality is not available. | |
49 | Further, the data sharing models between the two thread models are completely | |
50 | different, and anything to do with data sharing has to be thought differently. | |
51 | With I<ithreads>, you must explicitly C<share()> variables between the | |
52 | threads. | |
43d3ddbe | 53 | |
9f015efb JH |
54 | You are strongly encouraged to migrate any existing threaded code to the new |
55 | model (i.e., use the C<threads> and C<threads::shared> modules) as soon as | |
56 | possible. | |
43d3ddbe | 57 | |
9f015efb | 58 | =head1 HISTORY |
9d40afd1 | 59 | |
9f015efb JH |
60 | In Perl 5.005, the thread model was that all data is implicitly shared, and |
61 | shared access to data has to be explicitly synchronized. This model is called | |
62 | I<5005threads>. | |
8a20485c | 63 | |
9f015efb JH |
64 | In Perl 5.6, a new model was introduced in which all is was thread local and |
65 | shared access to data has to be explicitly declared. This model is called | |
66 | I<ithreads>, for "interpreter threads". | |
43d3ddbe | 67 | |
9f015efb JH |
68 | In Perl 5.6, the I<ithreads> model was not available as a public API; only as |
69 | an internal API that was available for extension writers, and to implement | |
70 | fork() emulation on Win32 platforms. | |
43d3ddbe | 71 | |
9f015efb JH |
72 | In Perl 5.8, the I<ithreads> model became available through the C<threads> |
73 | module, and the I<5005threads> model was deprecated. | |
8a20485c | 74 | |
9f015efb | 75 | In Perl 5.10, the I<5005threads> model was removed from the Perl interpreter. |
43d3ddbe JH |
76 | |
77 | =head1 SYNOPSIS | |
78 | ||
9d40afd1 | 79 | use Thread qw(:DEFAULT async yield); |
43d3ddbe JH |
80 | |
81 | my $t = Thread->new(\&start_sub, @start_args); | |
82 | ||
83 | $result = $t->join; | |
43d3ddbe JH |
84 | $t->detach; |
85 | ||
86 | if ($t->done) { | |
87 | $t->join; | |
88 | } | |
89 | ||
90 | if($t->equal($another_thread)) { | |
9d40afd1 | 91 | # ... |
43d3ddbe JH |
92 | } |
93 | ||
94 | yield(); | |
95 | ||
9d40afd1 | 96 | my $tid = Thread->self->tid; |
43d3ddbe JH |
97 | |
98 | lock($scalar); | |
99 | lock(@array); | |
100 | lock(%hash); | |
101 | ||
9d40afd1 | 102 | my @list = Thread->list; |
43d3ddbe JH |
103 | |
104 | =head1 DESCRIPTION | |
105 | ||
9f015efb | 106 | The C<Thread> module provides multithreading support for Perl. |
43d3ddbe JH |
107 | |
108 | =head1 FUNCTIONS | |
109 | ||
110 | =over 8 | |
111 | ||
112 | =item $thread = Thread->new(\&start_sub) | |
113 | ||
114 | =item $thread = Thread->new(\&start_sub, LIST) | |
115 | ||
116 | C<new> starts a new thread of execution in the referenced subroutine. The | |
117 | optional list is passed as parameters to the subroutine. Execution | |
118 | continues in both the subroutine and the code after the C<new> call. | |
119 | ||
120 | C<Thread->new> returns a thread object representing the newly created | |
121 | thread. | |
122 | ||
123 | =item lock VARIABLE | |
124 | ||
dfca11dd | 125 | C<lock> places a lock on a variable until the lock goes out of scope. |
43d3ddbe JH |
126 | |
127 | If the variable is locked by another thread, the C<lock> call will | |
128 | block until it's available. C<lock> is recursive, so multiple calls | |
129 | to C<lock> are safe--the variable will remain locked until the | |
130 | outermost lock on the variable goes out of scope. | |
131 | ||
132 | Locks on variables only affect C<lock> calls--they do I<not> affect normal | |
133 | access to a variable. (Locks on subs are different, and covered in a bit.) | |
134 | If you really, I<really> want locks to block access, then go ahead and tie | |
135 | them to something and manage this yourself. This is done on purpose. | |
136 | While managing access to variables is a good thing, Perl doesn't force | |
137 | you out of its living room... | |
138 | ||
139 | If a container object, such as a hash or array, is locked, all the | |
140 | elements of that container are not locked. For example, if a thread | |
141 | does a C<lock @a>, any other thread doing a C<lock($a[12])> won't | |
142 | block. | |
143 | ||
43d3ddbe JH |
144 | Finally, C<lock> will traverse up references exactly I<one> level. |
145 | C<lock(\$a)> is equivalent to C<lock($a)>, while C<lock(\\$a)> is not. | |
146 | ||
147 | =item async BLOCK; | |
148 | ||
149 | C<async> creates a thread to execute the block immediately following | |
150 | it. This block is treated as an anonymous sub, and so must have a | |
151 | semi-colon after the closing brace. Like C<Thread->new>, C<async> | |
152 | returns a thread object. | |
153 | ||
154 | =item Thread->self | |
155 | ||
156 | The C<Thread-E<gt>self> function returns a thread object that represents | |
157 | the thread making the C<Thread-E<gt>self> call. | |
158 | ||
9d40afd1 JH |
159 | =item Thread->list |
160 | ||
161 | Returns a list of all non-joined, non-detached Thread objects. | |
162 | ||
43d3ddbe JH |
163 | =item cond_wait VARIABLE |
164 | ||
165 | The C<cond_wait> function takes a B<locked> variable as | |
166 | a parameter, unlocks the variable, and blocks until another thread | |
167 | does a C<cond_signal> or C<cond_broadcast> for that same locked | |
168 | variable. The variable that C<cond_wait> blocked on is relocked | |
169 | after the C<cond_wait> is satisfied. If there are multiple threads | |
170 | C<cond_wait>ing on the same variable, all but one will reblock waiting | |
191050aa | 171 | to re-acquire the lock on the variable. (So if you're only using |
43d3ddbe JH |
172 | C<cond_wait> for synchronization, give up the lock as soon as |
173 | possible.) | |
174 | ||
175 | =item cond_signal VARIABLE | |
176 | ||
177 | The C<cond_signal> function takes a locked variable as a parameter and | |
178 | unblocks one thread that's C<cond_wait>ing on that variable. If more than | |
179 | one thread is blocked in a C<cond_wait> on that variable, only one (and | |
180 | which one is indeterminate) will be unblocked. | |
181 | ||
182 | If there are no threads blocked in a C<cond_wait> on the variable, | |
183 | the signal is discarded. | |
184 | ||
185 | =item cond_broadcast VARIABLE | |
186 | ||
187 | The C<cond_broadcast> function works similarly to C<cond_signal>. | |
188 | C<cond_broadcast>, though, will unblock B<all> the threads that are | |
189 | blocked in a C<cond_wait> on the locked variable, rather than only | |
190 | one. | |
191 | ||
192 | =item yield | |
193 | ||
194 | The C<yield> function allows another thread to take control of the | |
195 | CPU. The exact results are implementation-dependent. | |
196 | ||
197 | =back | |
198 | ||
199 | =head1 METHODS | |
200 | ||
201 | =over 8 | |
202 | ||
203 | =item join | |
204 | ||
205 | C<join> waits for a thread to end and returns any values the thread | |
206 | exited with. C<join> will block until the thread has ended, though | |
207 | it won't block if the thread has already terminated. | |
208 | ||
209 | If the thread being C<join>ed C<die>d, the error it died with will | |
210 | be returned at this time. If you don't want the thread performing | |
211 | the C<join> to die as well, you should either wrap the C<join> in | |
212 | an C<eval> or use the C<eval> thread method instead of C<join>. | |
213 | ||
43d3ddbe JH |
214 | =item detach |
215 | ||
216 | C<detach> tells a thread that it is never going to be joined i.e. | |
217 | that all traces of its existence can be removed once it stops running. | |
218 | Errors in detached threads will not be visible anywhere - if you want | |
219 | to catch them, you should use $SIG{__DIE__} or something like that. | |
220 | ||
9d40afd1 | 221 | =item equal |
43d3ddbe JH |
222 | |
223 | C<equal> tests whether two thread objects represent the same thread and | |
224 | returns true if they do. | |
225 | ||
226 | =item tid | |
227 | ||
228 | The C<tid> method returns the tid of a thread. The tid is | |
229 | a monotonically increasing integer assigned when a thread is | |
230 | created. The main thread of a program will have a tid of zero, | |
231 | while subsequent threads will have tids assigned starting with one. | |
232 | ||
43d3ddbe JH |
233 | =item done |
234 | ||
235 | The C<done> method returns true if the thread you're checking has | |
9d40afd1 | 236 | finished, and false otherwise. |
43d3ddbe JH |
237 | |
238 | =back | |
239 | ||
9f015efb | 240 | =head1 DEFUNCT |
43d3ddbe | 241 | |
9f015efb JH |
242 | The following were implemented with I<5005threads>, but are no longer |
243 | available with I<ithreads>. | |
43d3ddbe | 244 | |
9f015efb | 245 | =over 8 |
43d3ddbe | 246 | |
9f015efb | 247 | =item lock(\&sub) |
43d3ddbe | 248 | |
9f015efb JH |
249 | With 5005threads, you could also C<lock> a sub such that any calls to that sub |
250 | from another thread would block until the lock was released. | |
43d3ddbe | 251 | |
9f015efb JH |
252 | Also, subroutines could be declared with the C<:locked> attribute which would |
253 | serialize access to the subroutine, but allowed different threads | |
254 | non-simultaneous access. | |
43d3ddbe | 255 | |
9f015efb | 256 | =item eval |
43d3ddbe | 257 | |
9f015efb JH |
258 | The C<eval> method wrapped an C<eval> around a C<join>, and so waited for a |
259 | thread to exit, passing along any values the thread might have returned and | |
260 | placing any errors into C<$@>. | |
43d3ddbe | 261 | |
9f015efb | 262 | =item flags |
43d3ddbe | 263 | |
9f015efb JH |
264 | The C<flags> method returned the flags for the thread - an integer value |
265 | corresponding to the internal flags for the thread. | |
43d3ddbe | 266 | |
9f015efb | 267 | =back |
43d3ddbe | 268 | |
9f015efb | 269 | =head1 SEE ALSO |
43d3ddbe | 270 | |
9f015efb | 271 | L<threads>, L<threads::shared>, L<Thread::Queue>, L<Thread::Semaphore> |
43d3ddbe | 272 | |
9f015efb | 273 | =cut |