Commit | Line | Data |
43d3ddbe |
1 | package Thread; |
2 | |
4038bebf |
3 | use strict; |
9f015efb |
4 | use warnings; |
014e6b2c |
5 | no warnings 'redefine'; |
4038bebf |
6 | |
014e6b2c |
7 | our $VERSION = '3.02'; |
9f015efb |
8 | $VERSION = eval $VERSION; |
4038bebf |
9 | |
43d3ddbe |
10 | BEGIN { |
11 | use Config; |
9f015efb |
12 | if (! $Config{useithreads}) { |
13 | die("This Perl not built to support threads\n"); |
14 | } |
43d3ddbe |
15 | } |
16 | |
9f015efb |
17 | use threads 'yield'; |
18 | use threads::shared; |
19 | |
43d3ddbe |
20 | require Exporter; |
9f015efb |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
76 | |
77 | =head1 SYNOPSIS |
78 | |
9d40afd1 |
79 | use Thread qw(:DEFAULT async yield); |
43d3ddbe |
80 | |
81 | my $t = Thread->new(\&start_sub, @start_args); |
82 | |
83 | $result = $t->join; |
43d3ddbe |
84 | $t->detach; |
85 | |
86 | if ($t->done) { |
87 | $t->join; |
88 | } |
89 | |
90 | if($t->equal($another_thread)) { |
9d40afd1 |
91 | # ... |
43d3ddbe |
92 | } |
93 | |
94 | yield(); |
95 | |
9d40afd1 |
96 | my $tid = Thread->self->tid; |
43d3ddbe |
97 | |
98 | lock($scalar); |
99 | lock(@array); |
100 | lock(%hash); |
101 | |
9d40afd1 |
102 | my @list = Thread->list; |
43d3ddbe |
103 | |
104 | =head1 DESCRIPTION |
105 | |
9f015efb |
106 | The C<Thread> module provides multithreading support for Perl. |
43d3ddbe |
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 |
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 |
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 |
159 | =item Thread->list |
160 | |
161 | Returns a list of all non-joined, non-detached Thread objects. |
162 | |
43d3ddbe |
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 |
171 | to reaquire the lock on the variable. (So if you're only using |
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 |
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 |
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 |
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 |
237 | |
238 | =back |
239 | |
9f015efb |
240 | =head1 DEFUNCT |
43d3ddbe |
241 | |
9f015efb |
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 |
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 |
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 |
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 |
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 |