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