Avoid pack/unpack to produce the binary form of a utf8 string
[perl.git] / lib / Thread.pm
1 package Thread;
2
3 use strict;
4 use warnings;
5 no warnings 'redefine';
6
7 our $VERSION = '3.04';
8 $VERSION = eval $VERSION;
9
10 BEGIN {
11     use Config;
12     if (! $Config{useithreads}) {
13         die("This Perl not built to support threads\n");
14     }
15 }
16
17 use threads 'yield';
18 use threads::shared;
19
20 require Exporter;
21 our @ISA = qw(Exporter threads);
22 our @EXPORT = qw(cond_wait cond_broadcast cond_signal);
23 our @EXPORT_OK = qw(async yield);
24
25 sub async (&;@) { return Thread->new(shift); }
26
27 sub done { return ! shift->is_running(); }
28
29 sub eval  { die("'eval' not implemented with 'ithreads'\n"); };
30 sub flags { die("'flags' not implemented with 'ithreads'\n"); };
31
32 1;
33
34 __END__
35
36 =head1 NAME
37
38 Thread - Manipulate threads in Perl (for old code only)
39
40 =head1 DEPRECATED
41
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.
45
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.
53
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.
57
58 =head1 HISTORY
59
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>.
63
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".
67
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.
71
72 In Perl 5.8, the I<ithreads> model became available through the C<threads>
73 module, and the I<5005threads> model was deprecated.
74
75 In Perl 5.10, the I<5005threads> model was removed from the Perl interpreter.
76
77 =head1 SYNOPSIS
78
79     use Thread qw(:DEFAULT async yield);
80
81     my $t = Thread->new(\&start_sub, @start_args);
82
83     $result = $t->join;
84     $t->detach;
85
86     if ($t->done) {
87         $t->join;
88     }
89
90     if($t->equal($another_thread)) {
91         # ...
92     }
93
94     yield();
95
96     my $tid = Thread->self->tid;
97
98     lock($scalar);
99     lock(@array);
100     lock(%hash);
101
102     my @list = Thread->list;
103
104 =head1 DESCRIPTION
105
106 The C<Thread> module provides multithreading support for Perl.
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-&gt;new> returns a thread object representing the newly created
121 thread.
122
123 =item lock VARIABLE
124
125 C<lock> places a lock on a variable until the lock goes out of scope.
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
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-&gt;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
159 =item Thread->list
160
161 Returns a list of all non-joined, non-detached Thread objects.
162
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 re-acquire 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
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
221 =item equal
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
233 =item done
234
235 The C<done> method returns true if the thread you're checking has
236 finished, and false otherwise.
237
238 =back
239
240 =head1 DEFUNCT
241
242 The following were implemented with I<5005threads>, but are no longer
243 available with I<ithreads>.
244
245 =over 8
246
247 =item lock(\&sub)
248
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.
251
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.
255
256 =item eval
257
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<$@>.
261
262 =item flags
263
264 The C<flags> method returned the flags for the thread - an integer value
265 corresponding to the internal flags for the thread.
266
267 =back
268
269 =head1 SEE ALSO
270
271 L<threads>, L<threads::shared>, L<Thread::Queue>, L<Thread::Semaphore>
272
273 =cut