Commit | Line | Data |
d9bb3666 |
1 | package Thread; |
2 | require Exporter; |
9426adcd |
3 | use XSLoader (); |
17f410f9 |
4 | our($VERSION, @ISA, @EXPORT); |
52e1cb5e |
5 | |
6 | $VERSION = "1.0"; |
7 | |
9426adcd |
8 | @ISA = qw(Exporter); |
8f4f90ac |
9 | @EXPORT_OK = qw(yield cond_signal cond_broadcast cond_wait async); |
734689b1 |
10 | |
d516a115 |
11 | =head1 NAME |
12 | |
e7d08fc9 |
13 | Thread - manipulate threads in Perl (EXPERIMENTAL, subject to change) |
d516a115 |
14 | |
948a8a50 |
15 | =head1 CAVEAT |
16 | |
17 | The Thread extension requires Perl to be built in a particular way to |
18 | enable the older 5.005 threading model. Just to confuse matters, there |
19 | is an alternate threading model known as "ithreads" that does NOT |
20 | support this extension. If you are using a binary distribution such |
21 | as ActivePerl that is built with ithreads support, this extension CANNOT |
22 | be used. |
23 | |
d516a115 |
24 | =head1 SYNOPSIS |
25 | |
26 | use Thread; |
27 | |
28 | my $t = new Thread \&start_sub, @start_args; |
29 | |
23a4f76c |
30 | $result = $t->join; |
31 | $result = $t->eval; |
32 | $t->detach; |
8dcd6f7b |
33 | $flags = $t->flags; |
bbc7dcd2 |
34 | |
8dcd6f7b |
35 | if ($t->done) { |
36 | $t->join; |
37 | } |
d516a115 |
38 | |
23a4f76c |
39 | if($t->equal($another_thread)) { |
40 | # ... |
41 | } |
d516a115 |
42 | |
23a4f76c |
43 | my $tid = Thread->self->tid; |
d516a115 |
44 | my $tlist = Thread->list; |
45 | |
46 | lock($scalar); |
23a4f76c |
47 | yield(); |
d516a115 |
48 | |
49 | use Thread 'async'; |
50 | |
d516a115 |
51 | =head1 DESCRIPTION |
52 | |
2a4bf773 |
53 | WARNING: Threading is an experimental feature. Both the interface |
54 | and implementation are subject to change drastically. In fact, this |
55 | documentation describes the flavor of threads that was in version |
56 | 5.005. Perl 5.6.0 and later have the beginnings of support for |
57 | interpreter threads, which (when finished) is expected to be |
58 | significantly different from what is described here. The information |
59 | contained here may therefore soon be obsolete. Use at your own risk! |
23a4f76c |
60 | |
2a4bf773 |
61 | The C<Thread> module provides multithreading support for perl. |
e7d08fc9 |
62 | |
589fe9d5 |
63 | =head1 FUNCTIONS |
64 | |
65 | =over 8 |
66 | |
67 | =item new \&start_sub |
68 | |
69 | =item new \&start_sub, LIST |
70 | |
71 | C<new> starts a new thread of execution in the referenced subroutine. The |
72 | optional list is passed as parameters to the subroutine. Execution |
73 | continues in both the subroutine and the code after the C<new> call. |
74 | |
75 | C<new Thread> returns a thread object representing the newly created |
76 | thread. |
77 | |
78 | =item lock VARIABLE |
79 | |
80 | C<lock> places a lock on a variable until the lock goes out of scope. If |
81 | the variable is locked by another thread, the C<lock> call will block until |
82 | it's available. C<lock> is recursive, so multiple calls to C<lock> are |
83 | safe--the variable will remain locked until the outermost lock on the |
84 | variable goes out of scope. |
85 | |
86 | Locks on variables only affect C<lock> calls--they do I<not> affect normal |
87 | access to a variable. (Locks on subs are different, and covered in a bit) |
88 | If you really, I<really> want locks to block access, then go ahead and tie |
89 | them to something and manage this yourself. This is done on purpose. While |
90 | managing access to variables is a good thing, perl doesn't force you out of |
91 | its living room... |
92 | |
93 | If a container object, such as a hash or array, is locked, all the elements |
94 | of that container are not locked. For example, if a thread does a C<lock |
95 | @a>, any other thread doing a C<lock($a[12])> won't block. |
96 | |
97 | You may also C<lock> a sub, using C<lock &sub>. Any calls to that sub from |
98 | another thread will block until the lock is released. This behaviour is not |
0655b981 |
99 | equivalent to declaring the sub with the C<locked> attribute. The C<locked> |
100 | attribute serializes access to a subroutine, but allows different threads |
589fe9d5 |
101 | non-simultaneous access. C<lock &sub>, on the other hand, will not allow |
102 | I<any> other thread access for the duration of the lock. |
103 | |
104 | Finally, C<lock> will traverse up references exactly I<one> level. |
105 | C<lock(\$a)> is equivalent to C<lock($a)>, while C<lock(\\$a)> is not. |
106 | |
107 | =item async BLOCK; |
108 | |
109 | C<async> creates a thread to execute the block immediately following |
110 | it. This block is treated as an anonymous sub, and so must have a |
111 | semi-colon after the closing brace. Like C<new Thread>, C<async> returns a |
112 | thread object. |
113 | |
114 | =item Thread->self |
115 | |
116 | The C<Thread-E<gt>self> function returns a thread object that represents |
117 | the thread making the C<Thread-E<gt>self> call. |
118 | |
119 | =item Thread->list |
120 | |
121 | C<Thread-E<gt>list> returns a list of thread objects for all running and |
122 | finished but un-C<join>ed threads. |
123 | |
124 | =item cond_wait VARIABLE |
125 | |
126 | The C<cond_wait> function takes a B<locked> variable as a parameter, |
127 | unlocks the variable, and blocks until another thread does a C<cond_signal> |
128 | or C<cond_broadcast> for that same locked variable. The variable that |
129 | C<cond_wait> blocked on is relocked after the C<cond_wait> is satisfied. |
130 | If there are multiple threads C<cond_wait>ing on the same variable, all but |
131 | one will reblock waiting to reaquire the lock on the variable. (So if |
132 | you're only using C<cond_wait> for synchronization, give up the lock as |
133 | soon as possible) |
134 | |
135 | =item cond_signal VARIABLE |
136 | |
137 | The C<cond_signal> function takes a locked variable as a parameter and |
138 | unblocks one thread that's C<cond_wait>ing on that variable. If more than |
139 | one thread is blocked in a C<cond_wait> on that variable, only one (and |
140 | which one is indeterminate) will be unblocked. |
141 | |
142 | If there are no threads blocked in a C<cond_wait> on the variable, the |
143 | signal is discarded. |
144 | |
145 | =item cond_broadcast VARIABLE |
146 | |
7284b4ab |
147 | The C<cond_broadcast> function works similarly to C<cond_signal>. |
589fe9d5 |
148 | C<cond_broadcast>, though, will unblock B<all> the threads that are blocked |
149 | in a C<cond_wait> on the locked variable, rather than only one. |
150 | |
23a4f76c |
151 | =item yield |
152 | |
153 | The C<yield> function allows another thread to take control of the |
154 | CPU. The exact results are implementation-dependent. |
155 | |
589fe9d5 |
156 | =back |
157 | |
158 | =head1 METHODS |
159 | |
160 | =over 8 |
161 | |
162 | =item join |
163 | |
164 | C<join> waits for a thread to end and returns any values the thread exited |
165 | with. C<join> will block until the thread has ended, though it won't block |
166 | if the thread has already terminated. |
167 | |
168 | If the thread being C<join>ed C<die>d, the error it died with will be |
169 | returned at this time. If you don't want the thread performing the C<join> |
170 | to die as well, you should either wrap the C<join> in an C<eval> or use the |
171 | C<eval> thread method instead of C<join>. |
172 | |
173 | =item eval |
174 | |
175 | The C<eval> method wraps an C<eval> around a C<join>, and so waits for a |
176 | thread to exit, passing along any values the thread might have returned. |
177 | Errors, of course, get placed into C<$@>. |
178 | |
23a4f76c |
179 | =item detach |
180 | |
181 | C<detach> tells a thread that it is never going to be joined i.e. |
182 | that all traces of its existence can be removed once it stops running. |
183 | Errors in detached threads will not be visible anywhere - if you want |
184 | to catch them, you should use $SIG{__DIE__} or something like that. |
185 | |
186 | =item equal |
187 | |
188 | C<equal> tests whether two thread objects represent the same thread and |
189 | returns true if they do. |
190 | |
589fe9d5 |
191 | =item tid |
192 | |
193 | The C<tid> method returns the tid of a thread. The tid is a monotonically |
194 | increasing integer assigned when a thread is created. The main thread of a |
195 | program will have a tid of zero, while subsequent threads will have tids |
196 | assigned starting with one. |
197 | |
8dcd6f7b |
198 | =item flags |
199 | |
200 | The C<flags> method returns the flags for the thread. This is the |
201 | integer value corresponding to the internal flags for the thread, and |
e01a9ca0 |
202 | the value may not be all that meaningful to you. |
8dcd6f7b |
203 | |
204 | =item done |
205 | |
206 | The C<done> method returns true if the thread you're checking has |
207 | finished, and false otherwise. |
208 | |
a45bd81d |
209 | =back |
210 | |
589fe9d5 |
211 | =head1 LIMITATIONS |
212 | |
213 | The sequence number used to assign tids is a simple integer, and no |
214 | checking is done to make sure the tid isn't currently in use. If a program |
215 | creates more than 2^32 - 1 threads in a single run, threads may be assigned |
216 | duplicate tids. This limitation may be lifted in a future version of Perl. |
d516a115 |
217 | |
218 | =head1 SEE ALSO |
219 | |
0655b981 |
220 | L<attributes>, L<Thread::Queue>, L<Thread::Semaphore>, L<Thread::Specific>. |
d516a115 |
221 | |
222 | =cut |
223 | |
734689b1 |
224 | # |
225 | # Methods |
226 | # |
227 | |
228 | # |
229 | # Exported functions |
230 | # |
231 | sub async (&) { |
232 | return new Thread $_[0]; |
233 | } |
d9bb3666 |
234 | |
458fb581 |
235 | sub eval { |
236 | return eval { shift->join; }; |
237 | } |
238 | |
9426adcd |
239 | XSLoader::load 'Thread'; |
d9bb3666 |
240 | |
d9bb3666 |
241 | 1; |