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
176 is ignored, as is the stack size argument to
178 the first thread in each proc
179 runs on the native system stack.
182 creates a new thread in the calling proc, returning a unique integer
183 identifying the thread; the thread
188 Thread stacks are allocated in shared memory, making it valid to pass
189 pointers to stack variables between threads and procs.
191 creates a new proc, and inside that proc creates
195 returning the id of the created thread.
197 .\" creates the new proc by calling
202 .\" .BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR.
203 .\" (The thread library depends on all its procs
204 .\" running in the same rendezvous group.
215 Be aware that the calling thread may continue
217 the newly created proc and thread
221 should not point to data on the stack of a function that could
222 return before the new process is scheduled.
225 terminates the calling thread.
226 If the thread is the last in its proc,
228 also terminates the proc, using
232 terminates all procs in the program,
237 When the last thread in
239 proc exits, the program will appear to its parent to have exited.
240 The remaining procs will still run together, but as a background program.
242 The threads in a proc are coroutines, scheduled nonpreemptively
243 in a round-robin fashion.
244 A thread must explicitly relinquish control of the processor
245 before another thread in the same proc is run.
246 Calls that do this are
259 (and the calls related to
263 their descriptions further on).
264 Procs are scheduled by the operating system.
265 Therefore, threads in different procs can preempt one another
266 in arbitrary ways and should synchronize their
271 or channel communication.
274 block the entire proc;
275 all threads in a proc block until the system call finishes.
278 disables scheduling inside a proc, `pinning' the current
279 thread as the only runnable one in the current proc.
281 reenables scheduling, allowing other procs to run once the current
282 thread relinquishes the processor.
286 can lead to deadlock.
287 Used carefully, they can make library routines that use
289 appear atomic relative to the current proc, like a system call.
291 As mentioned above, each thread has a unique integer thread id.
292 Thread ids are not reused; they are unique across the life of the program.
294 returns the id for the current thread.
295 Each thread also has a thread group id.
296 The initial thread has a group id of zero.
297 Each new thread inherits the group id of
298 the thread that created it.
300 returns the group id for the current thread;
304 returns the pid of the Plan 9 process containing
305 the thread identified by
308 if no such thread is found.
311 interrupts a thread that is blocked in a channel operation
314 interrupts all threads with the given group id.
316 marks a thread to die when it next relinquishes the processor
317 (via one of the calls listed above).
318 If the thread is blocked in a channel operation or system call,
319 it is also interrupted.
321 kills all threads with the given group id.
326 will not terminate a thread that never relinquishes
329 Primarily for debugging,
330 threads can have string names associated with them.
332 returns the current thread's name;
335 The pointer returned by
337 is only valid until the next call to
341 threads have a string state associated with them.
343 sets the state string.
346 since the thread scheduler resets the state to
348 every time it runs the thread,
349 it is only useful for debuggers to inspect the state.
352 returns a pointer to a per-thread pointer
353 that may be modified by threaded programs for
357 returns a pointer to a per-proc pointer.
362 are threaded analogues of
369 they replace the calling thread
370 and invoke the external program, never returning.
371 (Unlike on Plan 9, the calling thread need not be the only thread in its proc\(emthe other
372 threads will continue executing.)
373 On error, they return \-1.
376 is not null, the pid of the invoked program
381 once the program has been started, or \-1 will be sent if an
386 will not access their arguments after sending a result
389 Thus, programs that malloc the
393 can safely free it once they have
404 the three file descriptors in
406 onto standard input, output, and error for the external program
407 and then close them in the calling thread.
408 Beware of code that sets
416 to use the current standard files. The correct code is
431 but do not replace the current thread.
432 They return the pid of the invoked program on success, or
437 but takes as its final argument the directory in which to run the invoked program.
438 The child will attempt to change into that directory before running the program,
439 but it is only best effort: failure to change into the directory does not
440 stop the running of the program.
443 returns a channel of pointers to
447 When an exec'ed process exits, a pointer to a
449 is sent to this channel.
452 structures have been allocated with
454 and should be freed after use.
458 is a buffered or unbuffered queue for fixed-size messages.
461 messages into the channel and
463 messages from the channel. If the channel is unbuffered, a
465 operation blocks until the corresponding
470 allocates a new channel
473 and with a buffer holding
478 is zero, the channel is unbuffered.
480 frees a channel that is no longer used.
482 can be called by either sender or receiver after the last item has been
483 sent or received. Freeing the channel will be delayed if there is a thread
484 blocked on it until that thread unblocks (but
486 returns immediately).
492 structure is a description intended for use in debugging.
497 sends the element pointed at by
503 is null, zeros are sent.
505 receives an element from
512 the received value is discarded.
516 return 1 on success, \-1 if interrupted.
520 behave similarly, but return 0 rather than blocking.
527 send a pointer or an unsigned long; the channel must
528 have been initialized with the appropriate
535 receive a pointer or an unsigned long;
536 they return zero when a zero is received,
542 when the operation would have blocked.
543 To distinguish between these three cases,
550 can be used to recv from or send to one of a number of channels,
551 as directed by an array of
554 each of which describes a potential send or receive operation.
561 the value pointer (which may be null); and
565 for a send operation,
567 for a recv operation;
573 is called with a varying set of operations).
576 structures is terminated by an entry with
583 structure can proceed, one of them is
584 chosen at random to be executed.
586 returns the index of the chosen structure.
587 If no operations can proceed and the list is terminated with
590 returns the index of the terminating
595 blocks until one of the operations can proceed,
596 eventually returning the index of the structure executes.
598 returns \-1 when interrupted.
605 structure are used internally by
607 and need not be initialized.
608 They are not used between
613 formats its arguments in the manner of
615 and sends the result to the channel
617 The string delivered by
621 and should be freed upon receipt.
623 Thread library functions do not return on failure;
624 if errors occur, the entire program is aborted.
626 Threaded programs should use
635 in threaded programs.
637 will print the error string and call
640 It is not safe to call
642 in a threaded program, except to call
644 from the main proc before any other procs have been created.
645 To create new processes, use
648 .\" It is safe to use
652 .\" to manage the namespace, file descriptors, note group, and environment of a
654 .\" That is, it is safe to call
664 .\" (To create new processes, use
668 .\" As mentioned above,
669 .\" the thread library depends on all procs being in the
670 .\" same rendezvous group; do not change the rendezvous
677 functions for debugging threaded programs.
679 .B \*9/src/libthread/test
680 contains some example programs.
687 To avoid name conflicts,
702 are defined as macros that expand to
707 is defined as a macro that expands to
715 threadkillgrp and threadpid are unimplemented.
717 The implementation of
721 There appears to be a race in the Linux NPTL
726 rather than coordinating a simultaneous
