43 yield \- thread and proc management
55 .ta 4n +4n +4n +4n +4n +4n +4n
66 .ta \w' 'u +\w'Channel 'u
67 typedef struct Alt Alt;
83 .ta \w'\fLChannel* 'u +4n +4n +4n +4n
84 void threadmain(int argc, char *argv[])
86 int proccreate(void (*fn)(void*), void *arg, uint stacksize)
87 int procrfork(void (*fn)(void*), void *arg, uint stacksize,
89 int threadcreate(void (*fn)(void*), void *arg, uint stacksize)
90 void threadexits(char *status)
91 void threadexitsall(char *status)
96 int threadsetgrp(int group)
100 int threadintgrp(int group)
101 int threadkill(int id)
102 int threadkillgrp(int group)
104 void threadsetname(char *name)
105 char* threadgetname(void)
107 void** threaddata(void)
108 void** procdata(void)
110 int chaninit(Channel *c, int elsize, int nel)
111 Channel* chancreate(int elsize, int nel)
112 void chanfree(Channel *c)
115 int recv(Channel *c, void *v)
116 void* recvp(Channel *c)
117 ulong recvul(Channel *c)
118 int nbrecv(Channel *c, void *v)
119 void* nbrecvp(Channel *c)
120 ulong nbrecvul(Channel *c)
121 int send(Channel *c, void *v)
122 int sendp(Channel *c, void *v)
123 int sendul(Channel *c, ulong v)
124 int nbsend(Channel *c, void *v)
125 int nbsendp(Channel *c, void *v)
126 int nbsendul(Channel *c, ulong v)
127 int chanprint(Channel *c, char *fmt, ...)
129 int procexecl(Channel *cpid, char *file, ...)
130 int procexec(Channel *cpid, char *file, char *args[])
131 Channel* threadwaitchan(void)
133 int threadnotify(int (*f)(void*, char*), int in)
137 The thread library provides parallel programming support similar to that
143 occupy a shared address space,
144 communicating and synchronizing through
146 and shared variables.
150 is a Plan 9 process that contains one or more cooperatively scheduled
152 Programs using threads must replace
156 The thread library provides a
158 function that sets up a proc with a single thread executing
162 (default eight kilobytes).
165 declare a global variable
166 initialized to the desired value
174 creates a new thread in the calling proc, returning a unique integer
175 identifying the thread; the thread
180 Thread stacks are allocated in shared memory, making it valid to pass
181 pointers to stack variables between threads and procs.
183 creates a new proc, and inside that proc creates
187 returning the id of the created thread.
189 creates the new proc by calling
194 .BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR.
195 (The thread library depends on all its procs
196 running in the same rendezvous group.
207 Be aware that the calling thread may continue
209 the newly created proc and thread
213 should not point to data on the stack of a function that could
214 return before the new process is scheduled.
217 terminates the calling thread.
218 If the thread is the last in its proc,
220 also terminates the proc, using
224 terminates all procs in the program,
229 The threads in a proc are coroutines, scheduled nonpreemptively
230 in a round-robin fashion.
231 A thread must explicitly relinquish control of the processor
232 before another thread in the same proc is run.
233 Calls that do this are
243 (and the calls related to
247 their descriptions further on).
248 Procs are scheduled by the operating system.
249 Therefore, threads in different procs can preempt one another
250 in arbitrary ways and should synchronize their
255 or channel communication.
258 block the entire proc;
259 all threads in a proc block until the system call finishes.
261 As mentioned above, each thread has a unique integer thread id.
262 Thread ids are not reused; they are unique across the life of the program.
264 returns the id for the current thread.
265 Each thread also has a thread group id.
266 The initial thread has a group id of zero.
267 Each new thread inherits the group id of
268 the thread that created it.
270 returns the group id for the current thread;
274 returns the pid of the Plan 9 process containing
275 the thread identified by
278 if no such thread is found.
281 interrupts a thread that is blocked in a channel operation
284 interrupts all threads with the given group id.
286 marks a thread to die when it next relinquishes the processor
287 (via one of the calls listed above).
288 If the thread is blocked in a channel operation or system call,
289 it is also interrupted.
291 kills all threads with the given group id.
296 will not terminate a thread that never relinquishes
299 Primarily for debugging,
300 threads can have string names associated with them.
302 returns the current thread's name;
305 The pointer returned by
307 is only valid until the next call to
311 returns a pointer to a per-thread pointer
312 that may be modified by threaded programs for
316 returns a pointer to a per-proc pointer.
321 are threaded analogues of
328 they replace the calling thread (which must be the only thread in its proc)
329 and invoke the external program, never returning.
330 On error, they return \-1.
333 is not null, the pid of the invoked program
336 once the program has been started, or \-1 will be sent if an
341 will not access their arguments after sending a result
344 Thus, programs that malloc the
348 can safely free it once they have
353 returns a channel of pointers to
357 When an exec'ed process exits, a pointer to a
359 is sent to this channel.
362 structures have been allocated with
364 and should be freed after use.
368 is a buffered or unbuffered queue for fixed-size messages.
371 messages into the channel and
373 messages from the channel. If the channel is unbuffered, a
375 operation blocks until the corresponding
384 and with a buffer holding
389 is zero, the channel is unbuffered.
391 allocates a new channel and initializes it.
393 frees a channel that is no longer used.
395 can be called by either sender or receiver after the last item has been
396 sent or received. Freeing the channel will be delayed if there is a thread
397 blocked on it until that thread unblocks (but
399 returns immediately).
402 sends the element pointed at by
408 is null, zeros are sent.
410 receives an element from
417 the received value is discarded.
421 return 1 on success, \-1 if interrupted.
425 behave similarly, but return 0 rather than blocking.
432 send a pointer or an unsigned long; the channel must
433 have been initialized with the appropriate
440 receive a pointer or an unsigned long;
441 they return zero when a zero is received,
447 when the operation would have blocked.
448 To distinguish between these three cases,
455 can be used to recv from or send to one of a number of channels,
456 as directed by an array of
459 each of which describes a potential send or receive operation.
466 the value pointer (which may be null); and
470 for a send operation,
472 for a recv operation;
478 is called with a varying set of operations).
481 structures is terminated by an entry with
488 structure can proceed, one of them is
489 chosen at random to be executed.
491 returns the index of the chosen structure.
492 If no operations can proceed and the list is terminated with
495 returns the index of the terminating
500 blocks until one of the operations can proceed,
501 eventually returning the index of the structure executes.
503 returns \-1 when interrupted.
510 structure are used internally by
512 and need not be initialized.
513 They are not used between
518 formats its arguments in the manner of
520 and sends the result to the channel
522 The string delivered by
526 and should be freed upon receipt.
528 Thread library functions do not return on failure;
529 if errors occur, the entire program is aborted.
531 Threaded programs should use
542 in threaded programs.
544 will print the error string and call
551 to manage the namespace, file descriptors, note group, and environment of a
553 That is, it is safe to call
563 (To create new processes, use
568 the thread library depends on all procs being in the
569 same rendezvous group; do not change the rendezvous
573 .B /usr/local/plan9/acid/thread
576 functions for debugging threaded programs.
578 .B /usr/local/plan9/src/libthread/example.c
579 contains a full example program.
581 .B /usr/local/plan9/src/libthread
