threads(3pm)

1threads(3pm)           Perl Programmers Reference Guide           threads(3pm)
2
3
4

NAME

6       threads - Perl extension allowing use of interpreter based threads from
7       perl
8

SYNOPSIS

10           use threads;
11
12           sub start_thread {
13               print "Thread started\n";
14           }
15
16           my $thread  = threads->create("start_thread","argument");
17           my $thread2 = $thread->create(sub { print "I am a thread"},"argument");
18           my $thread3 = async { foreach (@files) { ... } };
19
20           $thread->join();
21           $thread->detach();
22
23           $thread = threads->self();
24           $thread = threads->object( $tid );
25
26           $thread->tid();
27           threads->tid();
28           threads->self->tid();
29
30           threads->yield();
31
32           threads->list();
33

DESCRIPTION

35       Perl 5.6 introduced something called interpreter threads.  Interpreter
36       threads are different from "5005threads" (the thread model of Perl
37       5.005) by creating a new perl interpreter per thread and not sharing
38       any data or state between threads by default.
39
40       Prior to perl 5.8 this has only been available to people embedding perl
41       and for emulating fork() on windows.
42
43       The threads API is loosely based on the old Thread.pm API. It is very
44       important to note that variables are not shared between threads, all
45       variables are per default thread local.  To use shared variables one
46       must use threads::shared.
47
48       It is also important to note that you must enable threads by doing "use
49       threads" as early as possible in the script itself and that it is not
50       possible to enable threading inside an "eval """, "do", "require", or
51       "use".  In particular, if you are intending to share variables with
52       threads::shared, you must "use threads" before you "use
53       threads::shared" and "threads" will emit a warning if you do it the
54       other way around.
55
56       $thread = threads->create(function, LIST)
57           This will create a new thread with the entry point function and
58           give it LIST as parameters.  It will return the corresponding
59           threads object, or "undef" if thread creation failed. The new()
60           method is an alias for create().
61
62       $thread->join
63           This will wait for the corresponding thread to join. When the
64           thread finishes, join() will return the return values of the entry
65           point function. If the thread has been detached, an error will be
66           thrown.
67
68           The context (void, scalar or list) of the thread creation is also
69           the context for join().  This means that if you intend to return an
70           array from a thread, you must use "my ($thread) =
71           threads-"new(...)>, and that if you intend to return a scalar, you
72           must use "my $thread = ...".
73
74           If the program exits without all other threads having been either
75           joined or detached, then a warning will be issued. (A program exits
76           either because one of its threads explicitly calls exit(), or in
77           the case of the main thread, reaches the end of the main program
78           file.)
79
80       $thread->detach
81           Will make the thread unjoinable, and cause any eventual return
82           value to be discarded.
83
84       threads->self
85           This will return the thread object for the current thread.
86
87       $thread->tid
88           This will return the id of the thread.  Thread IDs are integers,
89           with the main thread in a program being 0.  Currently Perl assigns
90           a unique tid to every thread ever created in your program, assign‐
91           ing the first thread to be created a tid of 1, and increasing the
92           tid by 1 for each new thread that's created.
93
94           NB the class method "threads->tid()" is a quick way to get the cur‐
95           rent thread id if you don't have your thread object handy.
96
97       threads->object( tid )
98           This will return the thread object for the thread associated with
99           the specified tid.  Returns undef if there is no thread associated
100           with the tid or no tid is specified or the specified tid is undef.
101
102       threads->yield();
103           This is a suggestion to the OS to let this thread yield CPU time to
104           other threads.  What actually happens is highly dependent upon the
105           underlying thread implementation.
106
107           You may do "use threads qw(yield)" then use just a bare "yield" in
108           your code.
109
110       threads->list();
111           This will return a list of all non joined, non detached threads.
112
113       async BLOCK;
114           "async" creates a thread to execute the block immediately following
115           it.  This block is treated as an anonymous sub, and so must have a
116           semi-colon after the closing brace. Like "threads->new", "async"
117           returns a thread object.
118

WARNINGS

120       A thread exited while %d other threads were still running
121           A thread (not necessarily the main thread) exited while there were
122           still other threads running.  Usually it's a good idea to first
123           collect the return values of the created threads by joining them,
124           and only then exit from the main thread.
125

TODO

127       The current implementation of threads has been an attempt to get a cor‐
128       rect threading system working that could be built on, and optimized, in
129       newer versions of perl.
130
131       Currently the overhead of creating a thread is rather large, also the
132       cost of returning values can be large. These are areas were there most
133       likely will be work done to optimize what data that needs to be cloned.
134

BUGS

136       Parent-Child threads.
137           On some platforms it might not be possible to destroy "parent"
138           threads while there are still existing child "threads".
139
140           This will possibly be fixed in later versions of perl.
141
142       tid is I32
143           The thread id is a 32 bit integer, it can potentially overflow.
144           This might be fixed in a later version of perl.
145
146       Returning objects
147           When you return an object the entire stash that the object is
148           blessed as well.  This will lead to a large memory usage.  The
149           ideal situation would be to detect the original stash if it
150           existed.
151
152       Creating threads inside BEGIN blocks
153           Creating threads inside BEGIN blocks (or during the compilation
154           phase in general) does not work.  (In Windows, trying to use fork()
155           inside BEGIN blocks is an equally losing proposition, since it has
156           been implemented in very much the same way as threads.)
157
158       PERL_OLD_SIGNALS are not threadsafe, will not be.
159           If your Perl has been built with PERL_OLD_SIGNALS (one has to
160           explicitly add that symbol to ccflags, see "perl -V"), signal han‐
161           dling is not threadsafe.
162

AUTHOR and COPYRIGHT

164       Arthur Bergman <sky at nanisky.com>
165
166       threads is released under the same license as Perl.
167
168       Thanks to
169
170       Richard Soderberg <perl at crystalflame.net> Helping me out tons, try‐
171       ing to find reasons for races and other weird bugs!
172
173       Simon Cozens <simon at brecon.co.uk> Being there to answer zillions of
174       annoying questions
175
176       Rocco Caputo <troc at netrus.net>
177
178       Vipul Ved Prakash <mail at vipul.net> Helping with debugging.
179
180       please join perl-ithreads@perl.org for more information
181