47 yield \- thread and proc management
51 .ta 4n +4n +4n +4n +4n +4n +4n
62 .ta \w' 'u +\w'Channel 'u
63 typedef struct Alt Alt;
80 .ta \w'\fLChannel* 'u +4n +4n +4n +4n
81 void threadmain(int argc, char *argv[])
83 int proccreate(void (*fn)(void*), void *arg, uint stacksize)
84 int threadcreate(void (*fn)(void*), void *arg, uint stacksize)
85 void threadexits(char *status)
86 void threadexitsall(char *status)
93 int threadsetgrp(int group)
97 int threadintgrp(int group)
98 int threadkill(int id)
99 int threadkillgrp(int group)
101 void threadsetname(char *name)
102 char* threadgetname(void)
104 void** threaddata(void)
105 void** procdata(void)
107 Channel* chancreate(int elsize, int nel)
108 void chanfree(Channel *c)
111 int recv(Channel *c, void *v)
112 void* recvp(Channel *c)
113 ulong recvul(Channel *c)
114 int nbrecv(Channel *c, void *v)
115 void* nbrecvp(Channel *c)
116 ulong nbrecvul(Channel *c)
117 int send(Channel *c, void *v)
118 int sendp(Channel *c, void *v)
119 int sendul(Channel *c, ulong v)
120 int nbsend(Channel *c, void *v)
121 int nbsendp(Channel *c, void *v)
122 int nbsendul(Channel *c, ulong v)
123 int chanprint(Channel *c, char *fmt, ...)
125 int threadspawnl(int fd[3], char *file, ...)
126 int threadspawn(int fd[3], char *file, char *args[])
127 int threadexecl(Channel *cpid, int fd[3], char *file, ...)
128 int threadexec(Channel *cpid, int fd[3], char *file, char *args[])
129 Channel* threadwaitchan(void)
131 int threadnotify(int (*f)(void*, char*), int in)
135 The thread library provides parallel programming support similar to that
141 occupy a shared address space,
142 communicating and synchronizing through
144 and shared variables.
148 is a Plan 9 process that contains one or more cooperatively scheduled
150 Programs using threads must replace
154 The thread library provides a
156 function that sets up a proc with a single thread executing
160 (default eight kilobytes).
163 declare a global variable
164 initialized to the desired value
172 creates a new thread in the calling proc, returning a unique integer
173 identifying the thread; the thread
178 Thread stacks are allocated in shared memory, making it valid to pass
179 pointers to stack variables between threads and procs.
181 creates a new proc, and inside that proc creates
185 returning the id of the created thread.
187 .\" creates the new proc by calling
192 .\" .BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR.
193 .\" (The thread library depends on all its procs
194 .\" running in the same rendezvous group.
205 Be aware that the calling thread may continue
207 the newly created proc and thread
211 should not point to data on the stack of a function that could
212 return before the new process is scheduled.
215 terminates the calling thread.
216 If the thread is the last in its proc,
218 also terminates the proc, using
222 terminates all procs in the program,
227 When the last thread in
229 proc exits, the program will appear to its parent to have exited.
230 The remaining procs will still run together, but as a background program.
232 The threads in a proc are coroutines, scheduled nonpreemptively
233 in a round-robin fashion.
234 A thread must explicitly relinquish control of the processor
235 before another thread in the same proc is run.
236 Calls that do this are
247 (and the calls related to
251 their descriptions further on).
252 Procs are scheduled by the operating system.
253 Therefore, threads in different procs can preempt one another
254 in arbitrary ways and should synchronize their
259 or channel communication.
262 block the entire proc;
263 all threads in a proc block until the system call finishes.
266 disables scheduling inside a proc, `pinning' the current
267 thread as the only runnable one in the current proc.
269 reenables scheduling, allowing other procs to run once the current
270 thread relinquishes the processor.
274 can lead to deadlock.
275 Used carefully, they can make library routines that use
277 appear atomic relative to the current proc, like a system call.
279 As mentioned above, each thread has a unique integer thread id.
280 Thread ids are not reused; they are unique across the life of the program.
282 returns the id for the current thread.
283 Each thread also has a thread group id.
284 The initial thread has a group id of zero.
285 Each new thread inherits the group id of
286 the thread that created it.
288 returns the group id for the current thread;
292 returns the pid of the Plan 9 process containing
293 the thread identified by
296 if no such thread is found.
299 interrupts a thread that is blocked in a channel operation
302 interrupts all threads with the given group id.
304 marks a thread to die when it next relinquishes the processor
305 (via one of the calls listed above).
306 If the thread is blocked in a channel operation or system call,
307 it is also interrupted.
309 kills all threads with the given group id.
314 will not terminate a thread that never relinquishes
317 Primarily for debugging,
318 threads can have string names associated with them.
320 returns the current thread's name;
323 The pointer returned by
325 is only valid until the next call to
329 threads have a string state associated with them.
331 sets the state string.
334 since the thread scheduler resets the state to
336 every time it runs the thread,
337 it is only useful for debuggers to inspect the state.
340 returns a pointer to a per-thread pointer
341 that may be modified by threaded programs for
345 returns a pointer to a per-proc pointer.
350 are threaded analogues of
357 they replace the calling thread
358 and invoke the external program, never returning.
359 (Unlike on Plan 9, the calling thread need not be the only thread in its proc\(emthe other
360 threads will continue executing.)
361 On error, they return \-1.
364 is not null, the pid of the invoked program
369 once the program has been started, or \-1 will be sent if an
374 will not access their arguments after sending a result
377 Thus, programs that malloc the
381 can safely free it once they have
392 the three file descriptors in
394 onto standard input, output, and error for the external program
395 and then close them in the calling thread.
396 Beware of code that sets
404 to use the current standard files. The correct code is
419 but do not replace the current thread.
420 They return the pid of the invoked program on success, or
424 returns a channel of pointers to
428 When an exec'ed process exits, a pointer to a
430 is sent to this channel.
433 structures have been allocated with
435 and should be freed after use.
439 is a buffered or unbuffered queue for fixed-size messages.
442 messages into the channel and
444 messages from the channel. If the channel is unbuffered, a
446 operation blocks until the corresponding
451 allocates a new channel
454 and with a buffer holding
459 is zero, the channel is unbuffered.
461 frees a channel that is no longer used.
463 can be called by either sender or receiver after the last item has been
464 sent or received. Freeing the channel will be delayed if there is a thread
465 blocked on it until that thread unblocks (but
467 returns immediately).
473 structure is a description intended for use in debugging.
478 sends the element pointed at by
484 is null, zeros are sent.
486 receives an element from
493 the received value is discarded.
497 return 1 on success, \-1 if interrupted.
501 behave similarly, but return 0 rather than blocking.
508 send a pointer or an unsigned long; the channel must
509 have been initialized with the appropriate
516 receive a pointer or an unsigned long;
517 they return zero when a zero is received,
523 when the operation would have blocked.
524 To distinguish between these three cases,
531 can be used to recv from or send to one of a number of channels,
532 as directed by an array of
535 each of which describes a potential send or receive operation.
542 the value pointer (which may be null); and
546 for a send operation,
548 for a recv operation;
554 is called with a varying set of operations).
557 structures is terminated by an entry with
564 structure can proceed, one of them is
565 chosen at random to be executed.
567 returns the index of the chosen structure.
568 If no operations can proceed and the list is terminated with
571 returns the index of the terminating
576 blocks until one of the operations can proceed,
577 eventually returning the index of the structure executes.
579 returns \-1 when interrupted.
586 structure are used internally by
588 and need not be initialized.
589 They are not used between
594 formats its arguments in the manner of
596 and sends the result to the channel
598 The string delivered by
602 and should be freed upon receipt.
604 Thread library functions do not return on failure;
605 if errors occur, the entire program is aborted.
607 Threaded programs should use
616 in threaded programs.
618 will print the error string and call
621 It is not safe to call
623 in a threaded program, except to call
625 from the main proc before any other procs have been created.
626 To create new processes, use
629 .\" It is safe to use
633 .\" to manage the namespace, file descriptors, note group, and environment of a
635 .\" That is, it is safe to call
645 .\" (To create new processes, use
649 .\" As mentioned above,
650 .\" the thread library depends on all procs being in the
651 .\" same rendezvous group; do not change the rendezvous
658 functions for debugging threaded programs.
660 .B \*9/src/libthread/test
661 contains some example programs.
668 To avoid name conflicts,
683 are defined as macros that expand to
688 is defined as a macro that expands to
696 threadkillgrp and threadpid are unimplemented.
698 The implementation of
702 There appears to be a race in the Linux NPTL
707 rather than coordinating a simultaneous
