| 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 "Thread 3perl" |
| 58 |
.TH Thread 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 |
Thread \- Manipulate threads in Perl (for old code only) |
| 65 |
.SH DEPRECATED |
| 66 |
.IX Header "DEPRECATED" |
| 67 |
The \f(CW\*(C`Thread\*(C'\fR module served as the frontend to the old-style thread model, |
| 68 |
called \fI5005threads\fR, that was introduced in release 5.005. That model was |
| 69 |
deprecated, and has been removed in version 5.10. |
| 70 |
.PP |
| 71 |
For old code and interim backwards compatibility, the \f(CW\*(C`Thread\*(C'\fR module has |
| 72 |
been reworked to function as a frontend for the new interpreter threads |
| 73 |
(\fIithreads\fR) model. However, some previous functionality is not available. |
| 74 |
Further, the data sharing models between the two thread models are completely |
| 75 |
different, and anything to do with data sharing has to be thought differently. |
| 76 |
With \fIithreads\fR, you must explicitly \f(CWshare()\fR variables between the |
| 77 |
threads. |
| 78 |
.PP |
| 79 |
You are strongly encouraged to migrate any existing threaded code to the new |
| 80 |
model (i.e., use the \f(CW\*(C`threads\*(C'\fR and \f(CW\*(C`threads::shared\*(C'\fR modules) as soon as |
| 81 |
possible. |
| 82 |
.SH HISTORY |
| 83 |
.IX Header "HISTORY" |
| 84 |
In Perl 5.005, the thread model was that all data is implicitly shared, and |
| 85 |
shared access to data has to be explicitly synchronized. This model is called |
| 86 |
\&\fI5005threads\fR. |
| 87 |
.PP |
| 88 |
In Perl 5.6, a new model was introduced in which all is was thread local and |
| 89 |
shared access to data has to be explicitly declared. This model is called |
| 90 |
\&\fIithreads\fR, for "interpreter threads". |
| 91 |
.PP |
| 92 |
In Perl 5.6, the \fIithreads\fR model was not available as a public API; only as |
| 93 |
an internal API that was available for extension writers, and to implement |
| 94 |
\&\fBfork()\fR emulation on Win32 platforms. |
| 95 |
.PP |
| 96 |
In Perl 5.8, the \fIithreads\fR model became available through the \f(CW\*(C`threads\*(C'\fR |
| 97 |
module, and the \fI5005threads\fR model was deprecated. |
| 98 |
.PP |
| 99 |
In Perl 5.10, the \fI5005threads\fR model was removed from the Perl interpreter. |
| 100 |
.SH SYNOPSIS |
| 101 |
.IX Header "SYNOPSIS" |
| 102 |
.Vb 1 |
| 103 |
\& use Thread qw(:DEFAULT async yield); |
| 104 |
\& |
| 105 |
\& my $t = Thread\->new(\e&start_sub, @start_args); |
| 106 |
\& |
| 107 |
\& $result = $t\->join; |
| 108 |
\& $t\->detach; |
| 109 |
\& |
| 110 |
\& if ($t\->done) { |
| 111 |
\& $t\->join; |
| 112 |
\& } |
| 113 |
\& |
| 114 |
\& if($t\->equal($another_thread)) { |
| 115 |
\& # ... |
| 116 |
\& } |
| 117 |
\& |
| 118 |
\& yield(); |
| 119 |
\& |
| 120 |
\& my $tid = Thread\->self\->tid; |
| 121 |
\& |
| 122 |
\& lock($scalar); |
| 123 |
\& lock(@array); |
| 124 |
\& lock(%hash); |
| 125 |
\& |
| 126 |
\& my @list = Thread\->list; |
| 127 |
.Ve |
| 128 |
.SH DESCRIPTION |
| 129 |
.IX Header "DESCRIPTION" |
| 130 |
The \f(CW\*(C`Thread\*(C'\fR module provides multithreading support for Perl. |
| 131 |
.SH FUNCTIONS |
| 132 |
.IX Header "FUNCTIONS" |
| 133 |
.ie n .IP "$thread = Thread\->new(\e&start_sub)" 8 |
| 134 |
.el .IP "\f(CW$thread\fR = Thread\->new(\e&start_sub)" 8 |
| 135 |
.IX Item "$thread = Thread->new(&start_sub)" |
| 136 |
.PD 0 |
| 137 |
.ie n .IP "$thread = Thread\->new(\e&start_sub, LIST)" 8 |
| 138 |
.el .IP "\f(CW$thread\fR = Thread\->new(\e&start_sub, LIST)" 8 |
| 139 |
.IX Item "$thread = Thread->new(&start_sub, LIST)" |
| 140 |
.PD |
| 141 |
\&\f(CW\*(C`new\*(C'\fR starts a new thread of execution in the referenced subroutine. The |
| 142 |
optional list is passed as parameters to the subroutine. Execution |
| 143 |
continues in both the subroutine and the code after the \f(CW\*(C`new\*(C'\fR call. |
| 144 |
.Sp |
| 145 |
\&\f(CW\*(C`Thread\->new\*(C'\fR returns a thread object representing the newly created |
| 146 |
thread. |
| 147 |
.IP "lock VARIABLE" 8 |
| 148 |
.IX Item "lock VARIABLE" |
| 149 |
\&\f(CW\*(C`lock\*(C'\fR places a lock on a variable until the lock goes out of scope. |
| 150 |
.Sp |
| 151 |
If the variable is locked by another thread, the \f(CW\*(C`lock\*(C'\fR call will |
| 152 |
block until it's available. \f(CW\*(C`lock\*(C'\fR is recursive, so multiple calls |
| 153 |
to \f(CW\*(C`lock\*(C'\fR are safe\-\-the variable will remain locked until the |
| 154 |
outermost lock on the variable goes out of scope. |
| 155 |
.Sp |
| 156 |
Locks on variables only affect \f(CW\*(C`lock\*(C'\fR calls\-\-they do \fInot\fR affect normal |
| 157 |
access to a variable. (Locks on subs are different, and covered in a bit.) |
| 158 |
If you really, \fIreally\fR want locks to block access, then go ahead and tie |
| 159 |
them to something and manage this yourself. This is done on purpose. |
| 160 |
While managing access to variables is a good thing, Perl doesn't force |
| 161 |
you out of its living room... |
| 162 |
.Sp |
| 163 |
If a container object, such as a hash or array, is locked, all the |
| 164 |
elements of that container are not locked. For example, if a thread |
| 165 |
does a \f(CW\*(C`lock @a\*(C'\fR, any other thread doing a \f(CWlock($a[12])\fR won't |
| 166 |
block. |
| 167 |
.Sp |
| 168 |
Finally, \f(CW\*(C`lock\*(C'\fR will traverse up references exactly \fIone\fR level. |
| 169 |
\&\f(CWlock(\e$a)\fR is equivalent to \f(CWlock($a)\fR, while \f(CWlock(\e\e$a)\fR is not. |
| 170 |
.IP "async BLOCK;" 8 |
| 171 |
.IX Item "async BLOCK;" |
| 172 |
\&\f(CW\*(C`async\*(C'\fR creates a thread to execute the block immediately following |
| 173 |
it. This block is treated as an anonymous sub, and so must have a |
| 174 |
semi-colon after the closing brace. Like \f(CW\*(C`Thread\->new\*(C'\fR, \f(CW\*(C`async\*(C'\fR |
| 175 |
returns a thread object. |
| 176 |
.IP Thread\->self 8 |
| 177 |
.IX Item "Thread->self" |
| 178 |
The \f(CW\*(C`Thread\->self\*(C'\fR function returns a thread object that represents |
| 179 |
the thread making the \f(CW\*(C`Thread\->self\*(C'\fR call. |
| 180 |
.IP Thread\->list 8 |
| 181 |
.IX Item "Thread->list" |
| 182 |
Returns a list of all non-joined, non-detached Thread objects. |
| 183 |
.IP "cond_wait VARIABLE" 8 |
| 184 |
.IX Item "cond_wait VARIABLE" |
| 185 |
The \f(CW\*(C`cond_wait\*(C'\fR function takes a \fBlocked\fR variable as |
| 186 |
a parameter, unlocks the variable, and blocks until another thread |
| 187 |
does a \f(CW\*(C`cond_signal\*(C'\fR or \f(CW\*(C`cond_broadcast\*(C'\fR for that same locked |
| 188 |
variable. The variable that \f(CW\*(C`cond_wait\*(C'\fR blocked on is relocked |
| 189 |
after the \f(CW\*(C`cond_wait\*(C'\fR is satisfied. If there are multiple threads |
| 190 |
\&\f(CW\*(C`cond_wait\*(C'\fRing on the same variable, all but one will reblock waiting |
| 191 |
to re-acquire the lock on the variable. (So if you're only using |
| 192 |
\&\f(CW\*(C`cond_wait\*(C'\fR for synchronization, give up the lock as soon as |
| 193 |
possible.) |
| 194 |
.IP "cond_signal VARIABLE" 8 |
| 195 |
.IX Item "cond_signal VARIABLE" |
| 196 |
The \f(CW\*(C`cond_signal\*(C'\fR function takes a locked variable as a parameter and |
| 197 |
unblocks one thread that's \f(CW\*(C`cond_wait\*(C'\fRing on that variable. If more than |
| 198 |
one thread is blocked in a \f(CW\*(C`cond_wait\*(C'\fR on that variable, only one (and |
| 199 |
which one is indeterminate) will be unblocked. |
| 200 |
.Sp |
| 201 |
If there are no threads blocked in a \f(CW\*(C`cond_wait\*(C'\fR on the variable, |
| 202 |
the signal is discarded. |
| 203 |
.IP "cond_broadcast VARIABLE" 8 |
| 204 |
.IX Item "cond_broadcast VARIABLE" |
| 205 |
The \f(CW\*(C`cond_broadcast\*(C'\fR function works similarly to \f(CW\*(C`cond_signal\*(C'\fR. |
| 206 |
\&\f(CW\*(C`cond_broadcast\*(C'\fR, though, will unblock \fBall\fR the threads that are |
| 207 |
blocked in a \f(CW\*(C`cond_wait\*(C'\fR on the locked variable, rather than only |
| 208 |
one. |
| 209 |
.IP yield 8 |
| 210 |
.IX Item "yield" |
| 211 |
The \f(CW\*(C`yield\*(C'\fR function allows another thread to take control of the |
| 212 |
CPU. The exact results are implementation-dependent. |
| 213 |
.SH METHODS |
| 214 |
.IX Header "METHODS" |
| 215 |
.IP join 8 |
| 216 |
.IX Item "join" |
| 217 |
\&\f(CW\*(C`join\*(C'\fR waits for a thread to end and returns any values the thread |
| 218 |
exited with. \f(CW\*(C`join\*(C'\fR will block until the thread has ended, though |
| 219 |
it won't block if the thread has already terminated. |
| 220 |
.Sp |
| 221 |
If the thread being \f(CW\*(C`join\*(C'\fRed \f(CW\*(C`die\*(C'\fRd, the error it died with will |
| 222 |
be returned at this time. If you don't want the thread performing |
| 223 |
the \f(CW\*(C`join\*(C'\fR to die as well, you should either wrap the \f(CW\*(C`join\*(C'\fR in |
| 224 |
an \f(CW\*(C`eval\*(C'\fR or use the \f(CW\*(C`eval\*(C'\fR thread method instead of \f(CW\*(C`join\*(C'\fR. |
| 225 |
.IP detach 8 |
| 226 |
.IX Item "detach" |
| 227 |
\&\f(CW\*(C`detach\*(C'\fR tells a thread that it is never going to be joined i.e. |
| 228 |
that all traces of its existence can be removed once it stops running. |
| 229 |
Errors in detached threads will not be visible anywhere \- if you want |
| 230 |
to catch them, you should use \f(CW$SIG\fR{_\|_DIE_\|_} or something like that. |
| 231 |
.IP equal 8 |
| 232 |
.IX Item "equal" |
| 233 |
\&\f(CW\*(C`equal\*(C'\fR tests whether two thread objects represent the same thread and |
| 234 |
returns true if they do. |
| 235 |
.IP tid 8 |
| 236 |
.IX Item "tid" |
| 237 |
The \f(CW\*(C`tid\*(C'\fR method returns the tid of a thread. The tid is |
| 238 |
a monotonically increasing integer assigned when a thread is |
| 239 |
created. The main thread of a program will have a tid of zero, |
| 240 |
while subsequent threads will have tids assigned starting with one. |
| 241 |
.IP done 8 |
| 242 |
.IX Item "done" |
| 243 |
The \f(CW\*(C`done\*(C'\fR method returns true if the thread you're checking has |
| 244 |
finished, and false otherwise. |
| 245 |
.SH DEFUNCT |
| 246 |
.IX Header "DEFUNCT" |
| 247 |
The following were implemented with \fI5005threads\fR, but are no longer |
| 248 |
available with \fIithreads\fR. |
| 249 |
.IP lock(\e&sub) 8 |
| 250 |
.IX Item "lock(&sub)" |
| 251 |
With 5005threads, you could also \f(CW\*(C`lock\*(C'\fR a sub such that any calls to that sub |
| 252 |
from another thread would block until the lock was released. |
| 253 |
.Sp |
| 254 |
Also, subroutines could be declared with the \f(CW\*(C`:locked\*(C'\fR attribute which would |
| 255 |
serialize access to the subroutine, but allowed different threads |
| 256 |
non-simultaneous access. |
| 257 |
.IP eval 8 |
| 258 |
.IX Item "eval" |
| 259 |
The \f(CW\*(C`eval\*(C'\fR method wrapped an \f(CW\*(C`eval\*(C'\fR around a \f(CW\*(C`join\*(C'\fR, and so waited for a |
| 260 |
thread to exit, passing along any values the thread might have returned and |
| 261 |
placing any errors into \f(CW$@\fR. |
| 262 |
.IP flags 8 |
| 263 |
.IX Item "flags" |
| 264 |
The \f(CW\*(C`flags\*(C'\fR method returned the flags for the thread \- an integer value |
| 265 |
corresponding to the internal flags for the thread. |
| 266 |
.SH "SEE ALSO" |
| 267 |
.IX Header "SEE ALSO" |
| 268 |
threads, threads::shared, Thread::Queue, Thread::Semaphore |