1 b2cfc4e2 2003-09-30 devnull .TH THREAD 2
4 b2cfc4e2 2003-09-30 devnull chancreate,
7 b2cfc4e2 2003-09-30 devnull chanprint,
8 b2cfc4e2 2003-09-30 devnull mainstacksize,
9 b2cfc4e2 2003-09-30 devnull proccreate,
10 b2cfc4e2 2003-09-30 devnull procdata,
11 b2cfc4e2 2003-09-30 devnull procexec,
12 b2cfc4e2 2003-09-30 devnull procexecl,
13 b2cfc4e2 2003-09-30 devnull procrfork,
22 b2cfc4e2 2003-09-30 devnull nbrecvul,
25 b2cfc4e2 2003-09-30 devnull nbsendul,
26 b2cfc4e2 2003-09-30 devnull threadcreate,
27 b2cfc4e2 2003-09-30 devnull threaddata,
28 b2cfc4e2 2003-09-30 devnull threadexits,
29 b2cfc4e2 2003-09-30 devnull threadexitsall,
30 b2cfc4e2 2003-09-30 devnull threadgetgrp,
31 b2cfc4e2 2003-09-30 devnull threadgetname,
32 b2cfc4e2 2003-09-30 devnull threadint,
33 b2cfc4e2 2003-09-30 devnull threadintgrp,
34 b2cfc4e2 2003-09-30 devnull threadkill,
35 b2cfc4e2 2003-09-30 devnull threadkillgrp,
36 b2cfc4e2 2003-09-30 devnull threadmain,
37 b2cfc4e2 2003-09-30 devnull threadnotify,
38 b2cfc4e2 2003-09-30 devnull threadid,
39 b2cfc4e2 2003-09-30 devnull threadpid,
40 b2cfc4e2 2003-09-30 devnull threadsetgrp,
41 b2cfc4e2 2003-09-30 devnull threadsetname,
42 b2cfc4e2 2003-09-30 devnull threadwaitchan,
43 b2cfc4e2 2003-09-30 devnull yield \- thread and proc management
44 b2cfc4e2 2003-09-30 devnull .SH SYNOPSIS
47 b2cfc4e2 2003-09-30 devnull .ta 4n +4n +4n +4n +4n +4n +4n
48 b2cfc4e2 2003-09-30 devnull #include <u.h>
49 b2cfc4e2 2003-09-30 devnull #include <libc.h>
50 b2cfc4e2 2003-09-30 devnull #include <thread.h>
52 b2cfc4e2 2003-09-30 devnull #define CHANEND 0
53 b2cfc4e2 2003-09-30 devnull #define CHANSND 1
54 b2cfc4e2 2003-09-30 devnull #define CHANRCV 2
55 b2cfc4e2 2003-09-30 devnull #define CHANNOP 3
56 b2cfc4e2 2003-09-30 devnull #define CHANNOBLK 4
58 b2cfc4e2 2003-09-30 devnull .ta \w' 'u +\w'Channel 'u
59 b2cfc4e2 2003-09-30 devnull typedef struct Alt Alt;
60 b2cfc4e2 2003-09-30 devnull struct Alt {
61 b2cfc4e2 2003-09-30 devnull Channel *c;
64 b2cfc4e2 2003-09-30 devnull Channel **tag;
65 b2cfc4e2 2003-09-30 devnull int entryno;
69 b2cfc4e2 2003-09-30 devnull .ift .sp 0.5
75 b2cfc4e2 2003-09-30 devnull .ta \w'\fLChannel* 'u +4n +4n +4n +4n
76 b2cfc4e2 2003-09-30 devnull void threadmain(int argc, char *argv[])
77 b2cfc4e2 2003-09-30 devnull int mainstacksize
78 b2cfc4e2 2003-09-30 devnull int proccreate(void (*fn)(void*), void *arg, uint stacksize)
79 b2cfc4e2 2003-09-30 devnull int procrfork(void (*fn)(void*), void *arg, uint stacksize,
80 b2cfc4e2 2003-09-30 devnull int rforkflag)
81 b2cfc4e2 2003-09-30 devnull int threadcreate(void (*fn)(void*), void *arg, uint stacksize)
82 b2cfc4e2 2003-09-30 devnull void threadexits(char *status)
83 b2cfc4e2 2003-09-30 devnull void threadexitsall(char *status)
84 b2cfc4e2 2003-09-30 devnull void yield(void)
86 b2cfc4e2 2003-09-30 devnull int threadid(void)
87 b2cfc4e2 2003-09-30 devnull int threadgrp(void)
88 b2cfc4e2 2003-09-30 devnull int threadsetgrp(int group)
89 b2cfc4e2 2003-09-30 devnull int threadpid(int id)
91 b2cfc4e2 2003-09-30 devnull int threadint(int id)
92 b2cfc4e2 2003-09-30 devnull int threadintgrp(int group)
93 b2cfc4e2 2003-09-30 devnull int threadkill(int id)
94 b2cfc4e2 2003-09-30 devnull int threadkillgrp(int group)
96 b2cfc4e2 2003-09-30 devnull void threadsetname(char *name)
97 b2cfc4e2 2003-09-30 devnull char* threadgetname(void)
99 b2cfc4e2 2003-09-30 devnull void** threaddata(void)
100 b2cfc4e2 2003-09-30 devnull void** procdata(void)
102 b2cfc4e2 2003-09-30 devnull int chaninit(Channel *c, int elsize, int nel)
103 b2cfc4e2 2003-09-30 devnull Channel* chancreate(int elsize, int nel)
104 b2cfc4e2 2003-09-30 devnull void chanfree(Channel *c)
106 b2cfc4e2 2003-09-30 devnull int alt(Alt *alts)
107 b2cfc4e2 2003-09-30 devnull int recv(Channel *c, void *v)
108 b2cfc4e2 2003-09-30 devnull void* recvp(Channel *c)
109 b2cfc4e2 2003-09-30 devnull ulong recvul(Channel *c)
110 b2cfc4e2 2003-09-30 devnull int nbrecv(Channel *c, void *v)
111 b2cfc4e2 2003-09-30 devnull void* nbrecvp(Channel *c)
112 b2cfc4e2 2003-09-30 devnull ulong nbrecvul(Channel *c)
113 b2cfc4e2 2003-09-30 devnull int send(Channel *c, void *v)
114 b2cfc4e2 2003-09-30 devnull int sendp(Channel *c, void *v)
115 b2cfc4e2 2003-09-30 devnull int sendul(Channel *c, ulong v)
116 b2cfc4e2 2003-09-30 devnull int nbsend(Channel *c, void *v)
117 b2cfc4e2 2003-09-30 devnull int nbsendp(Channel *c, void *v)
118 b2cfc4e2 2003-09-30 devnull int nbsendul(Channel *c, ulong v)
119 b2cfc4e2 2003-09-30 devnull int chanprint(Channel *c, char *fmt, ...)
121 b2cfc4e2 2003-09-30 devnull int procexecl(Channel *cpid, char *file, ...)
122 b2cfc4e2 2003-09-30 devnull int procexec(Channel *cpid, char *file, char *args[])
123 b2cfc4e2 2003-09-30 devnull Channel* threadwaitchan(void)
125 b2cfc4e2 2003-09-30 devnull int threadnotify(int (*f)(void*, char*), int in)
127 b2cfc4e2 2003-09-30 devnull .SH DESCRIPTION
129 b2cfc4e2 2003-09-30 devnull The thread library provides parallel programming support similar to that
130 b2cfc4e2 2003-09-30 devnull of the languages
131 b2cfc4e2 2003-09-30 devnull Alef and Newsqueak.
135 b2cfc4e2 2003-09-30 devnull occupy a shared address space,
136 b2cfc4e2 2003-09-30 devnull communicating and synchronizing through
137 b2cfc4e2 2003-09-30 devnull .I channels
138 b2cfc4e2 2003-09-30 devnull and shared variables.
142 b2cfc4e2 2003-09-30 devnull is a Plan 9 process that contains one or more cooperatively scheduled
143 b2cfc4e2 2003-09-30 devnull .IR threads .
144 b2cfc4e2 2003-09-30 devnull Programs using threads must replace
147 b2cfc4e2 2003-09-30 devnull .IR threadmain .
148 b2cfc4e2 2003-09-30 devnull The thread library provides a
150 b2cfc4e2 2003-09-30 devnull function that sets up a proc with a single thread executing
151 b2cfc4e2 2003-09-30 devnull .I threadmain
152 b2cfc4e2 2003-09-30 devnull on a stack of size
153 b2cfc4e2 2003-09-30 devnull .I mainstacksize
154 b2cfc4e2 2003-09-30 devnull (default eight kilobytes).
156 b2cfc4e2 2003-09-30 devnull .IR mainstacksize ,
157 b2cfc4e2 2003-09-30 devnull declare a global variable
158 b2cfc4e2 2003-09-30 devnull initialized to the desired value
159 b2cfc4e2 2003-09-30 devnull .RI ( e.g. ,
161 b2cfc4e2 2003-09-30 devnull .B mainstacksize
163 b2cfc4e2 2003-09-30 devnull .BR 1024 ).
165 b2cfc4e2 2003-09-30 devnull .I Threadcreate
166 b2cfc4e2 2003-09-30 devnull creates a new thread in the calling proc, returning a unique integer
167 b2cfc4e2 2003-09-30 devnull identifying the thread; the thread
168 b2cfc4e2 2003-09-30 devnull executes
169 b2cfc4e2 2003-09-30 devnull .I fn(arg)
170 b2cfc4e2 2003-09-30 devnull on a stack of size
171 b2cfc4e2 2003-09-30 devnull .IR stacksize .
172 b2cfc4e2 2003-09-30 devnull Thread stacks are allocated in shared memory, making it valid to pass
173 b2cfc4e2 2003-09-30 devnull pointers to stack variables between threads and procs.
174 b2cfc4e2 2003-09-30 devnull .I Procrfork
175 b2cfc4e2 2003-09-30 devnull creates a new proc, and inside that proc creates
176 b2cfc4e2 2003-09-30 devnull a single thread as
177 b2cfc4e2 2003-09-30 devnull .I threadcreate
179 b2cfc4e2 2003-09-30 devnull returning the id of the created thread.
180 b2cfc4e2 2003-09-30 devnull .I Procrfork
181 b2cfc4e2 2003-09-30 devnull creates the new proc by calling
182 b2cfc4e2 2003-09-30 devnull .B rfork
184 b2cfc4e2 2003-09-30 devnull .IR fork (2))
185 b2cfc4e2 2003-09-30 devnull with flags
186 b2cfc4e2 2003-09-30 devnull .BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR.
187 b2cfc4e2 2003-09-30 devnull (The thread library depends on all its procs
188 b2cfc4e2 2003-09-30 devnull running in the same rendezvous group.
189 b2cfc4e2 2003-09-30 devnull Do not include
190 b2cfc4e2 2003-09-30 devnull .B RFREND
192 b2cfc4e2 2003-09-30 devnull .IR rforkflag .)
193 b2cfc4e2 2003-09-30 devnull .I Proccreate
194 b2cfc4e2 2003-09-30 devnull is identical to
195 b2cfc4e2 2003-09-30 devnull .I procrfork
197 b2cfc4e2 2003-09-30 devnull .I rforkflag
198 b2cfc4e2 2003-09-30 devnull set to zero.
199 b2cfc4e2 2003-09-30 devnull Be aware that the calling thread may continue
200 b2cfc4e2 2003-09-30 devnull execution before
201 b2cfc4e2 2003-09-30 devnull the newly created proc and thread
202 b2cfc4e2 2003-09-30 devnull are scheduled.
203 b2cfc4e2 2003-09-30 devnull Because of this,
205 b2cfc4e2 2003-09-30 devnull should not point to data on the stack of a function that could
206 b2cfc4e2 2003-09-30 devnull return before the new process is scheduled.
208 b2cfc4e2 2003-09-30 devnull .I Threadexits
209 b2cfc4e2 2003-09-30 devnull terminates the calling thread.
210 b2cfc4e2 2003-09-30 devnull If the thread is the last in its proc,
211 b2cfc4e2 2003-09-30 devnull .I threadexits
212 b2cfc4e2 2003-09-30 devnull also terminates the proc, using
213 b2cfc4e2 2003-09-30 devnull .I status
214 b2cfc4e2 2003-09-30 devnull as the exit status.
215 b2cfc4e2 2003-09-30 devnull .I Threadexitsall
216 b2cfc4e2 2003-09-30 devnull terminates all procs in the program,
218 b2cfc4e2 2003-09-30 devnull .I status
219 b2cfc4e2 2003-09-30 devnull as the exit status.
221 b2cfc4e2 2003-09-30 devnull The threads in a proc are coroutines, scheduled nonpreemptively
222 b2cfc4e2 2003-09-30 devnull in a round-robin fashion.
223 b2cfc4e2 2003-09-30 devnull A thread must explicitly relinquish control of the processor
224 b2cfc4e2 2003-09-30 devnull before another thread in the same proc is run.
225 b2cfc4e2 2003-09-30 devnull Calls that do this are
226 b2cfc4e2 2003-09-30 devnull .IR yield ,
227 b2cfc4e2 2003-09-30 devnull .IR proccreate ,
228 b2cfc4e2 2003-09-30 devnull .IR procexec ,
229 b2cfc4e2 2003-09-30 devnull .IR procexecl ,
230 b2cfc4e2 2003-09-30 devnull .IR threadexits ,
231 b2cfc4e2 2003-09-30 devnull .IR alt ,
232 b2cfc4e2 2003-09-30 devnull .IR send ,
235 b2cfc4e2 2003-09-30 devnull (and the calls related to
238 b2cfc4e2 2003-09-30 devnull .IR recv \(emsee
239 b2cfc4e2 2003-09-30 devnull their descriptions further on).
240 b2cfc4e2 2003-09-30 devnull Procs are scheduled by the operating system.
241 b2cfc4e2 2003-09-30 devnull Therefore, threads in different procs can preempt one another
242 b2cfc4e2 2003-09-30 devnull in arbitrary ways and should synchronize their
243 b2cfc4e2 2003-09-30 devnull actions using
244 b2cfc4e2 2003-09-30 devnull .B qlocks
246 b2cfc4e2 2003-09-30 devnull .IR lock (2))
247 b2cfc4e2 2003-09-30 devnull or channel communication.
248 b2cfc4e2 2003-09-30 devnull System calls such as
249 b2cfc4e2 2003-09-30 devnull .IR read (2)
250 b2cfc4e2 2003-09-30 devnull block the entire proc;
251 b2cfc4e2 2003-09-30 devnull all threads in a proc block until the system call finishes.
253 b2cfc4e2 2003-09-30 devnull As mentioned above, each thread has a unique integer thread id.
254 b2cfc4e2 2003-09-30 devnull Thread ids are not reused; they are unique across the life of the program.
255 b2cfc4e2 2003-09-30 devnull .I Threadid
256 b2cfc4e2 2003-09-30 devnull returns the id for the current thread.
257 b2cfc4e2 2003-09-30 devnull Each thread also has a thread group id.
258 b2cfc4e2 2003-09-30 devnull The initial thread has a group id of zero.
259 b2cfc4e2 2003-09-30 devnull Each new thread inherits the group id of
260 b2cfc4e2 2003-09-30 devnull the thread that created it.
261 b2cfc4e2 2003-09-30 devnull .I Threadgrp
262 b2cfc4e2 2003-09-30 devnull returns the group id for the current thread;
263 b2cfc4e2 2003-09-30 devnull .I threadsetgrp
264 b2cfc4e2 2003-09-30 devnull sets it.
265 b2cfc4e2 2003-09-30 devnull .I Threadpid
266 b2cfc4e2 2003-09-30 devnull returns the pid of the Plan 9 process containing
267 b2cfc4e2 2003-09-30 devnull the thread identified by
268 b2cfc4e2 2003-09-30 devnull .IR id ,
270 b2cfc4e2 2003-09-30 devnull if no such thread is found.
272 b2cfc4e2 2003-09-30 devnull .I Threadint
273 b2cfc4e2 2003-09-30 devnull interrupts a thread that is blocked in a channel operation
274 b2cfc4e2 2003-09-30 devnull or system call.
275 b2cfc4e2 2003-09-30 devnull .I Threadintgrp
276 b2cfc4e2 2003-09-30 devnull interrupts all threads with the given group id.
277 b2cfc4e2 2003-09-30 devnull .I Threadkill
278 b2cfc4e2 2003-09-30 devnull marks a thread to die when it next relinquishes the processor
279 b2cfc4e2 2003-09-30 devnull (via one of the calls listed above).
280 b2cfc4e2 2003-09-30 devnull If the thread is blocked in a channel operation or system call,
281 b2cfc4e2 2003-09-30 devnull it is also interrupted.
282 b2cfc4e2 2003-09-30 devnull .I Threadkillgrp
283 b2cfc4e2 2003-09-30 devnull kills all threads with the given group id.
284 b2cfc4e2 2003-09-30 devnull Note that
285 b2cfc4e2 2003-09-30 devnull .I threadkill
287 b2cfc4e2 2003-09-30 devnull .I threadkillgrp
288 b2cfc4e2 2003-09-30 devnull will not terminate a thread that never relinquishes
289 b2cfc4e2 2003-09-30 devnull the processor.
291 b2cfc4e2 2003-09-30 devnull Primarily for debugging,
292 b2cfc4e2 2003-09-30 devnull threads can have string names associated with them.
293 b2cfc4e2 2003-09-30 devnull .I Threadgetname
294 b2cfc4e2 2003-09-30 devnull returns the current thread's name;
295 b2cfc4e2 2003-09-30 devnull .I threadsetname
296 b2cfc4e2 2003-09-30 devnull sets it.
297 b2cfc4e2 2003-09-30 devnull The pointer returned by
298 b2cfc4e2 2003-09-30 devnull .I threadgetname
299 b2cfc4e2 2003-09-30 devnull is only valid until the next call to
300 b2cfc4e2 2003-09-30 devnull .IR threadsetname .
302 b2cfc4e2 2003-09-30 devnull .I Threaddata
303 b2cfc4e2 2003-09-30 devnull returns a pointer to a per-thread pointer
304 b2cfc4e2 2003-09-30 devnull that may be modified by threaded programs for
305 b2cfc4e2 2003-09-30 devnull per-thread storage.
306 b2cfc4e2 2003-09-30 devnull Similarly,
307 b2cfc4e2 2003-09-30 devnull .I procdata
308 b2cfc4e2 2003-09-30 devnull returns a pointer to a per-proc pointer.
310 b2cfc4e2 2003-09-30 devnull .I Procexecl
312 b2cfc4e2 2003-09-30 devnull .I procexec
313 b2cfc4e2 2003-09-30 devnull are threaded analogues of
316 b2cfc4e2 2003-09-30 devnull .I execl
318 b2cfc4e2 2003-09-30 devnull .IR exec (2));
319 b2cfc4e2 2003-09-30 devnull on success,
320 b2cfc4e2 2003-09-30 devnull they replace the calling thread (which must be the only thread in its proc)
321 b2cfc4e2 2003-09-30 devnull and invoke the external program, never returning.
322 b2cfc4e2 2003-09-30 devnull On error, they return \-1.
325 b2cfc4e2 2003-09-30 devnull is not null, the pid of the invoked program
326 b2cfc4e2 2003-09-30 devnull will be sent along
328 b2cfc4e2 2003-09-30 devnull once the program has been started, or \-1 will be sent if an
329 b2cfc4e2 2003-09-30 devnull error occurs.
330 b2cfc4e2 2003-09-30 devnull .I Procexec
332 b2cfc4e2 2003-09-30 devnull .I procexecl
333 b2cfc4e2 2003-09-30 devnull will not access their arguments after sending a result
335 b2cfc4e2 2003-09-30 devnull .IR cpid .
336 b2cfc4e2 2003-09-30 devnull Thus, programs that malloc the
338 b2cfc4e2 2003-09-30 devnull passed to
339 b2cfc4e2 2003-09-30 devnull .I procexec
340 b2cfc4e2 2003-09-30 devnull can safely free it once they have
341 b2cfc4e2 2003-09-30 devnull received the
343 b2cfc4e2 2003-09-30 devnull response.
344 b2cfc4e2 2003-09-30 devnull .I Threadwaitchan
345 b2cfc4e2 2003-09-30 devnull returns a channel of pointers to
346 b2cfc4e2 2003-09-30 devnull .B Waitmsg
347 b2cfc4e2 2003-09-30 devnull structures (see
348 b2cfc4e2 2003-09-30 devnull .IR wait (2)).
349 b2cfc4e2 2003-09-30 devnull When an exec'ed process exits, a pointer to a
350 b2cfc4e2 2003-09-30 devnull .B Waitmsg
351 b2cfc4e2 2003-09-30 devnull is sent to this channel.
353 b2cfc4e2 2003-09-30 devnull .B Waitmsg
354 b2cfc4e2 2003-09-30 devnull structures have been allocated with
355 b2cfc4e2 2003-09-30 devnull .IR malloc (2)
356 b2cfc4e2 2003-09-30 devnull and should be freed after use.
359 b2cfc4e2 2003-09-30 devnull .B Channel
360 b2cfc4e2 2003-09-30 devnull is a buffered or unbuffered queue for fixed-size messages.
361 b2cfc4e2 2003-09-30 devnull Procs and threads
363 b2cfc4e2 2003-09-30 devnull messages into the channel and
365 b2cfc4e2 2003-09-30 devnull messages from the channel. If the channel is unbuffered, a
367 b2cfc4e2 2003-09-30 devnull operation blocks until the corresponding
369 b2cfc4e2 2003-09-30 devnull operation occurs and
370 b2cfc4e2 2003-09-30 devnull .IR "vice versa" .
371 b2cfc4e2 2003-09-30 devnull .I Chaninit
372 b2cfc4e2 2003-09-30 devnull initializes a
373 b2cfc4e2 2003-09-30 devnull .B Channel
374 b2cfc4e2 2003-09-30 devnull for messages of size
375 b2cfc4e2 2003-09-30 devnull .I elsize
376 b2cfc4e2 2003-09-30 devnull and with a buffer holding
378 b2cfc4e2 2003-09-30 devnull messages.
381 b2cfc4e2 2003-09-30 devnull is zero, the channel is unbuffered.
382 b2cfc4e2 2003-09-30 devnull .IR Chancreate
383 b2cfc4e2 2003-09-30 devnull allocates a new channel and initializes it.
384 b2cfc4e2 2003-09-30 devnull .I Chanfree
385 b2cfc4e2 2003-09-30 devnull frees a channel that is no longer used.
386 b2cfc4e2 2003-09-30 devnull .I Chanfree
387 b2cfc4e2 2003-09-30 devnull can be called by either sender or receiver after the last item has been
388 b2cfc4e2 2003-09-30 devnull sent or received. Freeing the channel will be delayed if there is a thread
389 b2cfc4e2 2003-09-30 devnull blocked on it until that thread unblocks (but
390 b2cfc4e2 2003-09-30 devnull .I chanfree
391 b2cfc4e2 2003-09-30 devnull returns immediately).
394 b2cfc4e2 2003-09-30 devnull sends the element pointed at by
396 b2cfc4e2 2003-09-30 devnull to the channel
400 b2cfc4e2 2003-09-30 devnull is null, zeros are sent.
402 b2cfc4e2 2003-09-30 devnull receives an element from
404 b2cfc4e2 2003-09-30 devnull and stores it in
408 b2cfc4e2 2003-09-30 devnull is null,
409 b2cfc4e2 2003-09-30 devnull the received value is discarded.
413 b2cfc4e2 2003-09-30 devnull return 1 on success, \-1 if interrupted.
414 b2cfc4e2 2003-09-30 devnull .I Nbsend
416 b2cfc4e2 2003-09-30 devnull .I nbrecv
417 b2cfc4e2 2003-09-30 devnull behave similarly, but return 0 rather than blocking.
419 b2cfc4e2 2003-09-30 devnull .IR Sendp ,
420 b2cfc4e2 2003-09-30 devnull .IR nbsendp ,
421 b2cfc4e2 2003-09-30 devnull .IR sendul ,
423 b2cfc4e2 2003-09-30 devnull .I nbsendul
424 b2cfc4e2 2003-09-30 devnull send a pointer or an unsigned long; the channel must
425 b2cfc4e2 2003-09-30 devnull have been initialized with the appropriate
426 b2cfc4e2 2003-09-30 devnull .IR elsize .
427 b2cfc4e2 2003-09-30 devnull .IR Recvp ,
428 b2cfc4e2 2003-09-30 devnull .IR nbrecvp ,
429 b2cfc4e2 2003-09-30 devnull .IR recvul ,
431 b2cfc4e2 2003-09-30 devnull .I nbrecvul
432 b2cfc4e2 2003-09-30 devnull receive a pointer or an unsigned long;
433 b2cfc4e2 2003-09-30 devnull they return zero when a zero is received,
434 b2cfc4e2 2003-09-30 devnull when interrupted, or
436 b2cfc4e2 2003-09-30 devnull .I nbrecvp
438 b2cfc4e2 2003-09-30 devnull .IR nbrecvul )
439 b2cfc4e2 2003-09-30 devnull when the operation would have blocked.
440 b2cfc4e2 2003-09-30 devnull To distinguish between these three cases,
444 b2cfc4e2 2003-09-30 devnull .IR nbrecv .
447 b2cfc4e2 2003-09-30 devnull can be used to recv from or send to one of a number of channels,
448 b2cfc4e2 2003-09-30 devnull as directed by an array of
450 b2cfc4e2 2003-09-30 devnull structures,
451 b2cfc4e2 2003-09-30 devnull each of which describes a potential send or receive operation.
454 b2cfc4e2 2003-09-30 devnull structure,
456 b2cfc4e2 2003-09-30 devnull is the channel;
458 b2cfc4e2 2003-09-30 devnull the value pointer (which may be null); and
460 b2cfc4e2 2003-09-30 devnull the operation:
461 b2cfc4e2 2003-09-30 devnull .B CHANSND
462 b2cfc4e2 2003-09-30 devnull for a send operation,
463 b2cfc4e2 2003-09-30 devnull .B CHANRECV
464 b2cfc4e2 2003-09-30 devnull for a recv operation;
465 b2cfc4e2 2003-09-30 devnull .B CHANNOP
466 b2cfc4e2 2003-09-30 devnull for no operation
470 b2cfc4e2 2003-09-30 devnull is called with a varying set of operations).
471 b2cfc4e2 2003-09-30 devnull The array of
473 b2cfc4e2 2003-09-30 devnull structures is terminated by an entry with
475 b2cfc4e2 2003-09-30 devnull .B CHANEND
477 b2cfc4e2 2003-09-30 devnull .BR CHANNOBLK .
478 b2cfc4e2 2003-09-30 devnull If at least one
480 b2cfc4e2 2003-09-30 devnull structure can proceed, one of them is
481 b2cfc4e2 2003-09-30 devnull chosen at random to be executed.
483 b2cfc4e2 2003-09-30 devnull returns the index of the chosen structure.
484 b2cfc4e2 2003-09-30 devnull If no operations can proceed and the list is terminated with
485 b2cfc4e2 2003-09-30 devnull .BR CHANNOBLK ,
487 b2cfc4e2 2003-09-30 devnull returns the index of the terminating
488 b2cfc4e2 2003-09-30 devnull .B CHANNOBLK
489 b2cfc4e2 2003-09-30 devnull structure.
490 b2cfc4e2 2003-09-30 devnull Otherwise,
492 b2cfc4e2 2003-09-30 devnull blocks until one of the operations can proceed,
493 b2cfc4e2 2003-09-30 devnull eventually returning the index of the structure executes.
495 b2cfc4e2 2003-09-30 devnull returns \-1 when interrupted.
499 b2cfc4e2 2003-09-30 devnull .B entryno
500 b2cfc4e2 2003-09-30 devnull fields in the
502 b2cfc4e2 2003-09-30 devnull structure are used internally by
504 b2cfc4e2 2003-09-30 devnull and need not be initialized.
505 b2cfc4e2 2003-09-30 devnull They are not used between
509 b2cfc4e2 2003-09-30 devnull .I Chanprint
510 b2cfc4e2 2003-09-30 devnull formats its arguments in the manner of
511 b2cfc4e2 2003-09-30 devnull .IR print (2)
512 b2cfc4e2 2003-09-30 devnull and sends the result to the channel
514 b2cfc4e2 2003-09-30 devnull The string delivered by
515 b2cfc4e2 2003-09-30 devnull .I chanprint
516 b2cfc4e2 2003-09-30 devnull is allocated with
517 b2cfc4e2 2003-09-30 devnull .IR malloc (2)
518 b2cfc4e2 2003-09-30 devnull and should be freed upon receipt.
520 b2cfc4e2 2003-09-30 devnull Thread library functions do not return on failure;
521 b2cfc4e2 2003-09-30 devnull if errors occur, the entire program is aborted.
523 b2cfc4e2 2003-09-30 devnull Threaded programs should use
524 b2cfc4e2 2003-09-30 devnull .I threadnotify
525 b2cfc4e2 2003-09-30 devnull in place of
526 b2cfc4e2 2003-09-30 devnull .I atnotify
528 b2cfc4e2 2003-09-30 devnull .IR notify (2)).
530 b2cfc4e2 2003-09-30 devnull It is safe to use
531 b2cfc4e2 2003-09-30 devnull .B sysfatal
533 b2cfc4e2 2003-09-30 devnull .IR perror (2))
534 b2cfc4e2 2003-09-30 devnull in threaded programs.
535 b2cfc4e2 2003-09-30 devnull .I Sysfatal
536 b2cfc4e2 2003-09-30 devnull will print the error string and call
537 b2cfc4e2 2003-09-30 devnull .IR threadexitsall .
539 b2cfc4e2 2003-09-30 devnull It is safe to use
540 b2cfc4e2 2003-09-30 devnull .IR rfork
542 b2cfc4e2 2003-09-30 devnull .IR fork (2))
543 b2cfc4e2 2003-09-30 devnull to manage the namespace, file descriptors, note group, and environment of a
544 b2cfc4e2 2003-09-30 devnull single process.
545 b2cfc4e2 2003-09-30 devnull That is, it is safe to call
546 b2cfc4e2 2003-09-30 devnull .I rfork
547 b2cfc4e2 2003-09-30 devnull with the flags
548 b2cfc4e2 2003-09-30 devnull .BR RFNAMEG ,
549 b2cfc4e2 2003-09-30 devnull .BR RFFDG ,
550 b2cfc4e2 2003-09-30 devnull .BR RFCFDG ,
551 b2cfc4e2 2003-09-30 devnull .BR RFNOTEG ,
552 b2cfc4e2 2003-09-30 devnull .BR RFENVG ,
554 b2cfc4e2 2003-09-30 devnull .BR RFCENVG.
555 b2cfc4e2 2003-09-30 devnull (To create new processes, use
556 b2cfc4e2 2003-09-30 devnull .I proccreate
558 b2cfc4e2 2003-09-30 devnull .IR procrfork .)
559 b2cfc4e2 2003-09-30 devnull As mentioned above,
560 b2cfc4e2 2003-09-30 devnull the thread library depends on all procs being in the
561 b2cfc4e2 2003-09-30 devnull same rendezvous group; do not change the rendezvous
562 b2cfc4e2 2003-09-30 devnull group with
563 b2cfc4e2 2003-09-30 devnull .IR rfork .
564 b2cfc4e2 2003-09-30 devnull .SH FILES
565 b2cfc4e2 2003-09-30 devnull .B /sys/lib/acid/thread
566 b2cfc4e2 2003-09-30 devnull contains useful
567 b2cfc4e2 2003-09-30 devnull .IR acid (1)
568 b2cfc4e2 2003-09-30 devnull functions for debugging threaded programs.
570 b2cfc4e2 2003-09-30 devnull .B /sys/src/libthread/example.c
571 b2cfc4e2 2003-09-30 devnull contains a full example program.
572 b2cfc4e2 2003-09-30 devnull .SH SOURCE
573 b2cfc4e2 2003-09-30 devnull .B /sys/src/libthread
574 b2cfc4e2 2003-09-30 devnull .SH SEE ALSO
575 b2cfc4e2 2003-09-30 devnull .IR intro (2),
576 b2cfc4e2 2003-09-30 devnull .IR ioproc (2)
