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 int chaninit(Channel *c, int elsize, int nel)
109 Channel* chancreate(int elsize, int nel)
110 void chanfree(Channel *c)
113 int recv(Channel *c, void *v)
114 void* recvp(Channel *c)
115 ulong recvul(Channel *c)
116 int nbrecv(Channel *c, void *v)
117 void* nbrecvp(Channel *c)
118 ulong nbrecvul(Channel *c)
119 int send(Channel *c, void *v)
120 int sendp(Channel *c, void *v)
121 int sendul(Channel *c, ulong v)
122 int nbsend(Channel *c, void *v)
123 int nbsendp(Channel *c, void *v)
124 int nbsendul(Channel *c, ulong v)
125 int chanprint(Channel *c, char *fmt, ...)
127 int threadspawnl(int fd[3], char *file, ...)
128 int threadspawn(int fd[3], char *file, char *args[])
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
249 (and the calls related to
253 their descriptions further on).
254 Procs are scheduled by the operating system.
255 Therefore, threads in different procs can preempt one another
256 in arbitrary ways and should synchronize their
261 or channel communication.
264 block the entire proc;
265 all threads in a proc block until the system call finishes.
268 disables scheduling inside a proc, `pinning' the current
269 thread as the only runnable one in the current proc.
271 reenables scheduling, allowing other procs to run once the current
272 thread relinquishes the processor.
276 can lead to deadlock.
277 Used carefully, they can make library routines that use
279 appear atomic relative to the current proc, like a system call.
281 As mentioned above, each thread has a unique integer thread id.
282 Thread ids are not reused; they are unique across the life of the program.
284 returns the id for the current thread.
285 Each thread also has a thread group id.
286 The initial thread has a group id of zero.
287 Each new thread inherits the group id of
288 the thread that created it.
290 returns the group id for the current thread;
294 returns the pid of the Plan 9 process containing
295 the thread identified by
298 if no such thread is found.
301 interrupts a thread that is blocked in a channel operation
304 interrupts all threads with the given group id.
306 marks a thread to die when it next relinquishes the processor
307 (via one of the calls listed above).
308 If the thread is blocked in a channel operation or system call,
309 it is also interrupted.
311 kills all threads with the given group id.
316 will not terminate a thread that never relinquishes
319 Primarily for debugging,
320 threads can have string names associated with them.
322 returns the current thread's name;
325 The pointer returned by
327 is only valid until the next call to
331 threads have a string state associated with them.
333 sets the state string.
336 since the thread scheduler resets the state to
338 every time it runs the thread,
339 it is only useful for debuggers to inspect the state.
342 returns a pointer to a per-thread pointer
343 that may be modified by threaded programs for
347 returns a pointer to a per-proc pointer.
352 are threaded analogues of
359 they replace the calling thread
360 and invoke the external program, never returning.
361 (Unlike on Plan 9, the calling thread need not be the only thread in its proc\(emthe other
362 threads will continue executing.)
363 On error, they return \-1.
366 is not null, the pid of the invoked program
371 once the program has been started, or \-1 will be sent if an
376 will not access their arguments after sending a result
379 Thus, programs that malloc the
383 can safely free it once they have
394 the three file descriptors in
396 onto standard input, output, and error for the external program
397 and then close them in the calling thread.
398 Beware of code that sets
406 to use the current standard files. The correct code is
421 but do not replace the current thread.
422 They return the pid of the invoked program on success, or
426 returns a channel of pointers to
430 When an exec'ed process exits, a pointer to a
432 is sent to this channel.
435 structures have been allocated with
437 and should be freed after use.
441 is a buffered or unbuffered queue for fixed-size messages.
444 messages into the channel and
446 messages from the channel. If the channel is unbuffered, a
448 operation blocks until the corresponding
457 and with a buffer holding
462 is zero, the channel is unbuffered.
464 allocates a new channel and initializes it.
466 frees a channel that is no longer used.
468 can be called by either sender or receiver after the last item has been
469 sent or received. Freeing the channel will be delayed if there is a thread
470 blocked on it until that thread unblocks (but
472 returns immediately).
478 structure is a description intended for use in debugging.
483 sends the element pointed at by
489 is null, zeros are sent.
491 receives an element from
498 the received value is discarded.
502 return 1 on success, \-1 if interrupted.
506 behave similarly, but return 0 rather than blocking.
513 send a pointer or an unsigned long; the channel must
514 have been initialized with the appropriate
521 receive a pointer or an unsigned long;
522 they return zero when a zero is received,
528 when the operation would have blocked.
529 To distinguish between these three cases,
536 can be used to recv from or send to one of a number of channels,
537 as directed by an array of
540 each of which describes a potential send or receive operation.
547 the value pointer (which may be null); and
551 for a send operation,
553 for a recv operation;
559 is called with a varying set of operations).
562 structures is terminated by an entry with
569 structure can proceed, one of them is
570 chosen at random to be executed.
572 returns the index of the chosen structure.
573 If no operations can proceed and the list is terminated with
576 returns the index of the terminating
581 blocks until one of the operations can proceed,
582 eventually returning the index of the structure executes.
584 returns \-1 when interrupted.
591 structure are used internally by
593 and need not be initialized.
594 They are not used between
599 formats its arguments in the manner of
601 and sends the result to the channel
603 The string delivered by
607 and should be freed upon receipt.
609 Thread library functions do not return on failure;
610 if errors occur, the entire program is aborted.
612 Threaded programs should use
621 in threaded programs.
623 will print the error string and call
626 It is not safe to call
628 in a threaded program, except to call
630 from the main proc before any other procs have been created.
631 To create new processes, use
634 .\" It is safe to use
638 .\" to manage the namespace, file descriptors, note group, and environment of a
640 .\" That is, it is safe to call
650 .\" (To create new processes, use
654 .\" As mentioned above,
655 .\" the thread library depends on all procs being in the
656 .\" same rendezvous group; do not change the rendezvous
663 functions for debugging threaded programs.
665 .B \*9/src/libthread/test
666 contains some example programs.
673 To avoid name conflicts,
688 are defined as macros that expand to
693 is defined as a macro that expands to
698 The implementation of
702 There appears to be a race in the Linux NPTL
707 rather than coordinating a simultaneous
