46 yield \- thread and proc management
58 .ta 4n +4n +4n +4n +4n +4n +4n
69 .ta \w' 'u +\w'Channel 'u
70 typedef struct Alt Alt;
87 .ta \w'\fLChannel* 'u +4n +4n +4n +4n
88 void threadmain(int argc, char *argv[])
90 int proccreate(void (*fn)(void*), void *arg, uint stacksize)
91 int procrfork(void (*fn)(void*), void *arg, uint stacksize,
93 int threadcreate(void (*fn)(void*), void *arg, uint stacksize)
94 void threadexits(char *status)
95 void threadexitsall(char *status)
100 int threadsetgrp(int group)
101 int threadpid(int id)
103 int threadint(int id)
104 int threadintgrp(int group)
105 int threadkill(int id)
106 int threadkillgrp(int group)
108 void threadsetname(char *name)
109 char* threadgetname(void)
111 void** threaddata(void)
112 void** procdata(void)
114 int chaninit(Channel *c, int elsize, int nel)
115 Channel* chancreate(int elsize, int nel)
116 void chanfree(Channel *c)
119 int recv(Channel *c, void *v)
120 void* recvp(Channel *c)
121 ulong recvul(Channel *c)
122 int nbrecv(Channel *c, void *v)
123 void* nbrecvp(Channel *c)
124 ulong nbrecvul(Channel *c)
125 int send(Channel *c, void *v)
126 int sendp(Channel *c, void *v)
127 int sendul(Channel *c, ulong v)
128 int nbsend(Channel *c, void *v)
129 int nbsendp(Channel *c, void *v)
130 int nbsendul(Channel *c, ulong v)
131 int chanprint(Channel *c, char *fmt, ...)
133 int threadspawn(int fd[3], char *file, char *args[])
134 int threadexecl(Channel *cpid, int fd[3], char *file, ...)
135 int threadexec(Channel *cpid, int fd[3], char *file, char *args[])
136 Channel* threadwaitchan(void)
138 int threadnotify(int (*f)(void*, char*), int in)
142 The thread library provides parallel programming support similar to that
148 occupy a shared address space,
149 communicating and synchronizing through
151 and shared variables.
155 is a Plan 9 process that contains one or more cooperatively scheduled
157 Programs using threads must replace
161 The thread library provides a
163 function that sets up a proc with a single thread executing
167 (default eight kilobytes).
170 declare a global variable
171 initialized to the desired value
179 creates a new thread in the calling proc, returning a unique integer
180 identifying the thread; the thread
185 Thread stacks are allocated in shared memory, making it valid to pass
186 pointers to stack variables between threads and procs.
188 creates a new proc, and inside that proc creates
192 returning the id of the created thread.
194 .\" creates the new proc by calling
199 .\" .BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR.
200 .\" (The thread library depends on all its procs
201 .\" running in the same rendezvous group.
212 Be aware that the calling thread may continue
214 the newly created proc and thread
218 should not point to data on the stack of a function that could
219 return before the new process is scheduled.
222 terminates the calling thread.
223 If the thread is the last in its proc,
225 also terminates the proc, using
229 terminates all procs in the program,
234 When the last thread in
236 proc exits, the program will appear to its parent to have exited.
237 The remaining procs will still run together, but as a background program.
239 The threads in a proc are coroutines, scheduled nonpreemptively
240 in a round-robin fashion.
241 A thread must explicitly relinquish control of the processor
242 before another thread in the same proc is run.
243 Calls that do this are
254 (and the calls related to
258 their descriptions further on).
259 Procs are scheduled by the operating system.
260 Therefore, threads in different procs can preempt one another
261 in arbitrary ways and should synchronize their
266 or channel communication.
269 block the entire proc;
270 all threads in a proc block until the system call finishes.
272 As mentioned above, each thread has a unique integer thread id.
273 Thread ids are not reused; they are unique across the life of the program.
275 returns the id for the current thread.
276 Each thread also has a thread group id.
277 The initial thread has a group id of zero.
278 Each new thread inherits the group id of
279 the thread that created it.
281 returns the group id for the current thread;
285 returns the pid of the Plan 9 process containing
286 the thread identified by
289 if no such thread is found.
292 interrupts a thread that is blocked in a channel operation
295 interrupts all threads with the given group id.
297 marks a thread to die when it next relinquishes the processor
298 (via one of the calls listed above).
299 If the thread is blocked in a channel operation or system call,
300 it is also interrupted.
302 kills all threads with the given group id.
307 will not terminate a thread that never relinquishes
310 Primarily for debugging,
311 threads can have string names associated with them.
313 returns the current thread's name;
316 The pointer returned by
318 is only valid until the next call to
322 threads have a string state associated with them.
324 sets the state string.
327 since the thread scheduler resets the state to
329 every time it runs the thread,
330 it is only useful for debuggers to inspect the state.
333 returns a pointer to a per-thread pointer
334 that may be modified by threaded programs for
338 returns a pointer to a per-proc pointer.
343 are threaded analogues of
350 they replace the calling thread
351 and invoke the external program, never returning.
352 (Unlike on Plan 9, the calling thread need not be the only thread in its proc\(emthe other
353 threads will continue executing.)
354 On error, they return \-1.
357 is not null, the pid of the invoked program
362 once the program has been started, or \-1 will be sent if an
367 will not access their arguments after sending a result
370 Thus, programs that malloc the
374 can safely free it once they have
385 the three file descriptors in
387 onto standard input, output, and error for the external program
388 and then close them in the calling thread.
389 Beware of code that sets
396 to use the current standard files. The correct code is
407 but does not replace the current thread.
408 It returns the pid of the invoked program on success, or
412 returns a channel of pointers to
416 When an exec'ed process exits, a pointer to a
418 is sent to this channel.
421 structures have been allocated with
423 and should be freed after use.
427 is a buffered or unbuffered queue for fixed-size messages.
430 messages into the channel and
432 messages from the channel. If the channel is unbuffered, a
434 operation blocks until the corresponding
443 and with a buffer holding
448 is zero, the channel is unbuffered.
450 allocates a new channel and initializes it.
452 frees a channel that is no longer used.
454 can be called by either sender or receiver after the last item has been
455 sent or received. Freeing the channel will be delayed if there is a thread
456 blocked on it until that thread unblocks (but
458 returns immediately).
464 structure is a description intended for use in debugging.
469 sends the element pointed at by
475 is null, zeros are sent.
477 receives an element from
484 the received value is discarded.
488 return 1 on success, \-1 if interrupted.
492 behave similarly, but return 0 rather than blocking.
499 send a pointer or an unsigned long; the channel must
500 have been initialized with the appropriate
507 receive a pointer or an unsigned long;
508 they return zero when a zero is received,
514 when the operation would have blocked.
515 To distinguish between these three cases,
522 can be used to recv from or send to one of a number of channels,
523 as directed by an array of
526 each of which describes a potential send or receive operation.
533 the value pointer (which may be null); and
537 for a send operation,
539 for a recv operation;
545 is called with a varying set of operations).
548 structures is terminated by an entry with
555 structure can proceed, one of them is
556 chosen at random to be executed.
558 returns the index of the chosen structure.
559 If no operations can proceed and the list is terminated with
562 returns the index of the terminating
567 blocks until one of the operations can proceed,
568 eventually returning the index of the structure executes.
570 returns \-1 when interrupted.
577 structure are used internally by
579 and need not be initialized.
580 They are not used between
585 formats its arguments in the manner of
587 and sends the result to the channel
589 The string delivered by
593 and should be freed upon receipt.
595 Thread library functions do not return on failure;
596 if errors occur, the entire program is aborted.
598 Threaded programs should use
607 in threaded programs.
609 will print the error string and call
612 It is not safe to call
614 in a threaded program, except to call
616 from the main proc before any other procs have been created.
617 To create new processes, use
620 .\" It is safe to use
624 .\" to manage the namespace, file descriptors, note group, and environment of a
626 .\" That is, it is safe to call
636 .\" (To create new processes, use
640 .\" As mentioned above,
641 .\" the thread library depends on all procs being in the
642 .\" same rendezvous group; do not change the rendezvous
649 functions for debugging threaded programs.
651 .B \*9/src/libthread/test
652 contains some example programs.
659 A program that intends to use the thread library
660 but does not call any of its functions will not cause Unix linkers
661 to link the thread library, resulting in the unintelligible error:
664 \*9/lib/lib9.a(main.o)(.text+0x17): In function `main':
665 \*9/src/lib9/main.c:10: undefined reference to `p9main'
668 or similar. To force the thread library to be linked properly in such cases,
669 insert a call to the no-op function
671 somewhere in your program.
673 To avoid name conflicts,
688 are defined as macros that expand to
694 is defined as a macro that expands to
697 The implementation of
