46 yield \- thread and proc management
50 .ta 4n +4n +4n +4n +4n +4n +4n
61 .ta \w' 'u +\w'Channel 'u
62 typedef struct Alt Alt;
79 .ta \w'\fLChannel* 'u +4n +4n +4n +4n
80 void threadmain(int argc, char *argv[])
82 int proccreate(void (*fn)(void*), void *arg, uint stacksize)
83 int threadcreate(void (*fn)(void*), void *arg, uint stacksize)
84 void threadexits(char *status)
85 void threadexitsall(char *status)
90 int threadsetgrp(int group)
94 int threadintgrp(int group)
95 int threadkill(int id)
96 int threadkillgrp(int group)
98 void threadsetname(char *name)
99 char* threadgetname(void)
101 void** threaddata(void)
102 void** procdata(void)
104 int chaninit(Channel *c, int elsize, int nel)
105 Channel* chancreate(int elsize, int nel)
106 void chanfree(Channel *c)
109 int recv(Channel *c, void *v)
110 void* recvp(Channel *c)
111 ulong recvul(Channel *c)
112 int nbrecv(Channel *c, void *v)
113 void* nbrecvp(Channel *c)
114 ulong nbrecvul(Channel *c)
115 int send(Channel *c, void *v)
116 int sendp(Channel *c, void *v)
117 int sendul(Channel *c, ulong v)
118 int nbsend(Channel *c, void *v)
119 int nbsendp(Channel *c, void *v)
120 int nbsendul(Channel *c, ulong v)
121 int chanprint(Channel *c, char *fmt, ...)
123 int threadspawnl(int fd[3], char *file, ...)
124 int threadspawn(int fd[3], char *file, char *args[])
125 int threadexecl(Channel *cpid, int fd[3], char *file, ...)
126 int threadexec(Channel *cpid, int fd[3], char *file, char *args[])
127 Channel* threadwaitchan(void)
129 int threadnotify(int (*f)(void*, char*), int in)
133 The thread library provides parallel programming support similar to that
139 occupy a shared address space,
140 communicating and synchronizing through
142 and shared variables.
146 is a Plan 9 process that contains one or more cooperatively scheduled
148 Programs using threads must replace
152 The thread library provides a
154 function that sets up a proc with a single thread executing
158 (default eight kilobytes).
161 declare a global variable
162 initialized to the desired value
170 creates a new thread in the calling proc, returning a unique integer
171 identifying the thread; the thread
176 Thread stacks are allocated in shared memory, making it valid to pass
177 pointers to stack variables between threads and procs.
179 creates a new proc, and inside that proc creates
183 returning the id of the created thread.
185 .\" creates the new proc by calling
190 .\" .BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR.
191 .\" (The thread library depends on all its procs
192 .\" running in the same rendezvous group.
203 Be aware that the calling thread may continue
205 the newly created proc and thread
209 should not point to data on the stack of a function that could
210 return before the new process is scheduled.
213 terminates the calling thread.
214 If the thread is the last in its proc,
216 also terminates the proc, using
220 terminates all procs in the program,
225 When the last thread in
227 proc exits, the program will appear to its parent to have exited.
228 The remaining procs will still run together, but as a background program.
230 The threads in a proc are coroutines, scheduled nonpreemptively
231 in a round-robin fashion.
232 A thread must explicitly relinquish control of the processor
233 before another thread in the same proc is run.
234 Calls that do this are
245 (and the calls related to
249 their descriptions further on).
250 Procs are scheduled by the operating system.
251 Therefore, threads in different procs can preempt one another
252 in arbitrary ways and should synchronize their
257 or channel communication.
260 block the entire proc;
261 all threads in a proc block until the system call finishes.
263 As mentioned above, each thread has a unique integer thread id.
264 Thread ids are not reused; they are unique across the life of the program.
266 returns the id for the current thread.
267 Each thread also has a thread group id.
268 The initial thread has a group id of zero.
269 Each new thread inherits the group id of
270 the thread that created it.
272 returns the group id for the current thread;
276 returns the pid of the Plan 9 process containing
277 the thread identified by
280 if no such thread is found.
283 interrupts a thread that is blocked in a channel operation
286 interrupts all threads with the given group id.
288 marks a thread to die when it next relinquishes the processor
289 (via one of the calls listed above).
290 If the thread is blocked in a channel operation or system call,
291 it is also interrupted.
293 kills all threads with the given group id.
298 will not terminate a thread that never relinquishes
301 Primarily for debugging,
302 threads can have string names associated with them.
304 returns the current thread's name;
307 The pointer returned by
309 is only valid until the next call to
313 threads have a string state associated with them.
315 sets the state string.
318 since the thread scheduler resets the state to
320 every time it runs the thread,
321 it is only useful for debuggers to inspect the state.
324 returns a pointer to a per-thread pointer
325 that may be modified by threaded programs for
329 returns a pointer to a per-proc pointer.
334 are threaded analogues of
341 they replace the calling thread
342 and invoke the external program, never returning.
343 (Unlike on Plan 9, the calling thread need not be the only thread in its proc\(emthe other
344 threads will continue executing.)
345 On error, they return \-1.
348 is not null, the pid of the invoked program
353 once the program has been started, or \-1 will be sent if an
358 will not access their arguments after sending a result
361 Thus, programs that malloc the
365 can safely free it once they have
376 the three file descriptors in
378 onto standard input, output, and error for the external program
379 and then close them in the calling thread.
380 Beware of code that sets
388 to use the current standard files. The correct code is
403 but do not replace the current thread.
404 They return the pid of the invoked program on success, or
408 returns a channel of pointers to
412 When an exec'ed process exits, a pointer to a
414 is sent to this channel.
417 structures have been allocated with
419 and should be freed after use.
423 is a buffered or unbuffered queue for fixed-size messages.
426 messages into the channel and
428 messages from the channel. If the channel is unbuffered, a
430 operation blocks until the corresponding
439 and with a buffer holding
444 is zero, the channel is unbuffered.
446 allocates a new channel and initializes it.
448 frees a channel that is no longer used.
450 can be called by either sender or receiver after the last item has been
451 sent or received. Freeing the channel will be delayed if there is a thread
452 blocked on it until that thread unblocks (but
454 returns immediately).
460 structure is a description intended for use in debugging.
465 sends the element pointed at by
471 is null, zeros are sent.
473 receives an element from
480 the received value is discarded.
484 return 1 on success, \-1 if interrupted.
488 behave similarly, but return 0 rather than blocking.
495 send a pointer or an unsigned long; the channel must
496 have been initialized with the appropriate
503 receive a pointer or an unsigned long;
504 they return zero when a zero is received,
510 when the operation would have blocked.
511 To distinguish between these three cases,
518 can be used to recv from or send to one of a number of channels,
519 as directed by an array of
522 each of which describes a potential send or receive operation.
529 the value pointer (which may be null); and
533 for a send operation,
535 for a recv operation;
541 is called with a varying set of operations).
544 structures is terminated by an entry with
551 structure can proceed, one of them is
552 chosen at random to be executed.
554 returns the index of the chosen structure.
555 If no operations can proceed and the list is terminated with
558 returns the index of the terminating
563 blocks until one of the operations can proceed,
564 eventually returning the index of the structure executes.
566 returns \-1 when interrupted.
573 structure are used internally by
575 and need not be initialized.
576 They are not used between
581 formats its arguments in the manner of
583 and sends the result to the channel
585 The string delivered by
589 and should be freed upon receipt.
591 Thread library functions do not return on failure;
592 if errors occur, the entire program is aborted.
594 Threaded programs should use
603 in threaded programs.
605 will print the error string and call
608 It is not safe to call
610 in a threaded program, except to call
612 from the main proc before any other procs have been created.
613 To create new processes, use
616 .\" It is safe to use
620 .\" to manage the namespace, file descriptors, note group, and environment of a
622 .\" That is, it is safe to call
632 .\" (To create new processes, use
636 .\" As mentioned above,
637 .\" the thread library depends on all procs being in the
638 .\" same rendezvous group; do not change the rendezvous
645 functions for debugging threaded programs.
647 .B \*9/src/libthread/test
648 contains some example programs.
655 To avoid name conflicts,
670 are defined as macros that expand to
675 is defined as a macro that expands to
680 The implementation of
684 There appears to be a race in the Linux NPTL
689 rather than coordinating a simultaneous
