Debian Codegraph @

upstream/debian-unstable/man3/Thread.3perl

raw
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