49 yield \- thread and proc management
53 .ta 4n +4n +4n +4n +4n +4n +4n
64 .ta \w' 'u +\w'Channel 'u
65 typedef struct Alt Alt;
82 .ta \w'\fLChannel* 'u +4n +4n +4n +4n
83 void threadmain(int argc, char *argv[])
84 int threadmaybackground(void)
86 int proccreate(void (*fn)(void*), void *arg, uint stacksize)
87 int threadcreate(void (*fn)(void*), void *arg, uint stacksize)
88 void threadexits(char *status)
89 void threadexitsall(char *status)
96 int threadsetgrp(int group)
100 int threadintgrp(int group)
101 int threadkill(int id)
102 int threadkillgrp(int group)
104 void threadsetname(char *name)
105 char* threadgetname(void)
107 void** threaddata(void)
108 void** procdata(void)
110 Channel* chancreate(int elsize, int nel)
111 void chanfree(Channel *c)
114 int recv(Channel *c, void *v)
115 void* recvp(Channel *c)
116 ulong recvul(Channel *c)
117 int nbrecv(Channel *c, void *v)
118 void* nbrecvp(Channel *c)
119 ulong nbrecvul(Channel *c)
120 int send(Channel *c, void *v)
121 int sendp(Channel *c, void *v)
122 int sendul(Channel *c, ulong v)
123 int nbsend(Channel *c, void *v)
124 int nbsendp(Channel *c, void *v)
125 int nbsendul(Channel *c, ulong v)
126 int chanprint(Channel *c, char *fmt, ...)
128 int threadspawnl(int fd[3], char *file, ...)
129 int threadspawn(int fd[3], char *file, char *args[])
130 int threadspawnd(int fd[3], char *file, char *args[], char *dir)
131 int threadexecl(Channel *cpid, int fd[3], char *file, ...)
132 int threadexec(Channel *cpid, int fd[3], char *file, char *args[])
133 Channel* threadwaitchan(void)
135 int threadnotify(int (*f)(void*, char*), int in)
139 The thread library provides parallel programming support similar to that
145 occupy a shared address space,
146 communicating and synchronizing through
148 and shared variables.
152 is a Plan 9 process that contains one or more cooperatively scheduled
154 Programs using threads must replace
158 The thread library provides a
160 function that sets up a proc with a single thread executing
163 Every thread is backed by an operating system-provided
165 and runs on its system-provided stack;
167 and the the stack size arguments to
172 Although each thread is backed by a separate
174 the threads in a proc are still scheduled non-preemptively
175 as on Plan 9 and as described below.
178 creates a new thread in the calling proc, returning a unique integer
179 identifying the thread; the thread
184 Thread stacks are allocated in shared memory, making it valid to pass
185 pointers to stack variables between threads and procs.
187 creates a new proc, and inside that proc creates
191 returning the id of the created thread.
193 .\" creates the new proc by calling
198 .\" .BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR.
199 .\" (The thread library depends on all its procs
200 .\" running in the same rendezvous group.
211 Be aware that the calling thread may continue
213 the newly created proc and thread
217 should not point to data on the stack of a function that could
218 return before the new process is scheduled.
221 terminates the calling thread.
222 If the thread is the last in its proc,
224 also terminates the proc, using
228 terminates all procs in the program,
233 When the last thread in
235 proc exits, the program will appear to its parent to have exited.
236 The remaining procs will still run together, but as a background program.
237 This functionality can only be relied upon if the program defines a function
238 .I threadmaybackground
239 returning a non-zero result.
240 Programs that do not define such a
241 .I threadmaybackground
242 will crash instead should the last thread in
244 proc exit leaving behind other running procs.
246 The threads in a proc are coroutines, scheduled nonpreemptively
247 in a round-robin fashion.
248 A thread must explicitly relinquish control of the processor
249 before another thread in the same proc is run.
250 Calls that do this are
263 (and the calls related to
267 their descriptions further on).
268 Procs are scheduled by the operating system.
269 Therefore, threads in different procs can preempt one another
270 in arbitrary ways and should synchronize their
275 or channel communication.
278 block the entire proc;
279 all threads in a proc block until the system call finishes.
282 disables scheduling inside a proc, `pinning' the current
283 thread as the only runnable one in the current proc.
285 reenables scheduling, allowing other procs to run once the current
286 thread relinquishes the processor.
290 can lead to deadlock.
291 Used carefully, they can make library routines that use
293 appear atomic relative to the current proc, like a system call.
295 As mentioned above, each thread has a unique integer thread id.
296 Thread ids are not reused; they are unique across the life of the program.
298 returns the id for the current thread.
299 Each thread also has a thread group id.
300 The initial thread has a group id of zero.
301 Each new thread inherits the group id of
302 the thread that created it.
304 returns the group id for the current thread;
308 returns the pid of the Plan 9 process containing
309 the thread identified by
312 if no such thread is found.
315 interrupts a thread that is blocked in a channel operation
318 interrupts all threads with the given group id.
320 marks a thread to die when it next relinquishes the processor
321 (via one of the calls listed above).
322 If the thread is blocked in a channel operation or system call,
323 it is also interrupted.
325 kills all threads with the given group id.
330 will not terminate a thread that never relinquishes
333 Primarily for debugging,
334 threads can have string names associated with them.
336 returns the current thread's name;
339 The pointer returned by
341 is only valid until the next call to
345 threads have a string state associated with them.
347 sets the state string.
350 since the thread scheduler resets the state to
352 every time it runs the thread,
353 it is only useful for debuggers to inspect the state.
356 returns a pointer to a per-thread pointer
357 that may be modified by threaded programs for
361 returns a pointer to a per-proc pointer.
366 are threaded analogues of
373 they replace the calling thread
374 and invoke the external program, never returning.
375 (Unlike on Plan 9, the calling thread need not be the only thread in its proc\(emthe other
376 threads will continue executing.)
377 On error, they return \-1.
380 is not null, the pid of the invoked program
385 once the program has been started, or \-1 will be sent if an
390 will not access their arguments after sending a result
393 Thus, programs that malloc the
397 can safely free it once they have
408 the three file descriptors in
410 onto standard input, output, and error for the external program
411 and then close them in the calling thread.
412 Beware of code that sets
420 to use the current standard files. The correct code is
435 but do not replace the current thread.
436 They return the pid of the invoked program on success, or
441 but takes as its final argument the directory in which to run the invoked program.
442 The child will attempt to change into that directory before running the program,
443 but it is only best effort: failure to change into the directory does not
444 stop the running of the program.
447 returns a channel of pointers to
451 When an exec'ed process exits, a pointer to a
453 is sent to this channel.
456 structures have been allocated with
458 and should be freed after use.
462 is a buffered or unbuffered queue for fixed-size messages.
465 messages into the channel and
467 messages from the channel. If the channel is unbuffered, a
469 operation blocks until the corresponding
474 allocates a new channel
477 and with a buffer holding
482 is zero, the channel is unbuffered.
484 frees a channel that is no longer used.
486 can be called by either sender or receiver after the last item has been
487 sent or received. Freeing the channel will be delayed if there is a thread
488 blocked on it until that thread unblocks (but
490 returns immediately).
496 structure is a description intended for use in debugging.
501 sends the element pointed at by
507 is null, zeros are sent.
509 receives an element from
516 the received value is discarded.
520 return 1 on success, \-1 if interrupted.
524 behave similarly, but return 0 rather than blocking.
531 send a pointer or an unsigned long; the channel must
532 have been initialized with the appropriate
539 receive a pointer or an unsigned long;
540 they return zero when a zero is received,
546 when the operation would have blocked.
547 To distinguish between these three cases,
554 can be used to recv from or send to one of a number of channels,
555 as directed by an array of
558 each of which describes a potential send or receive operation.
565 the value pointer (which may be null); and
569 for a send operation,
571 for a recv operation;
577 is called with a varying set of operations).
580 structures is terminated by an entry with
587 structure can proceed, one of them is
588 chosen at random to be executed.
590 returns the index of the chosen structure.
591 If no operations can proceed and the list is terminated with
594 returns the index of the terminating
599 blocks until one of the operations can proceed,
600 eventually returning the index of the structure executes.
602 returns \-1 when interrupted.
609 structure are used internally by
611 and need not be initialized.
612 They are not used between
617 formats its arguments in the manner of
619 and sends the result to the channel
621 The string delivered by
625 and should be freed upon receipt.
627 Thread library functions do not return on failure;
628 if errors occur, the entire program is aborted.
630 Threaded programs should use
639 in threaded programs.
641 will print the error string and call
644 It is not safe to call
646 in a threaded program, except to call
648 from the main proc before any other procs have been created.
649 To create new processes, use
652 .\" It is safe to use
656 .\" to manage the namespace, file descriptors, note group, and environment of a
658 .\" That is, it is safe to call
668 .\" (To create new processes, use
672 .\" As mentioned above,
673 .\" the thread library depends on all procs being in the
674 .\" same rendezvous group; do not change the rendezvous
681 functions for debugging threaded programs.
683 .B \*9/src/libthread/test
684 contains some example programs.
691 To avoid name conflicts,
706 are defined as macros that expand to
711 is defined as a macro that expands to
719 threadkillgrp and threadpid are unimplemented.
721 The implementation of
725 There appears to be a race in the Linux NPTL
730 rather than coordinating a simultaneous
