43 yield \- thread and proc management
47 .ta 4n +4n +4n +4n +4n +4n +4n
58 .ta \w' 'u +\w'Channel 'u
59 typedef struct Alt Alt;
75 .ta \w'\fLChannel* 'u +4n +4n +4n +4n
76 void threadmain(int argc, char *argv[])
78 int proccreate(void (*fn)(void*), void *arg, uint stacksize)
79 int procrfork(void (*fn)(void*), void *arg, uint stacksize,
81 int threadcreate(void (*fn)(void*), void *arg, uint stacksize)
82 void threadexits(char *status)
83 void threadexitsall(char *status)
88 int threadsetgrp(int group)
92 int threadintgrp(int group)
93 int threadkill(int id)
94 int threadkillgrp(int group)
96 void threadsetname(char *name)
97 char* threadgetname(void)
99 void** threaddata(void)
100 void** procdata(void)
102 int chaninit(Channel *c, int elsize, int nel)
103 Channel* chancreate(int elsize, int nel)
104 void chanfree(Channel *c)
107 int recv(Channel *c, void *v)
108 void* recvp(Channel *c)
109 ulong recvul(Channel *c)
110 int nbrecv(Channel *c, void *v)
111 void* nbrecvp(Channel *c)
112 ulong nbrecvul(Channel *c)
113 int send(Channel *c, void *v)
114 int sendp(Channel *c, void *v)
115 int sendul(Channel *c, ulong v)
116 int nbsend(Channel *c, void *v)
117 int nbsendp(Channel *c, void *v)
118 int nbsendul(Channel *c, ulong v)
119 int chanprint(Channel *c, char *fmt, ...)
121 int procexecl(Channel *cpid, char *file, ...)
122 int procexec(Channel *cpid, char *file, char *args[])
123 Channel* threadwaitchan(void)
125 int threadnotify(int (*f)(void*, char*), int in)
129 The thread library provides parallel programming support similar to that
135 occupy a shared address space,
136 communicating and synchronizing through
138 and shared variables.
142 is a Plan 9 process that contains one or more cooperatively scheduled
144 Programs using threads must replace
148 The thread library provides a
150 function that sets up a proc with a single thread executing
154 (default eight kilobytes).
157 declare a global variable
158 initialized to the desired value
166 creates a new thread in the calling proc, returning a unique integer
167 identifying the thread; the thread
172 Thread stacks are allocated in shared memory, making it valid to pass
173 pointers to stack variables between threads and procs.
175 creates a new proc, and inside that proc creates
179 returning the id of the created thread.
181 creates the new proc by calling
186 .BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR.
187 (The thread library depends on all its procs
188 running in the same rendezvous group.
199 Be aware that the calling thread may continue
201 the newly created proc and thread
205 should not point to data on the stack of a function that could
206 return before the new process is scheduled.
209 terminates the calling thread.
210 If the thread is the last in its proc,
212 also terminates the proc, using
216 terminates all procs in the program,
221 The threads in a proc are coroutines, scheduled nonpreemptively
222 in a round-robin fashion.
223 A thread must explicitly relinquish control of the processor
224 before another thread in the same proc is run.
225 Calls that do this are
235 (and the calls related to
239 their descriptions further on).
240 Procs are scheduled by the operating system.
241 Therefore, threads in different procs can preempt one another
242 in arbitrary ways and should synchronize their
247 or channel communication.
250 block the entire proc;
251 all threads in a proc block until the system call finishes.
253 As mentioned above, each thread has a unique integer thread id.
254 Thread ids are not reused; they are unique across the life of the program.
256 returns the id for the current thread.
257 Each thread also has a thread group id.
258 The initial thread has a group id of zero.
259 Each new thread inherits the group id of
260 the thread that created it.
262 returns the group id for the current thread;
266 returns the pid of the Plan 9 process containing
267 the thread identified by
270 if no such thread is found.
273 interrupts a thread that is blocked in a channel operation
276 interrupts all threads with the given group id.
278 marks a thread to die when it next relinquishes the processor
279 (via one of the calls listed above).
280 If the thread is blocked in a channel operation or system call,
281 it is also interrupted.
283 kills all threads with the given group id.
288 will not terminate a thread that never relinquishes
291 Primarily for debugging,
292 threads can have string names associated with them.
294 returns the current thread's name;
297 The pointer returned by
299 is only valid until the next call to
303 returns a pointer to a per-thread pointer
304 that may be modified by threaded programs for
308 returns a pointer to a per-proc pointer.
313 are threaded analogues of
320 they replace the calling thread (which must be the only thread in its proc)
321 and invoke the external program, never returning.
322 On error, they return \-1.
325 is not null, the pid of the invoked program
328 once the program has been started, or \-1 will be sent if an
333 will not access their arguments after sending a result
336 Thus, programs that malloc the
340 can safely free it once they have
345 returns a channel of pointers to
349 When an exec'ed process exits, a pointer to a
351 is sent to this channel.
354 structures have been allocated with
356 and should be freed after use.
360 is a buffered or unbuffered queue for fixed-size messages.
363 messages into the channel and
365 messages from the channel. If the channel is unbuffered, a
367 operation blocks until the corresponding
376 and with a buffer holding
381 is zero, the channel is unbuffered.
383 allocates a new channel and initializes it.
385 frees a channel that is no longer used.
387 can be called by either sender or receiver after the last item has been
388 sent or received. Freeing the channel will be delayed if there is a thread
389 blocked on it until that thread unblocks (but
391 returns immediately).
394 sends the element pointed at by
400 is null, zeros are sent.
402 receives an element from
409 the received value is discarded.
413 return 1 on success, \-1 if interrupted.
417 behave similarly, but return 0 rather than blocking.
424 send a pointer or an unsigned long; the channel must
425 have been initialized with the appropriate
432 receive a pointer or an unsigned long;
433 they return zero when a zero is received,
439 when the operation would have blocked.
440 To distinguish between these three cases,
447 can be used to recv from or send to one of a number of channels,
448 as directed by an array of
451 each of which describes a potential send or receive operation.
458 the value pointer (which may be null); and
462 for a send operation,
464 for a recv operation;
470 is called with a varying set of operations).
473 structures is terminated by an entry with
480 structure can proceed, one of them is
481 chosen at random to be executed.
483 returns the index of the chosen structure.
484 If no operations can proceed and the list is terminated with
487 returns the index of the terminating
492 blocks until one of the operations can proceed,
493 eventually returning the index of the structure executes.
495 returns \-1 when interrupted.
502 structure are used internally by
504 and need not be initialized.
505 They are not used between
510 formats its arguments in the manner of
512 and sends the result to the channel
514 The string delivered by
518 and should be freed upon receipt.
520 Thread library functions do not return on failure;
521 if errors occur, the entire program is aborted.
523 Threaded programs should use
534 in threaded programs.
536 will print the error string and call
543 to manage the namespace, file descriptors, note group, and environment of a
545 That is, it is safe to call
555 (To create new processes, use
560 the thread library depends on all procs being in the
561 same rendezvous group; do not change the rendezvous
565 .B /sys/lib/acid/thread
568 functions for debugging threaded programs.
570 .B /sys/src/libthread/example.c
571 contains a full example program.
573 .B /sys/src/libthread
