Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Thread.3pm

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