1 | package threads;
|
---|
2 |
|
---|
3 | use 5.008;
|
---|
4 | use strict;
|
---|
5 | use warnings;
|
---|
6 | use Config;
|
---|
7 |
|
---|
8 | BEGIN {
|
---|
9 | unless ($Config{useithreads}) {
|
---|
10 | my @caller = caller(2);
|
---|
11 | die <<EOF;
|
---|
12 | $caller[1] line $caller[2]:
|
---|
13 |
|
---|
14 | This Perl hasn't been configured and built properly for the threads
|
---|
15 | module to work. (The 'useithreads' configuration option hasn't been used.)
|
---|
16 |
|
---|
17 | Having threads support requires all of Perl and all of the XS modules in
|
---|
18 | the Perl installation to be rebuilt, it is not just a question of adding
|
---|
19 | the threads module. (In other words, threaded and non-threaded Perls
|
---|
20 | are binary incompatible.)
|
---|
21 |
|
---|
22 | If you want to the use the threads module, please contact the people
|
---|
23 | who built your Perl.
|
---|
24 |
|
---|
25 | Cannot continue, aborting.
|
---|
26 | EOF
|
---|
27 | }
|
---|
28 | }
|
---|
29 |
|
---|
30 | use overload
|
---|
31 | '==' => \&equal,
|
---|
32 | 'fallback' => 1;
|
---|
33 |
|
---|
34 | BEGIN {
|
---|
35 | warn "Warning, threads::shared has already been loaded. ".
|
---|
36 | "To enable shared variables for these modules 'use threads' ".
|
---|
37 | "must be called before any of those modules are loaded\n"
|
---|
38 | if($threads::shared::threads_shared);
|
---|
39 | }
|
---|
40 |
|
---|
41 | require Exporter;
|
---|
42 | require DynaLoader;
|
---|
43 |
|
---|
44 | our @ISA = qw(Exporter DynaLoader);
|
---|
45 |
|
---|
46 | our %EXPORT_TAGS = ( all => [qw(yield)]);
|
---|
47 |
|
---|
48 | our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
|
---|
49 |
|
---|
50 | our @EXPORT = qw(
|
---|
51 | async
|
---|
52 | );
|
---|
53 | our $VERSION = '1.07';
|
---|
54 |
|
---|
55 |
|
---|
56 | # || 0 to ensure compatibility with previous versions
|
---|
57 | sub equal { ($_[0]->tid == $_[1]->tid) || 0 }
|
---|
58 |
|
---|
59 | # use "goto" trick to avoid pad problems from 5.8.1 (fixed in 5.8.2)
|
---|
60 | # should also be faster
|
---|
61 | sub async (&;@) { unshift @_,'threads'; goto &new }
|
---|
62 |
|
---|
63 | sub object {
|
---|
64 | return undef unless @_ > 1;
|
---|
65 | foreach (threads->list) {
|
---|
66 | return $_ if $_->tid == $_[1];
|
---|
67 | }
|
---|
68 | return undef;
|
---|
69 | }
|
---|
70 |
|
---|
71 | $threads::threads = 1;
|
---|
72 |
|
---|
73 | bootstrap threads $VERSION;
|
---|
74 |
|
---|
75 | # why document 'new' then use 'create' in the tests!
|
---|
76 | *create = \&new;
|
---|
77 |
|
---|
78 | # Preloaded methods go here.
|
---|
79 |
|
---|
80 | 1;
|
---|
81 | __END__
|
---|
82 |
|
---|
83 | =head1 NAME
|
---|
84 |
|
---|
85 | threads - Perl extension allowing use of interpreter based threads from perl
|
---|
86 |
|
---|
87 | =head1 SYNOPSIS
|
---|
88 |
|
---|
89 | use threads;
|
---|
90 |
|
---|
91 | sub start_thread {
|
---|
92 | print "Thread started\n";
|
---|
93 | }
|
---|
94 |
|
---|
95 | my $thread = threads->create("start_thread","argument");
|
---|
96 | my $thread2 = $thread->create(sub { print "I am a thread"},"argument");
|
---|
97 | my $thread3 = async { foreach (@files) { ... } };
|
---|
98 |
|
---|
99 | $thread->join();
|
---|
100 | $thread->detach();
|
---|
101 |
|
---|
102 | $thread = threads->self();
|
---|
103 | $thread = threads->object( $tid );
|
---|
104 |
|
---|
105 | $thread->tid();
|
---|
106 | threads->tid();
|
---|
107 | threads->self->tid();
|
---|
108 |
|
---|
109 | threads->yield();
|
---|
110 |
|
---|
111 | threads->list();
|
---|
112 |
|
---|
113 | =head1 DESCRIPTION
|
---|
114 |
|
---|
115 | Perl 5.6 introduced something called interpreter threads. Interpreter
|
---|
116 | threads are different from "5005threads" (the thread model of Perl
|
---|
117 | 5.005) by creating a new perl interpreter per thread and not sharing
|
---|
118 | any data or state between threads by default.
|
---|
119 |
|
---|
120 | Prior to perl 5.8 this has only been available to people embedding
|
---|
121 | perl and for emulating fork() on windows.
|
---|
122 |
|
---|
123 | The threads API is loosely based on the old Thread.pm API. It is very
|
---|
124 | important to note that variables are not shared between threads, all
|
---|
125 | variables are per default thread local. To use shared variables one
|
---|
126 | must use threads::shared.
|
---|
127 |
|
---|
128 | It is also important to note that you must enable threads by doing
|
---|
129 | C<use threads> as early as possible in the script itself and that it
|
---|
130 | is not possible to enable threading inside an C<eval "">, C<do>,
|
---|
131 | C<require>, or C<use>. In particular, if you are intending to share
|
---|
132 | variables with threads::shared, you must C<use threads> before you
|
---|
133 | C<use threads::shared> and C<threads> will emit a warning if you do
|
---|
134 | it the other way around.
|
---|
135 |
|
---|
136 | =over
|
---|
137 |
|
---|
138 | =item $thread = threads->create(function, LIST)
|
---|
139 |
|
---|
140 | This will create a new thread with the entry point function and give
|
---|
141 | it LIST as parameters. It will return the corresponding threads
|
---|
142 | object, or C<undef> if thread creation failed. The new() method is an
|
---|
143 | alias for create().
|
---|
144 |
|
---|
145 | =item $thread->join
|
---|
146 |
|
---|
147 | This will wait for the corresponding thread to join. When the thread
|
---|
148 | finishes, join() will return the return values of the entry point
|
---|
149 | function. If the thread has been detached, an error will be thrown.
|
---|
150 |
|
---|
151 | The context (void, scalar or list) of the thread creation is also the
|
---|
152 | context for join(). This means that if you intend to return an array
|
---|
153 | from a thread, you must use C<my ($thread) = threads->new(...)>, and
|
---|
154 | that if you intend to return a scalar, you must use C<my $thread = ...>.
|
---|
155 |
|
---|
156 | If the program exits without all other threads having been either
|
---|
157 | joined or detached, then a warning will be issued. (A program exits
|
---|
158 | either because one of its threads explicitly calls exit(), or in the
|
---|
159 | case of the main thread, reaches the end of the main program file.)
|
---|
160 |
|
---|
161 |
|
---|
162 | =item $thread->detach
|
---|
163 |
|
---|
164 | Will make the thread unjoinable, and cause any eventual return value
|
---|
165 | to be discarded.
|
---|
166 |
|
---|
167 | =item threads->self
|
---|
168 |
|
---|
169 | This will return the thread object for the current thread.
|
---|
170 |
|
---|
171 | =item $thread->tid
|
---|
172 |
|
---|
173 | This will return the id of the thread. Thread IDs are integers, with
|
---|
174 | the main thread in a program being 0. Currently Perl assigns a unique
|
---|
175 | tid to every thread ever created in your program, assigning the first
|
---|
176 | thread to be created a tid of 1, and increasing the tid by 1 for each
|
---|
177 | new thread that's created.
|
---|
178 |
|
---|
179 | NB the class method C<< threads->tid() >> is a quick way to get the
|
---|
180 | current thread id if you don't have your thread object handy.
|
---|
181 |
|
---|
182 | =item threads->object( tid )
|
---|
183 |
|
---|
184 | This will return the thread object for the thread associated with the
|
---|
185 | specified tid. Returns undef if there is no thread associated with the tid
|
---|
186 | or no tid is specified or the specified tid is undef.
|
---|
187 |
|
---|
188 | =item threads->yield();
|
---|
189 |
|
---|
190 | This is a suggestion to the OS to let this thread yield CPU time to other
|
---|
191 | threads. What actually happens is highly dependent upon the underlying
|
---|
192 | thread implementation.
|
---|
193 |
|
---|
194 | You may do C<use threads qw(yield)> then use just a bare C<yield> in your
|
---|
195 | code.
|
---|
196 |
|
---|
197 | =item threads->list();
|
---|
198 |
|
---|
199 | This will return a list of all non joined, non detached threads.
|
---|
200 |
|
---|
201 | =item async BLOCK;
|
---|
202 |
|
---|
203 | C<async> creates a thread to execute the block immediately following
|
---|
204 | it. This block is treated as an anonymous sub, and so must have a
|
---|
205 | semi-colon after the closing brace. Like C<< threads->new >>, C<async>
|
---|
206 | returns a thread object.
|
---|
207 |
|
---|
208 | =back
|
---|
209 |
|
---|
210 | =head1 WARNINGS
|
---|
211 |
|
---|
212 | =over 4
|
---|
213 |
|
---|
214 | =item A thread exited while %d other threads were still running
|
---|
215 |
|
---|
216 | A thread (not necessarily the main thread) exited while there were
|
---|
217 | still other threads running. Usually it's a good idea to first collect
|
---|
218 | the return values of the created threads by joining them, and only then
|
---|
219 | exit from the main thread.
|
---|
220 |
|
---|
221 | =back
|
---|
222 |
|
---|
223 | =head1 TODO
|
---|
224 |
|
---|
225 | The current implementation of threads has been an attempt to get
|
---|
226 | a correct threading system working that could be built on,
|
---|
227 | and optimized, in newer versions of perl.
|
---|
228 |
|
---|
229 | Currently the overhead of creating a thread is rather large,
|
---|
230 | also the cost of returning values can be large. These are areas
|
---|
231 | were there most likely will be work done to optimize what data
|
---|
232 | that needs to be cloned.
|
---|
233 |
|
---|
234 | =head1 BUGS
|
---|
235 |
|
---|
236 | =over
|
---|
237 |
|
---|
238 | =item Parent-Child threads.
|
---|
239 |
|
---|
240 | On some platforms it might not be possible to destroy "parent"
|
---|
241 | threads while there are still existing child "threads".
|
---|
242 |
|
---|
243 | This will possibly be fixed in later versions of perl.
|
---|
244 |
|
---|
245 | =item tid is I32
|
---|
246 |
|
---|
247 | The thread id is a 32 bit integer, it can potentially overflow.
|
---|
248 | This might be fixed in a later version of perl.
|
---|
249 |
|
---|
250 | =item Returning objects
|
---|
251 |
|
---|
252 | When you return an object the entire stash that the object is blessed
|
---|
253 | as well. This will lead to a large memory usage. The ideal situation
|
---|
254 | would be to detect the original stash if it existed.
|
---|
255 |
|
---|
256 | =item Creating threads inside BEGIN blocks
|
---|
257 |
|
---|
258 | Creating threads inside BEGIN blocks (or during the compilation phase
|
---|
259 | in general) does not work. (In Windows, trying to use fork() inside
|
---|
260 | BEGIN blocks is an equally losing proposition, since it has been
|
---|
261 | implemented in very much the same way as threads.)
|
---|
262 |
|
---|
263 | =item PERL_OLD_SIGNALS are not threadsafe, will not be.
|
---|
264 |
|
---|
265 | If your Perl has been built with PERL_OLD_SIGNALS (one has
|
---|
266 | to explicitly add that symbol to ccflags, see C<perl -V>),
|
---|
267 | signal handling is not threadsafe.
|
---|
268 |
|
---|
269 | =back
|
---|
270 |
|
---|
271 | =head1 AUTHOR and COPYRIGHT
|
---|
272 |
|
---|
273 | Arthur Bergman E<lt>sky at nanisky.comE<gt>
|
---|
274 |
|
---|
275 | threads is released under the same license as Perl.
|
---|
276 |
|
---|
277 | Thanks to
|
---|
278 |
|
---|
279 | Richard Soderberg E<lt>perl at crystalflame.netE<gt>
|
---|
280 | Helping me out tons, trying to find reasons for races and other weird bugs!
|
---|
281 |
|
---|
282 | Simon Cozens E<lt>simon at brecon.co.ukE<gt>
|
---|
283 | Being there to answer zillions of annoying questions
|
---|
284 |
|
---|
285 | Rocco Caputo E<lt>troc at netrus.netE<gt>
|
---|
286 |
|
---|
287 | Vipul Ved Prakash E<lt>mail at vipul.netE<gt>
|
---|
288 | Helping with debugging.
|
---|
289 |
|
---|
290 | please join [email protected] for more information
|
---|
291 |
|
---|
292 | =head1 SEE ALSO
|
---|
293 |
|
---|
294 | L<threads::shared>, L<perlthrtut>,
|
---|
295 | L<http://www.perl.com/pub/a/2002/06/11/threads.html>,
|
---|
296 | L<perlcall>, L<perlembed>, L<perlguts>
|
---|
297 |
|
---|
298 | =cut
|
---|