| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "threads 3perl" |
| 58 |
.TH threads 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
threads \- Perl interpreter\-based threads |
| 65 |
.SH VERSION |
| 66 |
.IX Header "VERSION" |
| 67 |
This document describes threads version 2.40 |
| 68 |
.SH WARNING |
| 69 |
.IX Header "WARNING" |
| 70 |
The "interpreter-based threads" provided by Perl are not the fast, lightweight |
| 71 |
system for multitasking that one might expect or hope for. Threads are |
| 72 |
implemented in a way that makes them easy to misuse. Few people know how to |
| 73 |
use them correctly or will be able to provide help. |
| 74 |
.PP |
| 75 |
The use of interpreter-based threads in perl is officially |
| 76 |
discouraged. |
| 77 |
.SH SYNOPSIS |
| 78 |
.IX Header "SYNOPSIS" |
| 79 |
.Vb 4 |
| 80 |
\& use threads (\*(Aqyield\*(Aq, |
| 81 |
\& \*(Aqstack_size\*(Aq => 64*4096, |
| 82 |
\& \*(Aqexit\*(Aq => \*(Aqthreads_only\*(Aq, |
| 83 |
\& \*(Aqstringify\*(Aq); |
| 84 |
\& |
| 85 |
\& sub start_thread { |
| 86 |
\& my @args = @_; |
| 87 |
\& print(\*(AqThread started: \*(Aq, join(\*(Aq \*(Aq, @args), "\en"); |
| 88 |
\& } |
| 89 |
\& my $thr = threads\->create(\*(Aqstart_thread\*(Aq, \*(Aqargument\*(Aq); |
| 90 |
\& $thr\->join(); |
| 91 |
\& |
| 92 |
\& threads\->create(sub { print("I am a thread\en"); })\->join(); |
| 93 |
\& |
| 94 |
\& my $thr2 = async { foreach (@files) { ... } }; |
| 95 |
\& $thr2\->join(); |
| 96 |
\& if (my $err = $thr2\->error()) { |
| 97 |
\& warn("Thread error: $err\en"); |
| 98 |
\& } |
| 99 |
\& |
| 100 |
\& # Invoke thread in list context (implicit) so it can return a list |
| 101 |
\& my ($thr) = threads\->create(sub { return (qw/a b c/); }); |
| 102 |
\& # or specify list context explicitly |
| 103 |
\& my $thr = threads\->create({\*(Aqcontext\*(Aq => \*(Aqlist\*(Aq}, |
| 104 |
\& sub { return (qw/a b c/); }); |
| 105 |
\& my @results = $thr\->join(); |
| 106 |
\& |
| 107 |
\& $thr\->detach(); |
| 108 |
\& |
| 109 |
\& # Get a thread\*(Aqs object |
| 110 |
\& $thr = threads\->self(); |
| 111 |
\& $thr = threads\->object($tid); |
| 112 |
\& |
| 113 |
\& # Get a thread\*(Aqs ID |
| 114 |
\& $tid = threads\->tid(); |
| 115 |
\& $tid = $thr\->tid(); |
| 116 |
\& $tid = "$thr"; |
| 117 |
\& |
| 118 |
\& # Give other threads a chance to run |
| 119 |
\& threads\->yield(); |
| 120 |
\& yield(); |
| 121 |
\& |
| 122 |
\& # Lists of non\-detached threads |
| 123 |
\& my @threads = threads\->list(); |
| 124 |
\& my $thread_count = threads\->list(); |
| 125 |
\& |
| 126 |
\& my @running = threads\->list(threads::running); |
| 127 |
\& my @joinable = threads\->list(threads::joinable); |
| 128 |
\& |
| 129 |
\& # Test thread objects |
| 130 |
\& if ($thr1 == $thr2) { |
| 131 |
\& ... |
| 132 |
\& } |
| 133 |
\& |
| 134 |
\& # Manage thread stack size |
| 135 |
\& $stack_size = threads\->get_stack_size(); |
| 136 |
\& $old_size = threads\->set_stack_size(32*4096); |
| 137 |
\& |
| 138 |
\& # Create a thread with a specific context and stack size |
| 139 |
\& my $thr = threads\->create({ \*(Aqcontext\*(Aq => \*(Aqlist\*(Aq, |
| 140 |
\& \*(Aqstack_size\*(Aq => 32*4096, |
| 141 |
\& \*(Aqexit\*(Aq => \*(Aqthread_only\*(Aq }, |
| 142 |
\& \e&foo); |
| 143 |
\& |
| 144 |
\& # Get thread\*(Aqs context |
| 145 |
\& my $wantarray = $thr\->wantarray(); |
| 146 |
\& |
| 147 |
\& # Check thread\*(Aqs state |
| 148 |
\& if ($thr\->is_running()) { |
| 149 |
\& sleep(1); |
| 150 |
\& } |
| 151 |
\& if ($thr\->is_joinable()) { |
| 152 |
\& $thr\->join(); |
| 153 |
\& } |
| 154 |
\& |
| 155 |
\& # Send a signal to a thread |
| 156 |
\& $thr\->kill(\*(AqSIGUSR1\*(Aq); |
| 157 |
\& |
| 158 |
\& # Exit a thread |
| 159 |
\& threads\->exit(); |
| 160 |
.Ve |
| 161 |
.SH DESCRIPTION |
| 162 |
.IX Header "DESCRIPTION" |
| 163 |
Since Perl 5.8, thread programming has been available using a model called |
| 164 |
\&\fIinterpreter threads\fR which provides a new Perl interpreter for each |
| 165 |
thread, and, by default, results in no data or state information being shared |
| 166 |
between threads. |
| 167 |
.PP |
| 168 |
(Prior to Perl 5.8, \fI5005threads\fR was available through the \f(CW\*(C`Thread.pm\*(C'\fR API. |
| 169 |
This threading model has been deprecated, and was removed as of Perl 5.10.0.) |
| 170 |
.PP |
| 171 |
As just mentioned, all variables are, by default, thread local. To use shared |
| 172 |
variables, you need to also load threads::shared: |
| 173 |
.PP |
| 174 |
.Vb 2 |
| 175 |
\& use threads; |
| 176 |
\& use threads::shared; |
| 177 |
.Ve |
| 178 |
.PP |
| 179 |
When loading threads::shared, you must \f(CW\*(C`use threads\*(C'\fR before you |
| 180 |
\&\f(CW\*(C`use threads::shared\*(C'\fR. (\f(CW\*(C`threads\*(C'\fR will emit a warning if you do it the |
| 181 |
other way around.) |
| 182 |
.PP |
| 183 |
It is strongly recommended that you enable threads via \f(CW\*(C`use threads\*(C'\fR as early |
| 184 |
as possible in your script. |
| 185 |
.PP |
| 186 |
If needed, scripts can be written so as to run on both threaded and |
| 187 |
non-threaded Perls: |
| 188 |
.PP |
| 189 |
.Vb 8 |
| 190 |
\& my $can_use_threads = eval \*(Aquse threads; 1\*(Aq; |
| 191 |
\& if ($can_use_threads) { |
| 192 |
\& # Do processing using threads |
| 193 |
\& ... |
| 194 |
\& } else { |
| 195 |
\& # Do it without using threads |
| 196 |
\& ... |
| 197 |
\& } |
| 198 |
.Ve |
| 199 |
.ie n .IP "$thr = threads\->create(FUNCTION, ARGS)" 4 |
| 200 |
.el .IP "\f(CW$thr\fR = threads\->create(FUNCTION, ARGS)" 4 |
| 201 |
.IX Item "$thr = threads->create(FUNCTION, ARGS)" |
| 202 |
This will create a new thread that will begin execution with the specified |
| 203 |
entry point function, and give it the \fIARGS\fR list as parameters. It will |
| 204 |
return the corresponding threads object, or \f(CW\*(C`undef\*(C'\fR if thread creation failed. |
| 205 |
.Sp |
| 206 |
\&\fIFUNCTION\fR may either be the name of a function, an anonymous subroutine, or |
| 207 |
a code ref. |
| 208 |
.Sp |
| 209 |
.Vb 5 |
| 210 |
\& my $thr = threads\->create(\*(Aqfunc_name\*(Aq, ...); |
| 211 |
\& # or |
| 212 |
\& my $thr = threads\->create(sub { ... }, ...); |
| 213 |
\& # or |
| 214 |
\& my $thr = threads\->create(\e&func, ...); |
| 215 |
.Ve |
| 216 |
.Sp |
| 217 |
The \f(CW\*(C`\->new()\*(C'\fR method is an alias for \f(CW\*(C`\->create()\*(C'\fR. |
| 218 |
.ie n .IP $thr\->\fBjoin()\fR 4 |
| 219 |
.el .IP \f(CW$thr\fR\->\fBjoin()\fR 4 |
| 220 |
.IX Item "$thr->join()" |
| 221 |
This will wait for the corresponding thread to complete its execution. When |
| 222 |
the thread finishes, \f(CW\*(C`\->join()\*(C'\fR will return the return value(s) of the |
| 223 |
entry point function. |
| 224 |
.Sp |
| 225 |
The context (void, scalar or list) for the return value(s) for \f(CW\*(C`\->join()\*(C'\fR |
| 226 |
is determined at the time of thread creation. |
| 227 |
.Sp |
| 228 |
.Vb 10 |
| 229 |
\& # Create thread in list context (implicit) |
| 230 |
\& my ($thr1) = threads\->create(sub { |
| 231 |
\& my @results = qw(a b c); |
| 232 |
\& return (@results); |
| 233 |
\& }); |
| 234 |
\& # or (explicit) |
| 235 |
\& my $thr1 = threads\->create({\*(Aqcontext\*(Aq => \*(Aqlist\*(Aq}, |
| 236 |
\& sub { |
| 237 |
\& my @results = qw(a b c); |
| 238 |
\& return (@results); |
| 239 |
\& }); |
| 240 |
\& # Retrieve list results from thread |
| 241 |
\& my @res1 = $thr1\->join(); |
| 242 |
\& |
| 243 |
\& # Create thread in scalar context (implicit) |
| 244 |
\& my $thr2 = threads\->create(sub { |
| 245 |
\& my $result = 42; |
| 246 |
\& return ($result); |
| 247 |
\& }); |
| 248 |
\& # Retrieve scalar result from thread |
| 249 |
\& my $res2 = $thr2\->join(); |
| 250 |
\& |
| 251 |
\& # Create a thread in void context (explicit) |
| 252 |
\& my $thr3 = threads\->create({\*(Aqvoid\*(Aq => 1}, |
| 253 |
\& sub { print("Hello, world\en"); }); |
| 254 |
\& # Join the thread in void context (i.e., no return value) |
| 255 |
\& $thr3\->join(); |
| 256 |
.Ve |
| 257 |
.Sp |
| 258 |
See "THREAD CONTEXT" for more details. |
| 259 |
.Sp |
| 260 |
If the program exits without all threads having either been joined or |
| 261 |
detached, then a warning will be issued. |
| 262 |
.Sp |
| 263 |
Calling \f(CW\*(C`\->join()\*(C'\fR or \f(CW\*(C`\->detach()\*(C'\fR on an already joined thread will |
| 264 |
cause an error to be thrown. |
| 265 |
.ie n .IP $thr\->\fBdetach()\fR 4 |
| 266 |
.el .IP \f(CW$thr\fR\->\fBdetach()\fR 4 |
| 267 |
.IX Item "$thr->detach()" |
| 268 |
Makes the thread unjoinable, and causes any eventual return value to be |
| 269 |
discarded. When the program exits, any detached threads that are still |
| 270 |
running are silently terminated. |
| 271 |
.Sp |
| 272 |
If the program exits without all threads having either been joined or |
| 273 |
detached, then a warning will be issued. |
| 274 |
.Sp |
| 275 |
Calling \f(CW\*(C`\->join()\*(C'\fR or \f(CW\*(C`\->detach()\*(C'\fR on an already detached thread |
| 276 |
will cause an error to be thrown. |
| 277 |
.IP threads\->\fBdetach()\fR 4 |
| 278 |
.IX Item "threads->detach()" |
| 279 |
Class method that allows a thread to detach itself. |
| 280 |
.IP threads\->\fBself()\fR 4 |
| 281 |
.IX Item "threads->self()" |
| 282 |
Class method that allows a thread to obtain its own \fIthreads\fR object. |
| 283 |
.ie n .IP $thr\->\fBtid()\fR 4 |
| 284 |
.el .IP \f(CW$thr\fR\->\fBtid()\fR 4 |
| 285 |
.IX Item "$thr->tid()" |
| 286 |
Returns the ID of the thread. Thread IDs are unique integers with the main |
| 287 |
thread in a program being 0, and incrementing by 1 for every thread created. |
| 288 |
.IP threads\->\fBtid()\fR 4 |
| 289 |
.IX Item "threads->tid()" |
| 290 |
Class method that allows a thread to obtain its own ID. |
| 291 |
.IP """$thr""" 4 |
| 292 |
.IX Item """$thr""" |
| 293 |
If you add the \f(CW\*(C`stringify\*(C'\fR import option to your \f(CW\*(C`use threads\*(C'\fR declaration, |
| 294 |
then using a threads object in a string or a string context (e.g., as a hash |
| 295 |
key) will cause its ID to be used as the value: |
| 296 |
.Sp |
| 297 |
.Vb 1 |
| 298 |
\& use threads qw(stringify); |
| 299 |
\& |
| 300 |
\& my $thr = threads\->create(...); |
| 301 |
\& print("Thread $thr started\en"); # Prints: Thread 1 started |
| 302 |
.Ve |
| 303 |
.IP threads\->object($tid) 4 |
| 304 |
.IX Item "threads->object($tid)" |
| 305 |
This will return the \fIthreads\fR object for the \fIactive\fR thread associated |
| 306 |
with the specified thread ID. If \f(CW$tid\fR is the value for the current thread, |
| 307 |
then this call works the same as \f(CW\*(C`\->self()\*(C'\fR. Otherwise, returns \f(CW\*(C`undef\*(C'\fR |
| 308 |
if there is no thread associated with the TID, if the thread is joined or |
| 309 |
detached, if no TID is specified or if the specified TID is undef. |
| 310 |
.IP threads\->\fByield()\fR 4 |
| 311 |
.IX Item "threads->yield()" |
| 312 |
This is a suggestion to the OS to let this thread yield CPU time to other |
| 313 |
threads. What actually happens is highly dependent upon the underlying |
| 314 |
thread implementation. |
| 315 |
.Sp |
| 316 |
You may do \f(CW\*(C`use threads qw(yield)\*(C'\fR, and then just use \f(CWyield()\fR in your |
| 317 |
code. |
| 318 |
.IP threads\->\fBlist()\fR 4 |
| 319 |
.IX Item "threads->list()" |
| 320 |
.PD 0 |
| 321 |
.IP threads\->list(threads::all) 4 |
| 322 |
.IX Item "threads->list(threads::all)" |
| 323 |
.IP threads\->list(threads::running) 4 |
| 324 |
.IX Item "threads->list(threads::running)" |
| 325 |
.IP threads\->list(threads::joinable) 4 |
| 326 |
.IX Item "threads->list(threads::joinable)" |
| 327 |
.PD |
| 328 |
With no arguments (or using \f(CW\*(C`threads::all\*(C'\fR) and in a list context, returns a |
| 329 |
list of all non-joined, non-detached \fIthreads\fR objects. In a scalar context, |
| 330 |
returns a count of the same. |
| 331 |
.Sp |
| 332 |
With a \fItrue\fR argument (using \f(CW\*(C`threads::running\*(C'\fR), returns a list of all |
| 333 |
non-joined, non-detached \fIthreads\fR objects that are still running. |
| 334 |
.Sp |
| 335 |
With a \fIfalse\fR argument (using \f(CW\*(C`threads::joinable\*(C'\fR), returns a list of all |
| 336 |
non-joined, non-detached \fIthreads\fR objects that have finished running (i.e., |
| 337 |
for which \f(CW\*(C`\->join()\*(C'\fR will not \fIblock\fR). |
| 338 |
.ie n .IP $thr1\->equal($thr2) 4 |
| 339 |
.el .IP \f(CW$thr1\fR\->equal($thr2) 4 |
| 340 |
.IX Item "$thr1->equal($thr2)" |
| 341 |
Tests if two threads objects are the same thread or not. This is overloaded |
| 342 |
to the more natural forms: |
| 343 |
.Sp |
| 344 |
.Vb 7 |
| 345 |
\& if ($thr1 == $thr2) { |
| 346 |
\& print("Threads are the same\en"); |
| 347 |
\& } |
| 348 |
\& # or |
| 349 |
\& if ($thr1 != $thr2) { |
| 350 |
\& print("Threads differ\en"); |
| 351 |
\& } |
| 352 |
.Ve |
| 353 |
.Sp |
| 354 |
(Thread comparison is based on thread IDs.) |
| 355 |
.IP "async BLOCK;" 4 |
| 356 |
.IX Item "async BLOCK;" |
| 357 |
\&\f(CW\*(C`async\*(C'\fR creates a thread to execute the block immediately following |
| 358 |
it. This block is treated as an anonymous subroutine, and so must have a |
| 359 |
semicolon after the closing brace. Like \f(CW\*(C`threads\->create()\*(C'\fR, \f(CW\*(C`async\*(C'\fR |
| 360 |
returns a \fIthreads\fR object. |
| 361 |
.ie n .IP $thr\->\fBerror()\fR 4 |
| 362 |
.el .IP \f(CW$thr\fR\->\fBerror()\fR 4 |
| 363 |
.IX Item "$thr->error()" |
| 364 |
Threads are executed in an \f(CW\*(C`eval\*(C'\fR context. This method will return \f(CW\*(C`undef\*(C'\fR |
| 365 |
if the thread terminates \fInormally\fR. Otherwise, it returns the value of |
| 366 |
\&\f(CW$@\fR associated with the thread's execution status in its \f(CW\*(C`eval\*(C'\fR context. |
| 367 |
.ie n .IP $thr\->\fB_handle()\fR 4 |
| 368 |
.el .IP \f(CW$thr\fR\->\fB_handle()\fR 4 |
| 369 |
.IX Item "$thr->_handle()" |
| 370 |
This \fIprivate\fR method returns a pointer (i.e., the memory location expressed |
| 371 |
as an unsigned integer) to the internal thread structure associated with a |
| 372 |
threads object. For Win32, this is a pointer to the \f(CW\*(C`HANDLE\*(C'\fR value returned |
| 373 |
by \f(CW\*(C`CreateThread\*(C'\fR (i.e., \f(CW\*(C`HANDLE *\*(C'\fR); for other platforms, it is a pointer |
| 374 |
to the \f(CW\*(C`pthread_t\*(C'\fR structure used in the \f(CW\*(C`pthread_create\*(C'\fR call (i.e., |
| 375 |
\&\f(CW\*(C`pthread_t *\*(C'\fR). |
| 376 |
.Sp |
| 377 |
This method is of no use for general Perl threads programming. Its intent is |
| 378 |
to provide other (XS-based) thread modules with the capability to access, and |
| 379 |
possibly manipulate, the underlying thread structure associated with a Perl |
| 380 |
thread. |
| 381 |
.IP threads\->\fB_handle()\fR 4 |
| 382 |
.IX Item "threads->_handle()" |
| 383 |
Class method that allows a thread to obtain its own \fIhandle\fR. |
| 384 |
.SH "EXITING A THREAD" |
| 385 |
.IX Header "EXITING A THREAD" |
| 386 |
The usual method for terminating a thread is to |
| 387 |
\&\fBreturn()\fR from the entry point function with the |
| 388 |
appropriate return value(s). |
| 389 |
.IP threads\->\fBexit()\fR 4 |
| 390 |
.IX Item "threads->exit()" |
| 391 |
If needed, a thread can be exited at any time by calling |
| 392 |
\&\f(CW\*(C`threads\->exit()\*(C'\fR. This will cause the thread to return \f(CW\*(C`undef\*(C'\fR in a |
| 393 |
scalar context, or the empty list in a list context. |
| 394 |
.Sp |
| 395 |
When called from the \fImain\fR thread, this behaves the same as \f(CWexit(0)\fR. |
| 396 |
.IP threads\->exit(status) 4 |
| 397 |
.IX Item "threads->exit(status)" |
| 398 |
When called from a thread, this behaves like \f(CW\*(C`threads\->exit()\*(C'\fR (i.e., the |
| 399 |
exit status code is ignored). |
| 400 |
.Sp |
| 401 |
When called from the \fImain\fR thread, this behaves the same as \f(CWexit(status)\fR. |
| 402 |
.IP \fBdie()\fR 4 |
| 403 |
.IX Item "die()" |
| 404 |
Calling \f(CWdie()\fR in a thread indicates an abnormal exit for the thread. Any |
| 405 |
\&\f(CW$SIG{_\|_DIE_\|_}\fR handler in the thread will be called first, and then the |
| 406 |
thread will exit with a warning message that will contain any arguments passed |
| 407 |
in the \f(CWdie()\fR call. |
| 408 |
.IP exit(status) 4 |
| 409 |
.IX Item "exit(status)" |
| 410 |
Calling \fBexit()\fR inside a thread causes the whole |
| 411 |
application to terminate. Because of this, the use of \f(CWexit()\fR inside |
| 412 |
threaded code, or in modules that might be used in threaded applications, is |
| 413 |
strongly discouraged. |
| 414 |
.Sp |
| 415 |
If \f(CWexit()\fR really is needed, then consider using the following: |
| 416 |
.Sp |
| 417 |
.Vb 2 |
| 418 |
\& threads\->exit() if threads\->can(\*(Aqexit\*(Aq); # Thread friendly |
| 419 |
\& exit(status); |
| 420 |
.Ve |
| 421 |
.IP "use threads 'exit' => 'threads_only'" 4 |
| 422 |
.IX Item "use threads 'exit' => 'threads_only'" |
| 423 |
This globally overrides the default behavior of calling \f(CWexit()\fR inside a |
| 424 |
thread, and effectively causes such calls to behave the same as |
| 425 |
\&\f(CW\*(C`threads\->exit()\*(C'\fR. In other words, with this setting, calling \f(CWexit()\fR |
| 426 |
causes only the thread to terminate. |
| 427 |
.Sp |
| 428 |
Because of its global effect, this setting should not be used inside modules |
| 429 |
or the like. |
| 430 |
.Sp |
| 431 |
The \fImain\fR thread is unaffected by this setting. |
| 432 |
.IP "threads\->create({'exit' => 'thread_only'}, ...)" 4 |
| 433 |
.IX Item "threads->create({'exit' => 'thread_only'}, ...)" |
| 434 |
This overrides the default behavior of \f(CWexit()\fR inside the newly created |
| 435 |
thread only. |
| 436 |
.ie n .IP $thr\->set_thread_exit_only(boolean) 4 |
| 437 |
.el .IP \f(CW$thr\fR\->set_thread_exit_only(boolean) 4 |
| 438 |
.IX Item "$thr->set_thread_exit_only(boolean)" |
| 439 |
This can be used to change the \fIexit thread only\fR behavior for a thread after |
| 440 |
it has been created. With a \fItrue\fR argument, \f(CWexit()\fR will cause only the |
| 441 |
thread to exit. With a \fIfalse\fR argument, \f(CWexit()\fR will terminate the |
| 442 |
application. |
| 443 |
.Sp |
| 444 |
The \fImain\fR thread is unaffected by this call. |
| 445 |
.IP threads\->set_thread_exit_only(boolean) 4 |
| 446 |
.IX Item "threads->set_thread_exit_only(boolean)" |
| 447 |
Class method for use inside a thread to change its own behavior for \f(CWexit()\fR. |
| 448 |
.Sp |
| 449 |
The \fImain\fR thread is unaffected by this call. |
| 450 |
.SH "THREAD STATE" |
| 451 |
.IX Header "THREAD STATE" |
| 452 |
The following boolean methods are useful in determining the \fIstate\fR of a |
| 453 |
thread. |
| 454 |
.ie n .IP $thr\->\fBis_running()\fR 4 |
| 455 |
.el .IP \f(CW$thr\fR\->\fBis_running()\fR 4 |
| 456 |
.IX Item "$thr->is_running()" |
| 457 |
Returns true if a thread is still running (i.e., if its entry point function |
| 458 |
has not yet finished or exited). |
| 459 |
.ie n .IP $thr\->\fBis_joinable()\fR 4 |
| 460 |
.el .IP \f(CW$thr\fR\->\fBis_joinable()\fR 4 |
| 461 |
.IX Item "$thr->is_joinable()" |
| 462 |
Returns true if the thread has finished running, is not detached and has not |
| 463 |
yet been joined. In other words, the thread is ready to be joined, and a call |
| 464 |
to \f(CW\*(C`$thr\->join()\*(C'\fR will not \fIblock\fR. |
| 465 |
.ie n .IP $thr\->\fBis_detached()\fR 4 |
| 466 |
.el .IP \f(CW$thr\fR\->\fBis_detached()\fR 4 |
| 467 |
.IX Item "$thr->is_detached()" |
| 468 |
Returns true if the thread has been detached. |
| 469 |
.IP threads\->\fBis_detached()\fR 4 |
| 470 |
.IX Item "threads->is_detached()" |
| 471 |
Class method that allows a thread to determine whether or not it is detached. |
| 472 |
.SH "THREAD CONTEXT" |
| 473 |
.IX Header "THREAD CONTEXT" |
| 474 |
As with subroutines, the type of value returned from a thread's entry point |
| 475 |
function may be determined by the thread's \fIcontext\fR: list, scalar or void. |
| 476 |
The thread's context is determined at thread creation. This is necessary so |
| 477 |
that the context is available to the entry point function via |
| 478 |
\&\fBwantarray()\fR. The thread may then specify a value of |
| 479 |
the appropriate type to be returned from \f(CW\*(C`\->join()\*(C'\fR. |
| 480 |
.SS "Explicit context" |
| 481 |
.IX Subsection "Explicit context" |
| 482 |
Because thread creation and thread joining may occur in different contexts, it |
| 483 |
may be desirable to state the context explicitly to the thread's entry point |
| 484 |
function. This may be done by calling \f(CW\*(C`\->create()\*(C'\fR with a hash reference |
| 485 |
as the first argument: |
| 486 |
.PP |
| 487 |
.Vb 3 |
| 488 |
\& my $thr = threads\->create({\*(Aqcontext\*(Aq => \*(Aqlist\*(Aq}, \e&foo); |
| 489 |
\& ... |
| 490 |
\& my @results = $thr\->join(); |
| 491 |
.Ve |
| 492 |
.PP |
| 493 |
In the above, the threads object is returned to the parent thread in scalar |
| 494 |
context, and the thread's entry point function \f(CW\*(C`foo\*(C'\fR will be called in list |
| 495 |
(array) context such that the parent thread can receive a list (array) from |
| 496 |
the \f(CW\*(C`\->join()\*(C'\fR call. (\f(CW\*(Aqarray\*(Aq\fR is synonymous with \f(CW\*(Aqlist\*(Aq\fR.) |
| 497 |
.PP |
| 498 |
Similarly, if you need the threads object, but your thread will not be |
| 499 |
returning a value (i.e., \fIvoid\fR context), you would do the following: |
| 500 |
.PP |
| 501 |
.Vb 3 |
| 502 |
\& my $thr = threads\->create({\*(Aqcontext\*(Aq => \*(Aqvoid\*(Aq}, \e&foo); |
| 503 |
\& ... |
| 504 |
\& $thr\->join(); |
| 505 |
.Ve |
| 506 |
.PP |
| 507 |
The context type may also be used as the \fIkey\fR in the hash reference followed |
| 508 |
by a \fItrue\fR value: |
| 509 |
.PP |
| 510 |
.Vb 4 |
| 511 |
\& threads\->create({\*(Aqscalar\*(Aq => 1}, \e&foo); |
| 512 |
\& ... |
| 513 |
\& my ($thr) = threads\->list(); |
| 514 |
\& my $result = $thr\->join(); |
| 515 |
.Ve |
| 516 |
.SS "Implicit context" |
| 517 |
.IX Subsection "Implicit context" |
| 518 |
If not explicitly stated, the thread's context is implied from the context |
| 519 |
of the \f(CW\*(C`\->create()\*(C'\fR call: |
| 520 |
.PP |
| 521 |
.Vb 2 |
| 522 |
\& # Create thread in list context |
| 523 |
\& my ($thr) = threads\->create(...); |
| 524 |
\& |
| 525 |
\& # Create thread in scalar context |
| 526 |
\& my $thr = threads\->create(...); |
| 527 |
\& |
| 528 |
\& # Create thread in void context |
| 529 |
\& threads\->create(...); |
| 530 |
.Ve |
| 531 |
.ie n .SS $thr\->\fBwantarray()\fP |
| 532 |
.el .SS \f(CW$thr\fP\->\fBwantarray()\fP |
| 533 |
.IX Subsection "$thr->wantarray()" |
| 534 |
This returns the thread's context in the same manner as |
| 535 |
\&\fBwantarray()\fR. |
| 536 |
.SS threads\->\fBwantarray()\fP |
| 537 |
.IX Subsection "threads->wantarray()" |
| 538 |
Class method to return the current thread's context. This returns the same |
| 539 |
value as running \fBwantarray()\fR inside the current |
| 540 |
thread's entry point function. |
| 541 |
.SH "THREAD STACK SIZE" |
| 542 |
.IX Header "THREAD STACK SIZE" |
| 543 |
The default per-thread stack size for different platforms varies |
| 544 |
significantly, and is almost always far more than is needed for most |
| 545 |
applications. On Win32, Perl's makefile explicitly sets the default stack to |
| 546 |
16 MB; on most other platforms, the system default is used, which again may be |
| 547 |
much larger than is needed. |
| 548 |
.PP |
| 549 |
By tuning the stack size to more accurately reflect your application's needs, |
| 550 |
you may significantly reduce your application's memory usage, and increase the |
| 551 |
number of simultaneously running threads. |
| 552 |
.PP |
| 553 |
Note that on Windows, address space allocation granularity is 64 KB, |
| 554 |
therefore, setting the stack smaller than that on Win32 Perl will not save any |
| 555 |
more memory. |
| 556 |
.IP threads\->\fBget_stack_size()\fR; 4 |
| 557 |
.IX Item "threads->get_stack_size();" |
| 558 |
Returns the current default per-thread stack size. The default is zero, which |
| 559 |
means the system default stack size is currently in use. |
| 560 |
.ie n .IP "$size = $thr\->\fBget_stack_size()\fR;" 4 |
| 561 |
.el .IP "\f(CW$size\fR = \f(CW$thr\fR\->\fBget_stack_size()\fR;" 4 |
| 562 |
.IX Item "$size = $thr->get_stack_size();" |
| 563 |
Returns the stack size for a particular thread. A return value of zero |
| 564 |
indicates the system default stack size was used for the thread. |
| 565 |
.ie n .IP "$old_size = threads\->set_stack_size($new_size);" 4 |
| 566 |
.el .IP "\f(CW$old_size\fR = threads\->set_stack_size($new_size);" 4 |
| 567 |
.IX Item "$old_size = threads->set_stack_size($new_size);" |
| 568 |
Sets a new default per-thread stack size, and returns the previous setting. |
| 569 |
.Sp |
| 570 |
Some platforms have a minimum thread stack size. Trying to set the stack size |
| 571 |
below this value will result in a warning, and the minimum stack size will be |
| 572 |
used. |
| 573 |
.Sp |
| 574 |
Some Linux platforms have a maximum stack size. Setting too large of a stack |
| 575 |
size will cause thread creation to fail. |
| 576 |
.Sp |
| 577 |
If needed, \f(CW$new_size\fR will be rounded up to the next multiple of the memory |
| 578 |
page size (usually 4096 or 8192). |
| 579 |
.Sp |
| 580 |
Threads created after the stack size is set will then either call |
| 581 |
\&\f(CWpthread_attr_setstacksize()\fR \fI(for pthreads platforms)\fR, or supply the |
| 582 |
stack size to \f(CWCreateThread()\fR \fI(for Win32 Perl)\fR. |
| 583 |
.Sp |
| 584 |
(Obviously, this call does not affect any currently extant threads.) |
| 585 |
.IP "use threads ('stack_size' => VALUE);" 4 |
| 586 |
.IX Item "use threads ('stack_size' => VALUE);" |
| 587 |
This sets the default per-thread stack size at the start of the application. |
| 588 |
.ie n .IP $ENV{'PERL5_ITHREADS_STACK_SIZE'} 4 |
| 589 |
.el .IP \f(CW$ENV\fR{'PERL5_ITHREADS_STACK_SIZE'} 4 |
| 590 |
.IX Item "$ENV{'PERL5_ITHREADS_STACK_SIZE'}" |
| 591 |
The default per-thread stack size may be set at the start of the application |
| 592 |
through the use of the environment variable \f(CW\*(C`PERL5_ITHREADS_STACK_SIZE\*(C'\fR: |
| 593 |
.Sp |
| 594 |
.Vb 3 |
| 595 |
\& PERL5_ITHREADS_STACK_SIZE=1048576 |
| 596 |
\& export PERL5_ITHREADS_STACK_SIZE |
| 597 |
\& perl \-e\*(Aquse threads; print(threads\->get_stack_size(), "\en")\*(Aq |
| 598 |
.Ve |
| 599 |
.Sp |
| 600 |
This value overrides any \f(CW\*(C`stack_size\*(C'\fR parameter given to \f(CW\*(C`use threads\*(C'\fR. Its |
| 601 |
primary purpose is to permit setting the per-thread stack size for legacy |
| 602 |
threaded applications. |
| 603 |
.IP "threads\->create({'stack_size' => VALUE}, FUNCTION, ARGS)" 4 |
| 604 |
.IX Item "threads->create({'stack_size' => VALUE}, FUNCTION, ARGS)" |
| 605 |
To specify a particular stack size for any individual thread, call |
| 606 |
\&\f(CW\*(C`\->create()\*(C'\fR with a hash reference as the first argument: |
| 607 |
.Sp |
| 608 |
.Vb 2 |
| 609 |
\& my $thr = threads\->create({\*(Aqstack_size\*(Aq => 32*4096}, |
| 610 |
\& \e&foo, @args); |
| 611 |
.Ve |
| 612 |
.ie n .IP "$thr2 = $thr1\->create(FUNCTION, ARGS)" 4 |
| 613 |
.el .IP "\f(CW$thr2\fR = \f(CW$thr1\fR\->create(FUNCTION, ARGS)" 4 |
| 614 |
.IX Item "$thr2 = $thr1->create(FUNCTION, ARGS)" |
| 615 |
This creates a new thread (\f(CW$thr2\fR) that inherits the stack size from an |
| 616 |
existing thread (\f(CW$thr1\fR). This is shorthand for the following: |
| 617 |
.Sp |
| 618 |
.Vb 3 |
| 619 |
\& my $stack_size = $thr1\->get_stack_size(); |
| 620 |
\& my $thr2 = threads\->create({\*(Aqstack_size\*(Aq => $stack_size}, |
| 621 |
\& FUNCTION, ARGS); |
| 622 |
.Ve |
| 623 |
.SH "THREAD SIGNALLING" |
| 624 |
.IX Header "THREAD SIGNALLING" |
| 625 |
When safe signals is in effect (the default behavior \- see "Unsafe signals" |
| 626 |
for more details), then signals may be sent and acted upon by individual |
| 627 |
threads. |
| 628 |
.ie n .IP $thr\->kill('SIG...'); 4 |
| 629 |
.el .IP \f(CW$thr\fR\->kill('SIG...'); 4 |
| 630 |
.IX Item "$thr->kill('SIG...');" |
| 631 |
Sends the specified signal to the thread. Signal names and (positive) signal |
| 632 |
numbers are the same as those supported by |
| 633 |
\&\fBkill()\fR. For example, 'SIGTERM', 'TERM' and |
| 634 |
(depending on the OS) 15 are all valid arguments to \f(CW\*(C`\->kill()\*(C'\fR. |
| 635 |
.Sp |
| 636 |
Returns the thread object to allow for method chaining: |
| 637 |
.Sp |
| 638 |
.Vb 1 |
| 639 |
\& $thr\->kill(\*(AqSIG...\*(Aq)\->join(); |
| 640 |
.Ve |
| 641 |
.PP |
| 642 |
Signal handlers need to be set up in the threads for the signals they are |
| 643 |
expected to act upon. Here's an example for \fIcancelling\fR a thread: |
| 644 |
.PP |
| 645 |
.Vb 1 |
| 646 |
\& use threads; |
| 647 |
\& |
| 648 |
\& sub thr_func |
| 649 |
\& { |
| 650 |
\& # Thread \*(Aqcancellation\*(Aq signal handler |
| 651 |
\& $SIG{\*(AqKILL\*(Aq} = sub { threads\->exit(); }; |
| 652 |
\& |
| 653 |
\& ... |
| 654 |
\& } |
| 655 |
\& |
| 656 |
\& # Create a thread |
| 657 |
\& my $thr = threads\->create(\*(Aqthr_func\*(Aq); |
| 658 |
\& |
| 659 |
\& ... |
| 660 |
\& |
| 661 |
\& # Signal the thread to terminate, and then detach |
| 662 |
\& # it so that it will get cleaned up automatically |
| 663 |
\& $thr\->kill(\*(AqKILL\*(Aq)\->detach(); |
| 664 |
.Ve |
| 665 |
.PP |
| 666 |
Here's another simplistic example that illustrates the use of thread |
| 667 |
signalling in conjunction with a semaphore to provide rudimentary \fIsuspend\fR |
| 668 |
and \fIresume\fR capabilities: |
| 669 |
.PP |
| 670 |
.Vb 2 |
| 671 |
\& use threads; |
| 672 |
\& use Thread::Semaphore; |
| 673 |
\& |
| 674 |
\& sub thr_func |
| 675 |
\& { |
| 676 |
\& my $sema = shift; |
| 677 |
\& |
| 678 |
\& # Thread \*(Aqsuspend/resume\*(Aq signal handler |
| 679 |
\& $SIG{\*(AqSTOP\*(Aq} = sub { |
| 680 |
\& $sema\->down(); # Thread suspended |
| 681 |
\& $sema\->up(); # Thread resumes |
| 682 |
\& }; |
| 683 |
\& |
| 684 |
\& ... |
| 685 |
\& } |
| 686 |
\& |
| 687 |
\& # Create a semaphore and pass it to a thread |
| 688 |
\& my $sema = Thread::Semaphore\->new(); |
| 689 |
\& my $thr = threads\->create(\*(Aqthr_func\*(Aq, $sema); |
| 690 |
\& |
| 691 |
\& # Suspend the thread |
| 692 |
\& $sema\->down(); |
| 693 |
\& $thr\->kill(\*(AqSTOP\*(Aq); |
| 694 |
\& |
| 695 |
\& ... |
| 696 |
\& |
| 697 |
\& # Allow the thread to continue |
| 698 |
\& $sema\->up(); |
| 699 |
.Ve |
| 700 |
.PP |
| 701 |
CAVEAT: The thread signalling capability provided by this module does not |
| 702 |
actually send signals via the OS. It \fIemulates\fR signals at the Perl-level |
| 703 |
such that signal handlers are called in the appropriate thread. For example, |
| 704 |
sending \f(CW\*(C`$thr\->kill(\*(AqSTOP\*(Aq)\*(C'\fR does not actually suspend a thread (or the |
| 705 |
whole process), but does cause a \f(CW$SIG{\*(AqSTOP\*(Aq}\fR handler to be called in that |
| 706 |
thread (as illustrated above). |
| 707 |
.PP |
| 708 |
As such, signals that would normally not be appropriate to use in the |
| 709 |
\&\f(CWkill()\fR command (e.g., \f(CW\*(C`kill(\*(AqKILL\*(Aq, $$)\*(C'\fR) are okay to use with the |
| 710 |
\&\f(CW\*(C`\->kill()\*(C'\fR method (again, as illustrated above). |
| 711 |
.PP |
| 712 |
Correspondingly, sending a signal to a thread does not disrupt the operation |
| 713 |
the thread is currently working on: The signal will be acted upon after the |
| 714 |
current operation has completed. For instance, if the thread is \fIstuck\fR on |
| 715 |
an I/O call, sending it a signal will not cause the I/O call to be interrupted |
| 716 |
such that the signal is acted up immediately. |
| 717 |
.PP |
| 718 |
Sending a signal to a terminated/finished thread is ignored. |
| 719 |
.SH WARNINGS |
| 720 |
.IX Header "WARNINGS" |
| 721 |
.IP "Perl exited with active threads:" 4 |
| 722 |
.IX Item "Perl exited with active threads:" |
| 723 |
If the program exits without all threads having either been joined or |
| 724 |
detached, then this warning will be issued. |
| 725 |
.Sp |
| 726 |
NOTE: If the \fImain\fR thread exits, then this warning cannot be suppressed |
| 727 |
using \f(CW\*(C`no warnings \*(Aqthreads\*(Aq;\*(C'\fR as suggested below. |
| 728 |
.IP "Thread creation failed: pthread_create returned #" 4 |
| 729 |
.IX Item "Thread creation failed: pthread_create returned #" |
| 730 |
See the appropriate \fIman\fR page for \f(CW\*(C`pthread_create\*(C'\fR to determine the actual |
| 731 |
cause for the failure. |
| 732 |
.IP "Thread # terminated abnormally: ..." 4 |
| 733 |
.IX Item "Thread # terminated abnormally: ..." |
| 734 |
A thread terminated in some manner other than just returning from its entry |
| 735 |
point function, or by using \f(CW\*(C`threads\->exit()\*(C'\fR. For example, the thread |
| 736 |
may have terminated because of an error, or by using \f(CW\*(C`die\*(C'\fR. |
| 737 |
.IP "Using minimum thread stack size of #" 4 |
| 738 |
.IX Item "Using minimum thread stack size of #" |
| 739 |
Some platforms have a minimum thread stack size. Trying to set the stack size |
| 740 |
below this value will result in the above warning, and the stack size will be |
| 741 |
set to the minimum. |
| 742 |
.IP "Thread creation failed: pthread_attr_setstacksize(\fISIZE\fR) returned 22" 4 |
| 743 |
.IX Item "Thread creation failed: pthread_attr_setstacksize(SIZE) returned 22" |
| 744 |
The specified \fISIZE\fR exceeds the system's maximum stack size. Use a smaller |
| 745 |
value for the stack size. |
| 746 |
.PP |
| 747 |
If needed, thread warnings can be suppressed by using: |
| 748 |
.PP |
| 749 |
.Vb 1 |
| 750 |
\& no warnings \*(Aqthreads\*(Aq; |
| 751 |
.Ve |
| 752 |
.PP |
| 753 |
in the appropriate scope. |
| 754 |
.SH ERRORS |
| 755 |
.IX Header "ERRORS" |
| 756 |
.IP "This Perl not built to support threads" 4 |
| 757 |
.IX Item "This Perl not built to support threads" |
| 758 |
The particular copy of Perl that you're trying to use was not built using the |
| 759 |
\&\f(CW\*(C`useithreads\*(C'\fR configuration option. |
| 760 |
.Sp |
| 761 |
Having threads support requires all of Perl and all of the XS modules in the |
| 762 |
Perl installation to be rebuilt; it is not just a question of adding the |
| 763 |
threads module (i.e., threaded and non-threaded Perls are binary |
| 764 |
incompatible). |
| 765 |
.IP "Cannot change stack size of an existing thread" 4 |
| 766 |
.IX Item "Cannot change stack size of an existing thread" |
| 767 |
The stack size of currently extant threads cannot be changed, therefore, the |
| 768 |
following results in the above error: |
| 769 |
.Sp |
| 770 |
.Vb 1 |
| 771 |
\& $thr\->set_stack_size($size); |
| 772 |
.Ve |
| 773 |
.IP "Cannot signal threads without safe signals" 4 |
| 774 |
.IX Item "Cannot signal threads without safe signals" |
| 775 |
Safe signals must be in effect to use the \f(CW\*(C`\->kill()\*(C'\fR signalling method. |
| 776 |
See "Unsafe signals" for more details. |
| 777 |
.IP "Unrecognized signal name: ..." 4 |
| 778 |
.IX Item "Unrecognized signal name: ..." |
| 779 |
The particular copy of Perl that you're trying to use does not support the |
| 780 |
specified signal being used in a \f(CW\*(C`\->kill()\*(C'\fR call. |
| 781 |
.SH "BUGS AND LIMITATIONS" |
| 782 |
.IX Header "BUGS AND LIMITATIONS" |
| 783 |
Before you consider posting a bug report, please consult, and possibly post a |
| 784 |
message to the discussion forum to see if what you've encountered is a known |
| 785 |
problem. |
| 786 |
.IP "Thread-safe modules" 4 |
| 787 |
.IX Item "Thread-safe modules" |
| 788 |
See "Making your module threadsafe" in perlmod when creating modules that may |
| 789 |
be used in threaded applications, especially if those modules use non-Perl |
| 790 |
data, or XS code. |
| 791 |
.IP "Using non-thread-safe modules" 4 |
| 792 |
.IX Item "Using non-thread-safe modules" |
| 793 |
Unfortunately, you may encounter Perl modules that are not \fIthread-safe\fR. |
| 794 |
For example, they may crash the Perl interpreter during execution, or may dump |
| 795 |
core on termination. Depending on the module and the requirements of your |
| 796 |
application, it may be possible to work around such difficulties. |
| 797 |
.Sp |
| 798 |
If the module will only be used inside a thread, you can try loading the |
| 799 |
module from inside the thread entry point function using \f(CW\*(C`require\*(C'\fR (and |
| 800 |
\&\f(CW\*(C`import\*(C'\fR if needed): |
| 801 |
.Sp |
| 802 |
.Vb 4 |
| 803 |
\& sub thr_func |
| 804 |
\& { |
| 805 |
\& require Unsafe::Module |
| 806 |
\& # Unsafe::Module\->import(...); |
| 807 |
\& |
| 808 |
\& .... |
| 809 |
\& } |
| 810 |
.Ve |
| 811 |
.Sp |
| 812 |
If the module is needed inside the \fImain\fR thread, try modifying your |
| 813 |
application so that the module is loaded (again using \f(CW\*(C`require\*(C'\fR and |
| 814 |
\&\f(CW\*(C`\->import()\*(C'\fR) after any threads are started, and in such a way that no |
| 815 |
other threads are started afterwards. |
| 816 |
.Sp |
| 817 |
If the above does not work, or is not adequate for your application, then file |
| 818 |
a bug report on <https://rt.cpan.org/Public/> against the problematic module. |
| 819 |
.IP "Memory consumption" 4 |
| 820 |
.IX Item "Memory consumption" |
| 821 |
On most systems, frequent and continual creation and destruction of threads |
| 822 |
can lead to ever-increasing growth in the memory footprint of the Perl |
| 823 |
interpreter. While it is simple to just launch threads and then |
| 824 |
\&\f(CW\*(C`\->join()\*(C'\fR or \f(CW\*(C`\->detach()\*(C'\fR them, for long-lived applications, it is |
| 825 |
better to maintain a pool of threads, and to reuse them for the work needed, |
| 826 |
using queues to notify threads of pending work. The CPAN |
| 827 |
distribution of this module contains a simple example |
| 828 |
(\fIexamples/pool_reuse.pl\fR) illustrating the creation, use and monitoring of a |
| 829 |
pool of \fIreusable\fR threads. |
| 830 |
.IP "Current working directory" 4 |
| 831 |
.IX Item "Current working directory" |
| 832 |
On all platforms except MSWin32, the setting for the current working directory |
| 833 |
is shared among all threads such that changing it in one thread (e.g., using |
| 834 |
\&\f(CWchdir()\fR) will affect all the threads in the application. |
| 835 |
.Sp |
| 836 |
On MSWin32, each thread maintains its own the current working directory |
| 837 |
setting. |
| 838 |
.IP Locales 4 |
| 839 |
.IX Item "Locales" |
| 840 |
Prior to Perl 5.28, locales could not be used with threads, due to various |
| 841 |
race conditions. Starting in that release, on systems that implement |
| 842 |
thread-safe locale functions, threads can be used, with some caveats. |
| 843 |
This includes Windows starting with Visual Studio 2005, and systems compatible |
| 844 |
with POSIX 2008. See "Multi-threaded operation" in perllocale. |
| 845 |
.Sp |
| 846 |
Each thread (except the main thread) is started using the C locale. The main |
| 847 |
thread is started like all other Perl programs; see "ENVIRONMENT" in perllocale. |
| 848 |
You can switch locales in any thread as often as you like. |
| 849 |
.Sp |
| 850 |
If you want to inherit the parent thread's locale, you can, in the parent, set |
| 851 |
a variable like so: |
| 852 |
.Sp |
| 853 |
.Vb 1 |
| 854 |
\& $foo = POSIX::setlocale(LC_ALL, NULL); |
| 855 |
.Ve |
| 856 |
.Sp |
| 857 |
and then pass to threads\->\fBcreate()\fR a sub that closes over \f(CW$foo\fR. Then, in |
| 858 |
the child, you say |
| 859 |
.Sp |
| 860 |
.Vb 1 |
| 861 |
\& POSIX::setlocale(LC_ALL, $foo); |
| 862 |
.Ve |
| 863 |
.Sp |
| 864 |
Or you can use the facilities in threads::shared to pass \f(CW$foo\fR; |
| 865 |
or if the environment hasn't changed, in the child, do |
| 866 |
.Sp |
| 867 |
.Vb 1 |
| 868 |
\& POSIX::setlocale(LC_ALL, ""); |
| 869 |
.Ve |
| 870 |
.IP "Environment variables" 4 |
| 871 |
.IX Item "Environment variables" |
| 872 |
Currently, on all platforms except MSWin32, all \fIsystem\fR calls (e.g., using |
| 873 |
\&\f(CWsystem()\fR or back-ticks) made from threads use the environment variable |
| 874 |
settings from the \fImain\fR thread. In other words, changes made to \f(CW%ENV\fR in |
| 875 |
a thread will not be visible in \fIsystem\fR calls made by that thread. |
| 876 |
.Sp |
| 877 |
To work around this, set environment variables as part of the \fIsystem\fR call. |
| 878 |
For example: |
| 879 |
.Sp |
| 880 |
.Vb 2 |
| 881 |
\& my $msg = \*(Aqhello\*(Aq; |
| 882 |
\& system("FOO=$msg; echo \e$FOO"); # Outputs \*(Aqhello\*(Aq to STDOUT |
| 883 |
.Ve |
| 884 |
.Sp |
| 885 |
On MSWin32, each thread maintains its own set of environment variables. |
| 886 |
.IP "Catching signals" 4 |
| 887 |
.IX Item "Catching signals" |
| 888 |
Signals are \fIcaught\fR by the main thread (thread ID = 0) of a script. |
| 889 |
Therefore, setting up signal handlers in threads for purposes other than |
| 890 |
"THREAD SIGNALLING" as documented above will not accomplish what is |
| 891 |
intended. |
| 892 |
.Sp |
| 893 |
This is especially true if trying to catch \f(CW\*(C`SIGALRM\*(C'\fR in a thread. To handle |
| 894 |
alarms in threads, set up a signal handler in the main thread, and then use |
| 895 |
"THREAD SIGNALLING" to relay the signal to the thread: |
| 896 |
.Sp |
| 897 |
.Vb 10 |
| 898 |
\& # Create thread with a task that may time out |
| 899 |
\& my $thr = threads\->create(sub { |
| 900 |
\& threads\->yield(); |
| 901 |
\& eval { |
| 902 |
\& $SIG{ALRM} = sub { die("Timeout\en"); }; |
| 903 |
\& alarm(10); |
| 904 |
\& ... # Do work here |
| 905 |
\& alarm(0); |
| 906 |
\& }; |
| 907 |
\& if ($@ =~ /Timeout/) { |
| 908 |
\& warn("Task in thread timed out\en"); |
| 909 |
\& } |
| 910 |
\& }; |
| 911 |
\& |
| 912 |
\& # Set signal handler to relay SIGALRM to thread |
| 913 |
\& $SIG{ALRM} = sub { $thr\->kill(\*(AqALRM\*(Aq) }; |
| 914 |
\& |
| 915 |
\& ... # Main thread continues working |
| 916 |
.Ve |
| 917 |
.IP "Parent-child threads" 4 |
| 918 |
.IX Item "Parent-child threads" |
| 919 |
On some platforms, it might not be possible to destroy \fIparent\fR threads while |
| 920 |
there are still existing \fIchild\fR threads. |
| 921 |
.IP "Unsafe signals" 4 |
| 922 |
.IX Item "Unsafe signals" |
| 923 |
Since Perl 5.8.0, signals have been made safer in Perl by postponing their |
| 924 |
handling until the interpreter is in a \fIsafe\fR state. See |
| 925 |
"Safe Signals" in perl58delta and "Deferred Signals (Safe Signals)" in perlipc |
| 926 |
for more details. |
| 927 |
.Sp |
| 928 |
Safe signals is the default behavior, and the old, immediate, unsafe |
| 929 |
signalling behavior is only in effect in the following situations: |
| 930 |
.RS 4 |
| 931 |
.IP \(bu 4 |
| 932 |
Perl has been built with \f(CW\*(C`PERL_OLD_SIGNALS\*(C'\fR (see \f(CW\*(C`perl\ \-V\*(C'\fR). |
| 933 |
.IP \(bu 4 |
| 934 |
The environment variable \f(CW\*(C`PERL_SIGNALS\*(C'\fR is set to \f(CW\*(C`unsafe\*(C'\fR |
| 935 |
(see "PERL_SIGNALS" in perlrun). |
| 936 |
.IP \(bu 4 |
| 937 |
The module Perl::Unsafe::Signals is used. |
| 938 |
.RE |
| 939 |
.RS 4 |
| 940 |
.Sp |
| 941 |
If unsafe signals is in effect, then signal handling is not thread-safe, and |
| 942 |
the \f(CW\*(C`\->kill()\*(C'\fR signalling method cannot be used. |
| 943 |
.RE |
| 944 |
.IP "Identity of objects returned from threads" 4 |
| 945 |
.IX Item "Identity of objects returned from threads" |
| 946 |
When a value is returned from a thread through a \f(CW\*(C`join\*(C'\fR operation, |
| 947 |
the value and everything that it references is copied across to the |
| 948 |
joining thread, in much the same way that values are copied upon thread |
| 949 |
creation. This works fine for most kinds of value, including arrays, |
| 950 |
hashes, and subroutines. The copying recurses through array elements, |
| 951 |
reference scalars, variables closed over by subroutines, and other kinds |
| 952 |
of reference. |
| 953 |
.Sp |
| 954 |
However, everything referenced by the returned value is a fresh copy in |
| 955 |
the joining thread, even if a returned object had in the child thread |
| 956 |
been a copy of something that previously existed in the parent thread. |
| 957 |
After joining, the parent will therefore have a duplicate of each such |
| 958 |
object. This sometimes matters, especially if the object gets mutated; |
| 959 |
this can especially matter for private data to which a returned subroutine |
| 960 |
provides access. |
| 961 |
.IP "Returning blessed objects from threads" 4 |
| 962 |
.IX Item "Returning blessed objects from threads" |
| 963 |
Returning blessed objects from threads does not work. Depending on the classes |
| 964 |
involved, you may be able to work around this by returning a serialized |
| 965 |
version of the object (e.g., using Data::Dumper or Storable), and then |
| 966 |
reconstituting it in the joining thread. If you're using Perl 5.10.0 or |
| 967 |
later, and if the class supports shared objects, |
| 968 |
you can pass them via shared queues. |
| 969 |
.IP "END blocks in threads" 4 |
| 970 |
.IX Item "END blocks in threads" |
| 971 |
It is possible to add END blocks to threads by using require or |
| 972 |
eval with the appropriate code. These \f(CW\*(C`END\*(C'\fR blocks |
| 973 |
will then be executed when the thread's interpreter is destroyed (i.e., either |
| 974 |
during a \f(CW\*(C`\->join()\*(C'\fR call, or at program termination). |
| 975 |
.Sp |
| 976 |
However, calling any threads methods in such an \f(CW\*(C`END\*(C'\fR block will most |
| 977 |
likely \fIfail\fR (e.g., the application may hang, or generate an error) due to |
| 978 |
mutexes that are needed to control functionality within the threads module. |
| 979 |
.Sp |
| 980 |
For this reason, the use of \f(CW\*(C`END\*(C'\fR blocks in threads is \fBstrongly\fR |
| 981 |
discouraged. |
| 982 |
.IP "Open directory handles" 4 |
| 983 |
.IX Item "Open directory handles" |
| 984 |
In perl 5.14 and higher, on systems other than Windows that do |
| 985 |
not support the \f(CW\*(C`fchdir\*(C'\fR C function, directory handles (see |
| 986 |
opendir) will not be copied to new |
| 987 |
threads. You can use the \f(CW\*(C`d_fchdir\*(C'\fR variable in Config.pm to |
| 988 |
determine whether your system supports it. |
| 989 |
.Sp |
| 990 |
In prior perl versions, spawning threads with open directory handles would |
| 991 |
crash the interpreter. |
| 992 |
[perl #75154] <https://rt.perl.org/rt3/Public/Bug/Display.html?id=75154> |
| 993 |
.IP "Detached threads and global destruction" 4 |
| 994 |
.IX Item "Detached threads and global destruction" |
| 995 |
If the main thread exits while there are detached threads which are still |
| 996 |
running, then Perl's global destruction phase is not executed because |
| 997 |
otherwise certain global structures that control the operation of threads and |
| 998 |
that are allocated in the main thread's memory may get destroyed before the |
| 999 |
detached thread is destroyed. |
| 1000 |
.Sp |
| 1001 |
If you are using any code that requires the execution of the global |
| 1002 |
destruction phase for clean up (e.g., removing temp files), then do not use |
| 1003 |
detached threads, but rather join all threads before exiting the program. |
| 1004 |
.IP "Perl Bugs and the CPAN Version of threads" 4 |
| 1005 |
.IX Item "Perl Bugs and the CPAN Version of threads" |
| 1006 |
Support for threads extends beyond the code in this module (i.e., |
| 1007 |
\&\fIthreads.pm\fR and \fIthreads.xs\fR), and into the Perl interpreter itself. Older |
| 1008 |
versions of Perl contain bugs that may manifest themselves despite using the |
| 1009 |
latest version of threads from CPAN. There is no workaround for this other |
| 1010 |
than upgrading to the latest version of Perl. |
| 1011 |
.Sp |
| 1012 |
Even with the latest version of Perl, it is known that certain constructs |
| 1013 |
with threads may result in warning messages concerning leaked scalars or |
| 1014 |
unreferenced scalars. However, such warnings are harmless, and may safely be |
| 1015 |
ignored. |
| 1016 |
.Sp |
| 1017 |
You can search for threads related bug reports at |
| 1018 |
<https://rt.cpan.org/Public/>. If needed submit any new bugs, problems, |
| 1019 |
patches, etc. to: <https://rt.cpan.org/Public/Dist/Display.html?Name=threads> |
| 1020 |
.SH REQUIREMENTS |
| 1021 |
.IX Header "REQUIREMENTS" |
| 1022 |
Perl 5.8.0 or later |
| 1023 |
.SH "SEE ALSO" |
| 1024 |
.IX Header "SEE ALSO" |
| 1025 |
threads on MetaCPAN: |
| 1026 |
<https://metacpan.org/release/threads> |
| 1027 |
.PP |
| 1028 |
Code repository for CPAN distribution: |
| 1029 |
<https://github.com/Dual\-Life/threads> |
| 1030 |
.PP |
| 1031 |
threads::shared, perlthrtut |
| 1032 |
.PP |
| 1033 |
<https://www.perl.com/pub/a/2002/06/11/threads.html> and |
| 1034 |
<https://www.perl.com/pub/a/2002/09/04/threads.html> |
| 1035 |
.PP |
| 1036 |
Perl threads mailing list: |
| 1037 |
<https://lists.perl.org/list/ithreads.html> |
| 1038 |
.PP |
| 1039 |
Stack size discussion: |
| 1040 |
<https://www.perlmonks.org/?node_id=532956> |
| 1041 |
.PP |
| 1042 |
Sample code in the \fIexamples\fR directory of this distribution on CPAN. |
| 1043 |
.SH AUTHOR |
| 1044 |
.IX Header "AUTHOR" |
| 1045 |
Artur Bergman <sky AT crucially DOT net> |
| 1046 |
.PP |
| 1047 |
CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org> |
| 1048 |
.SH LICENSE |
| 1049 |
.IX Header "LICENSE" |
| 1050 |
threads is released under the same license as Perl. |
| 1051 |
.SH ACKNOWLEDGEMENTS |
| 1052 |
.IX Header "ACKNOWLEDGEMENTS" |
| 1053 |
Richard Soderberg <perl AT crystalflame DOT net> \- |
| 1054 |
Helping me out tons, trying to find reasons for races and other weird bugs! |
| 1055 |
.PP |
| 1056 |
Simon Cozens <simon AT brecon DOT co DOT uk> \- |
| 1057 |
Being there to answer zillions of annoying questions |
| 1058 |
.PP |
| 1059 |
Rocco Caputo <troc AT netrus DOT net> |
| 1060 |
.PP |
| 1061 |
Vipul Ved Prakash <mail AT vipul DOT net> \- |
| 1062 |
Helping with debugging |
| 1063 |
.PP |
| 1064 |
Dean Arnold <darnold AT presicient DOT com> \- |
| 1065 |
Stack size API |