48 yield \- thread and proc management
52 .ta 4n +4n +4n +4n +4n +4n +4n
63 .ta \w' 'u +\w'Channel 'u
64 typedef struct Alt Alt;
81 .ta \w'\fLChannel* 'u +4n +4n +4n +4n
82 void threadmain(int argc, char *argv[])
84 int proccreate(void (*fn)(void*), void *arg, uint stacksize)
85 int threadcreate(void (*fn)(void*), void *arg, uint stacksize)
86 void threadexits(char *status)
87 void threadexitsall(char *status)
94 int threadsetgrp(int group)
98 int threadintgrp(int group)
99 int threadkill(int id)
100 int threadkillgrp(int group)
102 void threadsetname(char *name)
103 char* threadgetname(void)
105 void** threaddata(void)
106 void** procdata(void)
108 Channel* chancreate(int elsize, int nel)
109 void chanfree(Channel *c)
112 int recv(Channel *c, void *v)
113 void* recvp(Channel *c)
114 ulong recvul(Channel *c)
115 int nbrecv(Channel *c, void *v)
116 void* nbrecvp(Channel *c)
117 ulong nbrecvul(Channel *c)
118 int send(Channel *c, void *v)
119 int sendp(Channel *c, void *v)
120 int sendul(Channel *c, ulong v)
121 int nbsend(Channel *c, void *v)
122 int nbsendp(Channel *c, void *v)
123 int nbsendul(Channel *c, ulong v)
124 int chanprint(Channel *c, char *fmt, ...)
126 int threadspawnl(int fd[3], char *file, ...)
127 int threadspawn(int fd[3], char *file, char *args[])
128 int threadspawnd(int fd[3], char *file, char *args[], char *dir)
129 int threadexecl(Channel *cpid, int fd[3], char *file, ...)
130 int threadexec(Channel *cpid, int fd[3], 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 When the last thread in
231 proc exits, the program will appear to its parent to have exited.
232 The remaining procs will still run together, but as a background program.
234 The threads in a proc are coroutines, scheduled nonpreemptively
235 in a round-robin fashion.
236 A thread must explicitly relinquish control of the processor
237 before another thread in the same proc is run.
238 Calls that do this are
251 (and the calls related to
255 their descriptions further on).
256 Procs are scheduled by the operating system.
257 Therefore, threads in different procs can preempt one another
258 in arbitrary ways and should synchronize their
263 or channel communication.
266 block the entire proc;
267 all threads in a proc block until the system call finishes.
270 disables scheduling inside a proc, `pinning' the current
271 thread as the only runnable one in the current proc.
273 reenables scheduling, allowing other procs to run once the current
274 thread relinquishes the processor.
278 can lead to deadlock.
279 Used carefully, they can make library routines that use
281 appear atomic relative to the current proc, like a system call.
283 As mentioned above, each thread has a unique integer thread id.
284 Thread ids are not reused; they are unique across the life of the program.
286 returns the id for the current thread.
287 Each thread also has a thread group id.
288 The initial thread has a group id of zero.
289 Each new thread inherits the group id of
290 the thread that created it.
292 returns the group id for the current thread;
296 returns the pid of the Plan 9 process containing
297 the thread identified by
300 if no such thread is found.
303 interrupts a thread that is blocked in a channel operation
306 interrupts all threads with the given group id.
308 marks a thread to die when it next relinquishes the processor
309 (via one of the calls listed above).
310 If the thread is blocked in a channel operation or system call,
311 it is also interrupted.
313 kills all threads with the given group id.
318 will not terminate a thread that never relinquishes
321 Primarily for debugging,
322 threads can have string names associated with them.
324 returns the current thread's name;
327 The pointer returned by
329 is only valid until the next call to
333 threads have a string state associated with them.
335 sets the state string.
338 since the thread scheduler resets the state to
340 every time it runs the thread,
341 it is only useful for debuggers to inspect the state.
344 returns a pointer to a per-thread pointer
345 that may be modified by threaded programs for
349 returns a pointer to a per-proc pointer.
354 are threaded analogues of
361 they replace the calling thread
362 and invoke the external program, never returning.
363 (Unlike on Plan 9, the calling thread need not be the only thread in its proc\(emthe other
364 threads will continue executing.)
365 On error, they return \-1.
368 is not null, the pid of the invoked program
373 once the program has been started, or \-1 will be sent if an
378 will not access their arguments after sending a result
381 Thus, programs that malloc the
385 can safely free it once they have
396 the three file descriptors in
398 onto standard input, output, and error for the external program
399 and then close them in the calling thread.
400 Beware of code that sets
408 to use the current standard files. The correct code is
423 but do not replace the current thread.
424 They return the pid of the invoked program on success, or
429 but takes as its final argument the directory in which to run the invoked program.
430 The child will attempt to change into that directory before running the program,
431 but it is only best effort: failure to change into the directory does not
432 stop the running of the program.
435 returns a channel of pointers to
439 When an exec'ed process exits, a pointer to a
441 is sent to this channel.
444 structures have been allocated with
446 and should be freed after use.
450 is a buffered or unbuffered queue for fixed-size messages.
453 messages into the channel and
455 messages from the channel. If the channel is unbuffered, a
457 operation blocks until the corresponding
462 allocates a new channel
465 and with a buffer holding
470 is zero, the channel is unbuffered.
472 frees a channel that is no longer used.
474 can be called by either sender or receiver after the last item has been
475 sent or received. Freeing the channel will be delayed if there is a thread
476 blocked on it until that thread unblocks (but
478 returns immediately).
484 structure is a description intended for use in debugging.
489 sends the element pointed at by
495 is null, zeros are sent.
497 receives an element from
504 the received value is discarded.
508 return 1 on success, \-1 if interrupted.
512 behave similarly, but return 0 rather than blocking.
519 send a pointer or an unsigned long; the channel must
520 have been initialized with the appropriate
527 receive a pointer or an unsigned long;
528 they return zero when a zero is received,
534 when the operation would have blocked.
535 To distinguish between these three cases,
542 can be used to recv from or send to one of a number of channels,
543 as directed by an array of
546 each of which describes a potential send or receive operation.
553 the value pointer (which may be null); and
557 for a send operation,
559 for a recv operation;
565 is called with a varying set of operations).
568 structures is terminated by an entry with
575 structure can proceed, one of them is
576 chosen at random to be executed.
578 returns the index of the chosen structure.
579 If no operations can proceed and the list is terminated with
582 returns the index of the terminating
587 blocks until one of the operations can proceed,
588 eventually returning the index of the structure executes.
590 returns \-1 when interrupted.
597 structure are used internally by
599 and need not be initialized.
600 They are not used between
605 formats its arguments in the manner of
607 and sends the result to the channel
609 The string delivered by
613 and should be freed upon receipt.
615 Thread library functions do not return on failure;
616 if errors occur, the entire program is aborted.
618 Threaded programs should use
627 in threaded programs.
629 will print the error string and call
632 It is not safe to call
634 in a threaded program, except to call
636 from the main proc before any other procs have been created.
637 To create new processes, use
640 .\" It is safe to use
644 .\" to manage the namespace, file descriptors, note group, and environment of a
646 .\" That is, it is safe to call
656 .\" (To create new processes, use
660 .\" As mentioned above,
661 .\" the thread library depends on all procs being in the
662 .\" same rendezvous group; do not change the rendezvous
669 functions for debugging threaded programs.
671 .B \*9/src/libthread/test
672 contains some example programs.
679 To avoid name conflicts,
694 are defined as macros that expand to
699 is defined as a macro that expands to
707 threadkillgrp and threadpid are unimplemented.
709 The implementation of
713 There appears to be a race in the Linux NPTL
718 rather than coordinating a simultaneous
