1 cfa37a7b 2004-04-10 devnull .TH THREAD 3
4 b2cfc4e2 2003-09-30 devnull chancreate,
6 b2cfc4e2 2003-09-30 devnull chanprint,
7 058b0118 2005-01-03 devnull chansetname,
8 b2cfc4e2 2003-09-30 devnull mainstacksize,
9 b2cfc4e2 2003-09-30 devnull proccreate,
10 b2cfc4e2 2003-09-30 devnull procdata,
19 b2cfc4e2 2003-09-30 devnull nbrecvul,
22 b2cfc4e2 2003-09-30 devnull nbsendul,
23 b2cfc4e2 2003-09-30 devnull threadcreate,
24 b2cfc4e2 2003-09-30 devnull threaddata,
25 058b0118 2005-01-03 devnull threadexec,
26 058b0118 2005-01-03 devnull threadexecl,
27 b2cfc4e2 2003-09-30 devnull threadexits,
28 b2cfc4e2 2003-09-30 devnull threadexitsall,
29 b2cfc4e2 2003-09-30 devnull threadgetgrp,
30 b2cfc4e2 2003-09-30 devnull threadgetname,
31 b2cfc4e2 2003-09-30 devnull threadint,
32 b2cfc4e2 2003-09-30 devnull threadintgrp,
33 b2cfc4e2 2003-09-30 devnull threadkill,
34 b2cfc4e2 2003-09-30 devnull threadkillgrp,
35 b2cfc4e2 2003-09-30 devnull threadmain,
36 b3a20a96 2020-12-30 rsc threadmaybackground,
37 b2cfc4e2 2003-09-30 devnull threadnotify,
38 b2cfc4e2 2003-09-30 devnull threadid,
39 b2cfc4e2 2003-09-30 devnull threadpid,
40 df970459 2006-06-26 devnull threadpin,
41 df970459 2006-06-26 devnull threadunpin,
42 b2cfc4e2 2003-09-30 devnull threadsetgrp,
43 b2cfc4e2 2003-09-30 devnull threadsetname,
44 058b0118 2005-01-03 devnull threadsetstate,
45 058b0118 2005-01-03 devnull threadspawn,
46 9e4b56e7 2012-10-22 rsc threadspawnd,
47 e4d62adf 2005-01-18 devnull threadspawnl,
48 b2cfc4e2 2003-09-30 devnull threadwaitchan,
49 b2cfc4e2 2003-09-30 devnull yield \- thread and proc management
50 b2cfc4e2 2003-09-30 devnull .SH SYNOPSIS
53 b2cfc4e2 2003-09-30 devnull .ta 4n +4n +4n +4n +4n +4n +4n
54 b2cfc4e2 2003-09-30 devnull #include <u.h>
55 b2cfc4e2 2003-09-30 devnull #include <libc.h>
56 b2cfc4e2 2003-09-30 devnull #include <thread.h>
58 b2cfc4e2 2003-09-30 devnull #define CHANEND 0
59 b2cfc4e2 2003-09-30 devnull #define CHANSND 1
60 b2cfc4e2 2003-09-30 devnull #define CHANRCV 2
61 b2cfc4e2 2003-09-30 devnull #define CHANNOP 3
62 b2cfc4e2 2003-09-30 devnull #define CHANNOBLK 4
64 b2cfc4e2 2003-09-30 devnull .ta \w' 'u +\w'Channel 'u
65 b2cfc4e2 2003-09-30 devnull typedef struct Alt Alt;
66 b2cfc4e2 2003-09-30 devnull struct Alt {
67 b2cfc4e2 2003-09-30 devnull Channel *c;
70 b2cfc4e2 2003-09-30 devnull Channel **tag;
71 b2cfc4e2 2003-09-30 devnull int entryno;
72 058b0118 2005-01-03 devnull char *name;
76 b5fdffee 2004-04-19 devnull .if t .sp 0.5
77 b5fdffee 2004-04-19 devnull .if n .sp
82 b2cfc4e2 2003-09-30 devnull .ta \w'\fLChannel* 'u +4n +4n +4n +4n
83 b2cfc4e2 2003-09-30 devnull void threadmain(int argc, char *argv[])
84 b3a20a96 2020-12-30 rsc int threadmaybackground(void)
85 b2cfc4e2 2003-09-30 devnull int mainstacksize
86 b2cfc4e2 2003-09-30 devnull int proccreate(void (*fn)(void*), void *arg, uint stacksize)
87 b2cfc4e2 2003-09-30 devnull int threadcreate(void (*fn)(void*), void *arg, uint stacksize)
88 b2cfc4e2 2003-09-30 devnull void threadexits(char *status)
89 b2cfc4e2 2003-09-30 devnull void threadexitsall(char *status)
90 b2cfc4e2 2003-09-30 devnull void yield(void)
91 df970459 2006-06-26 devnull int threadpin(void)
92 df970459 2006-06-26 devnull int threadunpin(void)
94 b2cfc4e2 2003-09-30 devnull int threadid(void)
95 b2cfc4e2 2003-09-30 devnull int threadgrp(void)
96 b2cfc4e2 2003-09-30 devnull int threadsetgrp(int group)
97 b2cfc4e2 2003-09-30 devnull int threadpid(int id)
99 b2cfc4e2 2003-09-30 devnull int threadint(int id)
100 b2cfc4e2 2003-09-30 devnull int threadintgrp(int group)
101 b2cfc4e2 2003-09-30 devnull int threadkill(int id)
102 b2cfc4e2 2003-09-30 devnull int threadkillgrp(int group)
104 b2cfc4e2 2003-09-30 devnull void threadsetname(char *name)
105 b2cfc4e2 2003-09-30 devnull char* threadgetname(void)
107 b2cfc4e2 2003-09-30 devnull void** threaddata(void)
108 b2cfc4e2 2003-09-30 devnull void** procdata(void)
110 b2cfc4e2 2003-09-30 devnull Channel* chancreate(int elsize, int nel)
111 b2cfc4e2 2003-09-30 devnull void chanfree(Channel *c)
113 b2cfc4e2 2003-09-30 devnull int alt(Alt *alts)
114 b2cfc4e2 2003-09-30 devnull int recv(Channel *c, void *v)
115 b2cfc4e2 2003-09-30 devnull void* recvp(Channel *c)
116 b2cfc4e2 2003-09-30 devnull ulong recvul(Channel *c)
117 b2cfc4e2 2003-09-30 devnull int nbrecv(Channel *c, void *v)
118 b2cfc4e2 2003-09-30 devnull void* nbrecvp(Channel *c)
119 b2cfc4e2 2003-09-30 devnull ulong nbrecvul(Channel *c)
120 b2cfc4e2 2003-09-30 devnull int send(Channel *c, void *v)
121 b2cfc4e2 2003-09-30 devnull int sendp(Channel *c, void *v)
122 b2cfc4e2 2003-09-30 devnull int sendul(Channel *c, ulong v)
123 b2cfc4e2 2003-09-30 devnull int nbsend(Channel *c, void *v)
124 b2cfc4e2 2003-09-30 devnull int nbsendp(Channel *c, void *v)
125 b2cfc4e2 2003-09-30 devnull int nbsendul(Channel *c, ulong v)
126 b2cfc4e2 2003-09-30 devnull int chanprint(Channel *c, char *fmt, ...)
128 e4d62adf 2005-01-18 devnull int threadspawnl(int fd[3], char *file, ...)
129 058b0118 2005-01-03 devnull int threadspawn(int fd[3], char *file, char *args[])
130 9e4b56e7 2012-10-22 rsc int threadspawnd(int fd[3], char *file, char *args[], char *dir)
131 058b0118 2005-01-03 devnull int threadexecl(Channel *cpid, int fd[3], char *file, ...)
132 058b0118 2005-01-03 devnull int threadexec(Channel *cpid, int fd[3], char *file, char *args[])
133 b2cfc4e2 2003-09-30 devnull Channel* threadwaitchan(void)
135 b2cfc4e2 2003-09-30 devnull int threadnotify(int (*f)(void*, char*), int in)
137 b2cfc4e2 2003-09-30 devnull .SH DESCRIPTION
139 b2cfc4e2 2003-09-30 devnull The thread library provides parallel programming support similar to that
140 b2cfc4e2 2003-09-30 devnull of the languages
141 b2cfc4e2 2003-09-30 devnull Alef and Newsqueak.
145 b2cfc4e2 2003-09-30 devnull occupy a shared address space,
146 b2cfc4e2 2003-09-30 devnull communicating and synchronizing through
147 b2cfc4e2 2003-09-30 devnull .I channels
148 b2cfc4e2 2003-09-30 devnull and shared variables.
152 b2cfc4e2 2003-09-30 devnull is a Plan 9 process that contains one or more cooperatively scheduled
153 b2cfc4e2 2003-09-30 devnull .IR threads .
154 b2cfc4e2 2003-09-30 devnull Programs using threads must replace
157 b2cfc4e2 2003-09-30 devnull .IR threadmain .
158 b2cfc4e2 2003-09-30 devnull The thread library provides a
160 b2cfc4e2 2003-09-30 devnull function that sets up a proc with a single thread executing
161 e68f07d4 2020-12-30 rsc .IR threadmain .
163 e68f07d4 2020-12-30 rsc Every thread is backed by an operating system-provided
165 e68f07d4 2020-12-30 rsc and runs on its system-provided stack;
166 e68f07d4 2020-12-30 rsc .I mainstacksize
167 e68f07d4 2020-12-30 rsc and the the stack size arguments to
168 e68f07d4 2020-12-30 rsc .I proccreate
170 e68f07d4 2020-12-30 rsc .I threadcreate
171 e68f07d4 2020-12-30 rsc are ignored.
172 e68f07d4 2020-12-30 rsc Although each thread is backed by a separate
173 e68f07d4 2020-12-30 rsc .IR pthread ,
174 e68f07d4 2020-12-30 rsc the threads in a proc are still scheduled non-preemptively
175 e68f07d4 2020-12-30 rsc as on Plan 9 and as described below.
177 b2cfc4e2 2003-09-30 devnull .I Threadcreate
178 b2cfc4e2 2003-09-30 devnull creates a new thread in the calling proc, returning a unique integer
179 b2cfc4e2 2003-09-30 devnull identifying the thread; the thread
180 b2cfc4e2 2003-09-30 devnull executes
181 b2cfc4e2 2003-09-30 devnull .I fn(arg)
182 b2cfc4e2 2003-09-30 devnull on a stack of size
183 b2cfc4e2 2003-09-30 devnull .IR stacksize .
184 b3a20a96 2020-12-30 rsc Thread stacks are allocated in shared memory, making it valid to pass
185 b2cfc4e2 2003-09-30 devnull pointers to stack variables between threads and procs.
186 058b0118 2005-01-03 devnull .I Proccreate
187 b2cfc4e2 2003-09-30 devnull creates a new proc, and inside that proc creates
188 b2cfc4e2 2003-09-30 devnull a single thread as
189 b2cfc4e2 2003-09-30 devnull .I threadcreate
191 b2cfc4e2 2003-09-30 devnull returning the id of the created thread.
192 058b0118 2005-01-03 devnull .\" .I Procrfork
193 058b0118 2005-01-03 devnull .\" creates the new proc by calling
194 058b0118 2005-01-03 devnull .\" .B rfork
195 058b0118 2005-01-03 devnull .\" (see
196 058b0118 2005-01-03 devnull .\" .IR fork (3))
197 058b0118 2005-01-03 devnull .\" with flags
198 058b0118 2005-01-03 devnull .\" .BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR.
199 058b0118 2005-01-03 devnull .\" (The thread library depends on all its procs
200 058b0118 2005-01-03 devnull .\" running in the same rendezvous group.
201 058b0118 2005-01-03 devnull .\" Do not include
202 058b0118 2005-01-03 devnull .\" .B RFREND
204 058b0118 2005-01-03 devnull .\" .IR rforkflag .)
205 058b0118 2005-01-03 devnull .\" .I Proccreate
206 b3a20a96 2020-12-30 rsc .\" is identical to
207 058b0118 2005-01-03 devnull .\" .I procrfork
208 058b0118 2005-01-03 devnull .\" with
209 058b0118 2005-01-03 devnull .\" .I rforkflag
210 058b0118 2005-01-03 devnull .\" set to zero.
211 b2cfc4e2 2003-09-30 devnull Be aware that the calling thread may continue
212 b2cfc4e2 2003-09-30 devnull execution before
213 b2cfc4e2 2003-09-30 devnull the newly created proc and thread
214 b2cfc4e2 2003-09-30 devnull are scheduled.
215 b2cfc4e2 2003-09-30 devnull Because of this,
217 b2cfc4e2 2003-09-30 devnull should not point to data on the stack of a function that could
218 b2cfc4e2 2003-09-30 devnull return before the new process is scheduled.
220 b2cfc4e2 2003-09-30 devnull .I Threadexits
221 b2cfc4e2 2003-09-30 devnull terminates the calling thread.
222 b2cfc4e2 2003-09-30 devnull If the thread is the last in its proc,
223 b2cfc4e2 2003-09-30 devnull .I threadexits
224 b2cfc4e2 2003-09-30 devnull also terminates the proc, using
225 b2cfc4e2 2003-09-30 devnull .I status
226 b2cfc4e2 2003-09-30 devnull as the exit status.
227 b2cfc4e2 2003-09-30 devnull .I Threadexitsall
228 b2cfc4e2 2003-09-30 devnull terminates all procs in the program,
230 b2cfc4e2 2003-09-30 devnull .I status
231 b2cfc4e2 2003-09-30 devnull as the exit status.
233 058b0118 2005-01-03 devnull When the last thread in
234 058b0118 2005-01-03 devnull .IR threadmain 's
235 058b0118 2005-01-03 devnull proc exits, the program will appear to its parent to have exited.
236 058b0118 2005-01-03 devnull The remaining procs will still run together, but as a background program.
237 b3a20a96 2020-12-30 rsc This functionality can only be relied upon if the program defines a function
238 b3a20a96 2020-12-30 rsc .I threadmaybackground
239 b3a20a96 2020-12-30 rsc returning a non-zero result.
240 b3a20a96 2020-12-30 rsc Programs that do not define such a
241 b3a20a96 2020-12-30 rsc .I threadmaybackground
242 b3a20a96 2020-12-30 rsc will crash instead should the last thread in
243 b3a20a96 2020-12-30 rsc .IR threadmain 's
244 b3a20a96 2020-12-30 rsc proc exit leaving behind other running procs.
246 b2cfc4e2 2003-09-30 devnull The threads in a proc are coroutines, scheduled nonpreemptively
247 b2cfc4e2 2003-09-30 devnull in a round-robin fashion.
248 b2cfc4e2 2003-09-30 devnull A thread must explicitly relinquish control of the processor
249 b2cfc4e2 2003-09-30 devnull before another thread in the same proc is run.
250 b2cfc4e2 2003-09-30 devnull Calls that do this are
251 b2cfc4e2 2003-09-30 devnull .IR yield ,
252 b2cfc4e2 2003-09-30 devnull .IR proccreate ,
253 058b0118 2005-01-03 devnull .IR threadexec ,
254 058b0118 2005-01-03 devnull .IR threadexecl ,
255 b2cfc4e2 2003-09-30 devnull .IR threadexits ,
256 058b0118 2005-01-03 devnull .IR threadspawn ,
257 9e4b56e7 2012-10-22 rsc .IR threadspawnd ,
258 9e4b56e7 2012-10-22 rsc .IR threadspawnl ,
259 b2cfc4e2 2003-09-30 devnull .IR alt ,
260 b2cfc4e2 2003-09-30 devnull .IR send ,
263 b2cfc4e2 2003-09-30 devnull (and the calls related to
266 b2cfc4e2 2003-09-30 devnull .IR recv \(emsee
267 b2cfc4e2 2003-09-30 devnull their descriptions further on).
268 b2cfc4e2 2003-09-30 devnull Procs are scheduled by the operating system.
269 b2cfc4e2 2003-09-30 devnull Therefore, threads in different procs can preempt one another
270 b2cfc4e2 2003-09-30 devnull in arbitrary ways and should synchronize their
271 b2cfc4e2 2003-09-30 devnull actions using
272 b2cfc4e2 2003-09-30 devnull .B qlocks
274 d32deab1 2020-08-16 rsc .MR lock (3) )
275 b2cfc4e2 2003-09-30 devnull or channel communication.
276 b2cfc4e2 2003-09-30 devnull System calls such as
277 d32deab1 2020-08-16 rsc .MR read (3)
278 b2cfc4e2 2003-09-30 devnull block the entire proc;
279 b2cfc4e2 2003-09-30 devnull all threads in a proc block until the system call finishes.
281 df970459 2006-06-26 devnull .I Threadpin
282 df970459 2006-06-26 devnull disables scheduling inside a proc, `pinning' the current
283 df970459 2006-06-26 devnull thread as the only runnable one in the current proc.
284 df970459 2006-06-26 devnull .I Threadunpin
285 df970459 2006-06-26 devnull reenables scheduling, allowing other procs to run once the current
286 df970459 2006-06-26 devnull thread relinquishes the processor.
287 df970459 2006-06-26 devnull .I Threadpin
289 df970459 2006-06-26 devnull .I threadunpin
290 df970459 2006-06-26 devnull can lead to deadlock.
291 df970459 2006-06-26 devnull Used carefully, they can make library routines that use
292 df970459 2006-06-26 devnull .B qlocks
293 df970459 2006-06-26 devnull appear atomic relative to the current proc, like a system call.
295 b2cfc4e2 2003-09-30 devnull As mentioned above, each thread has a unique integer thread id.
296 b2cfc4e2 2003-09-30 devnull Thread ids are not reused; they are unique across the life of the program.
297 b2cfc4e2 2003-09-30 devnull .I Threadid
298 b2cfc4e2 2003-09-30 devnull returns the id for the current thread.
299 b2cfc4e2 2003-09-30 devnull Each thread also has a thread group id.
300 b2cfc4e2 2003-09-30 devnull The initial thread has a group id of zero.
301 b2cfc4e2 2003-09-30 devnull Each new thread inherits the group id of
302 b2cfc4e2 2003-09-30 devnull the thread that created it.
303 b2cfc4e2 2003-09-30 devnull .I Threadgrp
304 b2cfc4e2 2003-09-30 devnull returns the group id for the current thread;
305 b2cfc4e2 2003-09-30 devnull .I threadsetgrp
306 b2cfc4e2 2003-09-30 devnull sets it.
307 b2cfc4e2 2003-09-30 devnull .I Threadpid
308 b2cfc4e2 2003-09-30 devnull returns the pid of the Plan 9 process containing
309 b2cfc4e2 2003-09-30 devnull the thread identified by
310 b2cfc4e2 2003-09-30 devnull .IR id ,
312 b2cfc4e2 2003-09-30 devnull if no such thread is found.
314 b2cfc4e2 2003-09-30 devnull .I Threadint
315 b2cfc4e2 2003-09-30 devnull interrupts a thread that is blocked in a channel operation
316 b2cfc4e2 2003-09-30 devnull or system call.
317 b2cfc4e2 2003-09-30 devnull .I Threadintgrp
318 b2cfc4e2 2003-09-30 devnull interrupts all threads with the given group id.
319 b2cfc4e2 2003-09-30 devnull .I Threadkill
320 b2cfc4e2 2003-09-30 devnull marks a thread to die when it next relinquishes the processor
321 b2cfc4e2 2003-09-30 devnull (via one of the calls listed above).
322 b2cfc4e2 2003-09-30 devnull If the thread is blocked in a channel operation or system call,
323 b2cfc4e2 2003-09-30 devnull it is also interrupted.
324 b2cfc4e2 2003-09-30 devnull .I Threadkillgrp
325 b2cfc4e2 2003-09-30 devnull kills all threads with the given group id.
326 b2cfc4e2 2003-09-30 devnull Note that
327 b2cfc4e2 2003-09-30 devnull .I threadkill
329 b2cfc4e2 2003-09-30 devnull .I threadkillgrp
330 b2cfc4e2 2003-09-30 devnull will not terminate a thread that never relinquishes
331 b2cfc4e2 2003-09-30 devnull the processor.
333 b2cfc4e2 2003-09-30 devnull Primarily for debugging,
334 b2cfc4e2 2003-09-30 devnull threads can have string names associated with them.
335 b2cfc4e2 2003-09-30 devnull .I Threadgetname
336 b2cfc4e2 2003-09-30 devnull returns the current thread's name;
337 b2cfc4e2 2003-09-30 devnull .I threadsetname
338 b2cfc4e2 2003-09-30 devnull sets it.
339 b2cfc4e2 2003-09-30 devnull The pointer returned by
340 b2cfc4e2 2003-09-30 devnull .I threadgetname
341 b2cfc4e2 2003-09-30 devnull is only valid until the next call to
342 b2cfc4e2 2003-09-30 devnull .IR threadsetname .
344 058b0118 2005-01-03 devnull Also for debugging,
345 058b0118 2005-01-03 devnull threads have a string state associated with them.
346 058b0118 2005-01-03 devnull .I Threadsetstate
347 058b0118 2005-01-03 devnull sets the state string.
349 058b0118 2005-01-03 devnull .IR threadgetstate ;
350 058b0118 2005-01-03 devnull since the thread scheduler resets the state to
351 058b0118 2005-01-03 devnull .B Running
352 b3a20a96 2020-12-30 rsc every time it runs the thread,
353 058b0118 2005-01-03 devnull it is only useful for debuggers to inspect the state.
355 b2cfc4e2 2003-09-30 devnull .I Threaddata
356 b2cfc4e2 2003-09-30 devnull returns a pointer to a per-thread pointer
357 b2cfc4e2 2003-09-30 devnull that may be modified by threaded programs for
358 b2cfc4e2 2003-09-30 devnull per-thread storage.
360 b2cfc4e2 2003-09-30 devnull .I procdata
361 b2cfc4e2 2003-09-30 devnull returns a pointer to a per-proc pointer.
363 058b0118 2005-01-03 devnull .I Threadexecl
365 058b0118 2005-01-03 devnull .I threadexec
366 b2cfc4e2 2003-09-30 devnull are threaded analogues of
369 b2cfc4e2 2003-09-30 devnull .I execl
371 d32deab1 2020-08-16 rsc .MR exec (3) );
372 b2cfc4e2 2003-09-30 devnull on success,
373 058b0118 2005-01-03 devnull they replace the calling thread
374 b2cfc4e2 2003-09-30 devnull and invoke the external program, never returning.
375 058b0118 2005-01-03 devnull (Unlike on Plan 9, the calling thread need not be the only thread in its proc\(emthe other
376 058b0118 2005-01-03 devnull threads will continue executing.)
377 b2cfc4e2 2003-09-30 devnull On error, they return \-1.
380 b2cfc4e2 2003-09-30 devnull is not null, the pid of the invoked program
381 b2cfc4e2 2003-09-30 devnull will be sent along
384 058b0118 2005-01-03 devnull .IR sendul )
385 b2cfc4e2 2003-09-30 devnull once the program has been started, or \-1 will be sent if an
386 b2cfc4e2 2003-09-30 devnull error occurs.
387 058b0118 2005-01-03 devnull .I Threadexec
389 058b0118 2005-01-03 devnull .I threadexecl
390 b2cfc4e2 2003-09-30 devnull will not access their arguments after sending a result
392 b2cfc4e2 2003-09-30 devnull .IR cpid .
393 b2cfc4e2 2003-09-30 devnull Thus, programs that malloc the
395 b2cfc4e2 2003-09-30 devnull passed to
396 058b0118 2005-01-03 devnull .I threadexec
397 b2cfc4e2 2003-09-30 devnull can safely free it once they have
398 b2cfc4e2 2003-09-30 devnull received the
400 b2cfc4e2 2003-09-30 devnull response.
402 058b0118 2005-01-03 devnull .I Threadexecl
404 058b0118 2005-01-03 devnull .I threadexec
405 b3a20a96 2020-12-30 rsc will duplicate
407 d32deab1 2020-08-16 rsc .MR dup (3) )
408 058b0118 2005-01-03 devnull the three file descriptors in
410 058b0118 2005-01-03 devnull onto standard input, output, and error for the external program
411 058b0118 2005-01-03 devnull and then close them in the calling thread.
412 058b0118 2005-01-03 devnull Beware of code that sets
415 058b0118 2005-01-03 devnull fd[0] = 0;
416 058b0118 2005-01-03 devnull fd[1] = 1;
417 058b0118 2005-01-03 devnull fd[2] = 2;
420 058b0118 2005-01-03 devnull to use the current standard files. The correct code is
423 058b0118 2005-01-03 devnull fd[0] = dup(0, -1);
424 058b0118 2005-01-03 devnull fd[1] = dup(1, -1);
425 058b0118 2005-01-03 devnull fd[2] = dup(2, -1);
428 e4d62adf 2005-01-18 devnull .I Threadspawnl
430 e4d62adf 2005-01-18 devnull .I threadspawn
431 e4d62adf 2005-01-18 devnull are like
432 e4d62adf 2005-01-18 devnull .I threadexecl
434 058b0118 2005-01-03 devnull .I threadexec
435 e4d62adf 2005-01-18 devnull but do not replace the current thread.
436 e4d62adf 2005-01-18 devnull They return the pid of the invoked program on success, or
437 058b0118 2005-01-03 devnull \-1 on error.
438 9e4b56e7 2012-10-22 rsc .I Threadspawnd
440 9e4b56e7 2012-10-22 rsc .I threadspawn
441 9e4b56e7 2012-10-22 rsc but takes as its final argument the directory in which to run the invoked program.
442 9e4b56e7 2012-10-22 rsc The child will attempt to change into that directory before running the program,
443 9e4b56e7 2012-10-22 rsc but it is only best effort: failure to change into the directory does not
444 9e4b56e7 2012-10-22 rsc stop the running of the program.
446 b2cfc4e2 2003-09-30 devnull .I Threadwaitchan
447 b2cfc4e2 2003-09-30 devnull returns a channel of pointers to
448 b2cfc4e2 2003-09-30 devnull .B Waitmsg
449 b2cfc4e2 2003-09-30 devnull structures (see
450 d32deab1 2020-08-16 rsc .MR wait (3) ).
451 b2cfc4e2 2003-09-30 devnull When an exec'ed process exits, a pointer to a
452 b2cfc4e2 2003-09-30 devnull .B Waitmsg
453 b2cfc4e2 2003-09-30 devnull is sent to this channel.
455 b2cfc4e2 2003-09-30 devnull .B Waitmsg
456 b2cfc4e2 2003-09-30 devnull structures have been allocated with
457 d32deab1 2020-08-16 rsc .MR malloc (3)
458 b2cfc4e2 2003-09-30 devnull and should be freed after use.
461 b2cfc4e2 2003-09-30 devnull .B Channel
462 b2cfc4e2 2003-09-30 devnull is a buffered or unbuffered queue for fixed-size messages.
463 b2cfc4e2 2003-09-30 devnull Procs and threads
465 b2cfc4e2 2003-09-30 devnull messages into the channel and
467 b2cfc4e2 2003-09-30 devnull messages from the channel. If the channel is unbuffered, a
469 b2cfc4e2 2003-09-30 devnull operation blocks until the corresponding
471 b2cfc4e2 2003-09-30 devnull operation occurs and
472 b2cfc4e2 2003-09-30 devnull .IR "vice versa" .
473 9ea7f9d8 2009-04-30 rsc .IR Chancreate
474 b3a20a96 2020-12-30 rsc allocates a new channel
475 b2cfc4e2 2003-09-30 devnull for messages of size
477 b2cfc4e2 2003-09-30 devnull and with a buffer holding
479 b2cfc4e2 2003-09-30 devnull messages.
482 b2cfc4e2 2003-09-30 devnull is zero, the channel is unbuffered.
483 b2cfc4e2 2003-09-30 devnull .I Chanfree
484 b2cfc4e2 2003-09-30 devnull frees a channel that is no longer used.
485 b2cfc4e2 2003-09-30 devnull .I Chanfree
486 b2cfc4e2 2003-09-30 devnull can be called by either sender or receiver after the last item has been
487 b2cfc4e2 2003-09-30 devnull sent or received. Freeing the channel will be delayed if there is a thread
488 b2cfc4e2 2003-09-30 devnull blocked on it until that thread unblocks (but
489 b2cfc4e2 2003-09-30 devnull .I chanfree
490 b2cfc4e2 2003-09-30 devnull returns immediately).
494 058b0118 2005-01-03 devnull element in the
495 058b0118 2005-01-03 devnull .B Channel
496 058b0118 2005-01-03 devnull structure is a description intended for use in debugging.
497 058b0118 2005-01-03 devnull .I Chansetname
498 058b0118 2005-01-03 devnull sets the name.
501 b2cfc4e2 2003-09-30 devnull sends the element pointed at by
503 b2cfc4e2 2003-09-30 devnull to the channel
507 b2cfc4e2 2003-09-30 devnull is null, zeros are sent.
509 b2cfc4e2 2003-09-30 devnull receives an element from
511 b2cfc4e2 2003-09-30 devnull and stores it in
515 b2cfc4e2 2003-09-30 devnull is null,
516 b2cfc4e2 2003-09-30 devnull the received value is discarded.
520 b2cfc4e2 2003-09-30 devnull return 1 on success, \-1 if interrupted.
521 b2cfc4e2 2003-09-30 devnull .I Nbsend
523 b2cfc4e2 2003-09-30 devnull .I nbrecv
524 b2cfc4e2 2003-09-30 devnull behave similarly, but return 0 rather than blocking.
526 b2cfc4e2 2003-09-30 devnull .IR Sendp ,
527 b2cfc4e2 2003-09-30 devnull .IR nbsendp ,
528 b2cfc4e2 2003-09-30 devnull .IR sendul ,
530 b2cfc4e2 2003-09-30 devnull .I nbsendul
531 b2cfc4e2 2003-09-30 devnull send a pointer or an unsigned long; the channel must
532 b2cfc4e2 2003-09-30 devnull have been initialized with the appropriate
533 b2cfc4e2 2003-09-30 devnull .IR elsize .
534 b2cfc4e2 2003-09-30 devnull .IR Recvp ,
535 b2cfc4e2 2003-09-30 devnull .IR nbrecvp ,
536 b2cfc4e2 2003-09-30 devnull .IR recvul ,
538 b2cfc4e2 2003-09-30 devnull .I nbrecvul
539 b2cfc4e2 2003-09-30 devnull receive a pointer or an unsigned long;
540 b2cfc4e2 2003-09-30 devnull they return zero when a zero is received,
541 b2cfc4e2 2003-09-30 devnull when interrupted, or
543 b2cfc4e2 2003-09-30 devnull .I nbrecvp
545 b2cfc4e2 2003-09-30 devnull .IR nbrecvul )
546 b2cfc4e2 2003-09-30 devnull when the operation would have blocked.
547 b2cfc4e2 2003-09-30 devnull To distinguish between these three cases,
551 b2cfc4e2 2003-09-30 devnull .IR nbrecv .
554 b2cfc4e2 2003-09-30 devnull can be used to recv from or send to one of a number of channels,
555 b2cfc4e2 2003-09-30 devnull as directed by an array of
557 b2cfc4e2 2003-09-30 devnull structures,
558 b2cfc4e2 2003-09-30 devnull each of which describes a potential send or receive operation.
561 b2cfc4e2 2003-09-30 devnull structure,
563 b2cfc4e2 2003-09-30 devnull is the channel;
565 b2cfc4e2 2003-09-30 devnull the value pointer (which may be null); and
567 b2cfc4e2 2003-09-30 devnull the operation:
568 b2cfc4e2 2003-09-30 devnull .B CHANSND
569 b2cfc4e2 2003-09-30 devnull for a send operation,
570 b2cfc4e2 2003-09-30 devnull .B CHANRECV
571 b2cfc4e2 2003-09-30 devnull for a recv operation;
572 b2cfc4e2 2003-09-30 devnull .B CHANNOP
573 b2cfc4e2 2003-09-30 devnull for no operation
577 b2cfc4e2 2003-09-30 devnull is called with a varying set of operations).
578 b2cfc4e2 2003-09-30 devnull The array of
580 b2cfc4e2 2003-09-30 devnull structures is terminated by an entry with
582 b2cfc4e2 2003-09-30 devnull .B CHANEND
584 b2cfc4e2 2003-09-30 devnull .BR CHANNOBLK .
585 b2cfc4e2 2003-09-30 devnull If at least one
587 b2cfc4e2 2003-09-30 devnull structure can proceed, one of them is
588 b2cfc4e2 2003-09-30 devnull chosen at random to be executed.
590 b2cfc4e2 2003-09-30 devnull returns the index of the chosen structure.
591 b2cfc4e2 2003-09-30 devnull If no operations can proceed and the list is terminated with
592 b2cfc4e2 2003-09-30 devnull .BR CHANNOBLK ,
594 b2cfc4e2 2003-09-30 devnull returns the index of the terminating
595 b2cfc4e2 2003-09-30 devnull .B CHANNOBLK
596 b2cfc4e2 2003-09-30 devnull structure.
597 b2cfc4e2 2003-09-30 devnull Otherwise,
599 b2cfc4e2 2003-09-30 devnull blocks until one of the operations can proceed,
600 b2cfc4e2 2003-09-30 devnull eventually returning the index of the structure executes.
602 b2cfc4e2 2003-09-30 devnull returns \-1 when interrupted.
606 b2cfc4e2 2003-09-30 devnull .B entryno
607 b2cfc4e2 2003-09-30 devnull fields in the
609 b2cfc4e2 2003-09-30 devnull structure are used internally by
611 b2cfc4e2 2003-09-30 devnull and need not be initialized.
612 b2cfc4e2 2003-09-30 devnull They are not used between
616 b2cfc4e2 2003-09-30 devnull .I Chanprint
617 b2cfc4e2 2003-09-30 devnull formats its arguments in the manner of
618 d32deab1 2020-08-16 rsc .MR print (3)
619 b2cfc4e2 2003-09-30 devnull and sends the result to the channel
621 b2cfc4e2 2003-09-30 devnull The string delivered by
622 b2cfc4e2 2003-09-30 devnull .I chanprint
623 b2cfc4e2 2003-09-30 devnull is allocated with
624 d32deab1 2020-08-16 rsc .MR malloc (3)
625 b2cfc4e2 2003-09-30 devnull and should be freed upon receipt.
627 b2cfc4e2 2003-09-30 devnull Thread library functions do not return on failure;
628 b2cfc4e2 2003-09-30 devnull if errors occur, the entire program is aborted.
630 b2cfc4e2 2003-09-30 devnull Threaded programs should use
631 b2cfc4e2 2003-09-30 devnull .I threadnotify
632 b2cfc4e2 2003-09-30 devnull in place of
633 b2cfc4e2 2003-09-30 devnull .I atnotify
635 d32deab1 2020-08-16 rsc .MR notify (3) ).
637 b2cfc4e2 2003-09-30 devnull It is safe to use
638 d32deab1 2020-08-16 rsc .MR sysfatal (3)
639 b2cfc4e2 2003-09-30 devnull in threaded programs.
640 b2cfc4e2 2003-09-30 devnull .I Sysfatal
641 b2cfc4e2 2003-09-30 devnull will print the error string and call
642 b2cfc4e2 2003-09-30 devnull .IR threadexitsall .
644 058b0118 2005-01-03 devnull It is not safe to call
645 b2cfc4e2 2003-09-30 devnull .IR rfork
646 058b0118 2005-01-03 devnull in a threaded program, except to call
647 058b0118 2005-01-03 devnull .B rfork(RFNOTEG)
648 058b0118 2005-01-03 devnull from the main proc before any other procs have been created.
649 058b0118 2005-01-03 devnull To create new processes, use
650 058b0118 2005-01-03 devnull .IR proccreate .
652 b3a20a96 2020-12-30 rsc .\" It is safe to use
653 058b0118 2005-01-03 devnull .\" .IR rfork
654 058b0118 2005-01-03 devnull .\" (see
655 058b0118 2005-01-03 devnull .\" .IR fork (3))
656 058b0118 2005-01-03 devnull .\" to manage the namespace, file descriptors, note group, and environment of a
657 058b0118 2005-01-03 devnull .\" single process.
658 058b0118 2005-01-03 devnull .\" That is, it is safe to call
659 058b0118 2005-01-03 devnull .\" .I rfork
660 058b0118 2005-01-03 devnull .\" with the flags
661 058b0118 2005-01-03 devnull .\" .BR RFNAMEG ,
662 058b0118 2005-01-03 devnull .\" .BR RFFDG ,
663 058b0118 2005-01-03 devnull .\" .BR RFCFDG ,
664 058b0118 2005-01-03 devnull .\" .BR RFNOTEG ,
665 058b0118 2005-01-03 devnull .\" .BR RFENVG ,
667 058b0118 2005-01-03 devnull .\" .BR RFCENVG.
668 058b0118 2005-01-03 devnull .\" (To create new processes, use
669 058b0118 2005-01-03 devnull .\" .I proccreate
671 058b0118 2005-01-03 devnull .\" .IR procrfork .)
672 058b0118 2005-01-03 devnull .\" As mentioned above,
673 058b0118 2005-01-03 devnull .\" the thread library depends on all procs being in the
674 058b0118 2005-01-03 devnull .\" same rendezvous group; do not change the rendezvous
675 058b0118 2005-01-03 devnull .\" group with
676 058b0118 2005-01-03 devnull .\" .IR rfork .
677 b2cfc4e2 2003-09-30 devnull .SH FILES
678 c3674de4 2005-01-11 devnull .B \*9/acid/thread
679 b2cfc4e2 2003-09-30 devnull contains useful
680 d32deab1 2020-08-16 rsc .MR acid (1)
681 b2cfc4e2 2003-09-30 devnull functions for debugging threaded programs.
683 c3674de4 2005-01-11 devnull .B \*9/src/libthread/test
684 058b0118 2005-01-03 devnull contains some example programs.
685 b2cfc4e2 2003-09-30 devnull .SH SOURCE
686 c3674de4 2005-01-11 devnull .B \*9/src/libthread
687 b2cfc4e2 2003-09-30 devnull .SH SEE ALSO
688 d32deab1 2020-08-16 rsc .MR intro (3) ,
689 d32deab1 2020-08-16 rsc .MR ioproc (3)
690 058b0118 2005-01-03 devnull .SH BUGS
691 058b0118 2005-01-03 devnull To avoid name conflicts,
692 058b0118 2005-01-03 devnull .IR alt ,
693 058b0118 2005-01-03 devnull .IR nbrecv ,
694 058b0118 2005-01-03 devnull .IR nbrecvp ,
695 058b0118 2005-01-03 devnull .IR nbrecvul ,
696 058b0118 2005-01-03 devnull .IR nbsend ,
697 058b0118 2005-01-03 devnull .IR nbsendp ,
698 058b0118 2005-01-03 devnull .IR nbsendul ,
699 058b0118 2005-01-03 devnull .IR recv ,
700 058b0118 2005-01-03 devnull .IR recvp ,
701 058b0118 2005-01-03 devnull .IR recvul ,
702 058b0118 2005-01-03 devnull .IR send ,
703 058b0118 2005-01-03 devnull .IR sendp ,
705 058b0118 2005-01-03 devnull .IR sendul
706 058b0118 2005-01-03 devnull are defined as macros that expand to
707 058b0118 2005-01-03 devnull .IR chanalt ,
708 058b0118 2005-01-03 devnull .IR channbrecv ,
709 058b0118 2005-01-03 devnull and so on.
710 c8b6342d 2005-01-13 devnull .I Yield
711 058b0118 2005-01-03 devnull is defined as a macro that expands to
712 058b0118 2005-01-03 devnull .IR threadyield .
714 d32deab1 2020-08-16 rsc .MR intro (3) .
716 e1df0680 2008-07-21 t.lainson Threadint,
717 e1df0680 2008-07-21 t.lainson threadintgrp,
718 e1df0680 2008-07-21 t.lainson threadkill,
719 e1df0680 2008-07-21 t.lainson threadkillgrp and threadpid are unimplemented.
721 058b0118 2005-01-03 devnull The implementation of
722 058b0118 2005-01-03 devnull .I threadnotify
723 058b0118 2005-01-03 devnull may not be correct.
725 33488b09 2005-03-18 devnull There appears to be a race in the Linux NPTL
726 33488b09 2005-03-18 devnull implementation of
727 33488b09 2005-03-18 devnull .I pthread_exit .
729 33488b09 2005-03-18 devnull .I threadexitsall
730 33488b09 2005-03-18 devnull rather than coordinating a simultaneous
731 33488b09 2005-03-18 devnull .I threadexits
732 33488b09 2005-03-18 devnull among many threads.
