45 yield \- thread and proc management
48 .ta 4n +4n +4n +4n +4n +4n +4n
61 .ta \w' 'u +\w'Channel 'u
62 typedef struct Alt Alt;
64 Channel *c; /* channel */
65 void *v; /* pointer to value */
66 ChanOp op; /* operation */
67 char *err; /* did the op fail? */
69 * the next variables are used internally to alt
70 * they need not be initialized
72 Channel **tag; /* pointer to rendez-vous tag */
73 int entryno; /* entry number */
83 .ta \w'\fLChannel* 'u +4n +4n +4n +4n
84 void threadmain(int argc, char *argv[])
86 int proccreate(void (*fn)(void*), void *arg, uint stacksize)
87 int procrfork(void (*fn)(void*), void *arg, uint stacksize,
89 int threadcreate(void (*fn)(void*), void *arg, uint stacksize)
90 void threadexits(char *status)
91 void threadexitsall(char *status)
96 int threadsetgrp(int group)
100 void threadintgrp(int group)
101 void 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 int chaninit(Channel *c, int elsize, int nel)
111 Channel* chancreate(int elsize, int nel)
112 void chanfree(Channel *c)
115 int recv(Channel *c, void *v)
116 void* recvp(Channel *c)
117 ulong recvul(Channel *c)
118 int nbrecv(Channel *c, void *v)
119 void* nbrecvp(Channel *c)
120 ulong nbrecvul(Channel *c)
121 int send(Channel *c, void *v)
122 int sendp(Channel *c, void *v)
123 int sendul(Channel *c, ulong v)
124 int nbsend(Channel *c, void *v)
125 int nbsendp(Channel *c, void *v)
126 int nbsendul(Channel *c, ulong v)
127 int chanprint(Channel *c, char *fmt, ...)
128 int chanclose(Channel *c);
129 int chanclosing(Channel *c);
131 void procexecl(Channel *cpid, char *file, ...)
132 void procexec(Channel *cpid, char *file, char *args[])
133 Channel* threadwaitchan(void)
135 int threadnotify(int (*f)(void*, char*), int in)
138 The thread library provides parallel programming support similar to that
144 occupy a shared address space,
145 communicating and synchronizing through
147 and shared variables.
151 is a Plan 9 process that contains one or more cooperatively-scheduled
153 Programs using threads must replace
157 The thread library provides a
159 function that sets up a proc with a single thread executing
163 (default eight kilobytes).
166 declare a global variable
167 initialized to the desired value
175 creates a new thread in the calling proc, returning a unique integer
176 identifying the thread; the thread
181 Thread stacks are allocated in shared memory, making it valid to pass
182 pointers to stack variables between threads and procs.
184 creates a new proc, and inside that proc creates
188 returning the id of the created thread.
190 creates the new proc by calling
195 .BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR.
196 (The thread library depends on all its procs
197 running in the same rendezvous group.
208 Be aware that the calling thread may continue
210 the newly created proc and thread
214 should not point to data on the stack of a function that could
215 return before the new process is scheduled.
218 terminates the calling thread.
219 If the thread is the last in its proc,
221 also terminates the proc, using
225 terminates all procs in the program,
230 The threads in a proc are coroutines, scheduled non-preemptively
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
244 (and the calls related to
248 their descriptions further on),
255 Procs are scheduled by the operating system.
256 Therefore, threads in different procs can preempt one another
257 in arbitrary ways and should synchronize their
262 or channel communication.
265 block the entire proc;
266 all threads in a proc block until the system call finishes.
268 As mentioned above, each thread has a unique integer thread id.
269 Thread ids are not reused; they are unique across the life of the program.
271 returns the id for the current thread.
272 Each thread also has a thread group id.
273 The initial thread has a group id of zero.
274 Each new thread inherits the group id of
275 the thread that created it.
277 returns the group id for the current thread;
281 returns the pid of the Plan 9 process containing
282 the thread identified by
285 if no such thread is found.
288 interrupts a thread that is blocked in a channel operation
291 interrupts all threads with the given group id.
293 marks a thread to die when it next relinquishes the processor
294 (via one of the calls listed above).
295 If the thread is blocked in a channel operation or system call,
296 it is also interrupted.
298 kills all threads with the given group id.
303 will not terminate a thread that never relinquishes
305 .SS Names and per-thread data
306 Primarily for debugging,
307 threads can have string names associated with them.
309 returns the current thread's name;
312 The pointer returned by
314 is only valid until the next call to
318 returns a pointer to a per-thread pointer
319 that may be modified by threaded programs for
323 returns a pointer to a per-proc pointer.
324 .SS Executing new programs
328 are threaded analogues of
335 they replace the calling thread (which must be the only thread in its proc)
336 and invoke the external program, never returning.
337 On error, they return \-1.
340 is not null, the pid of the invoked program
343 once the program has been started, or \-1 will be sent if an
348 will not access their arguments after sending a result
351 Thus, programs that malloc the
355 can safely free it once they have
359 Note that the mount point
366 returns a channel of pointers to
370 When an exec'ed process exits, a pointer to a
372 is sent to this channel.
375 structures have been allocated with
377 and should be freed after use.
381 is a buffered or unbuffered queue for fixed-size messages.
384 messages into the channel and
386 messages from the channel. If the channel is unbuffered, a
388 operation blocks until the corresponding
397 and with a buffer holding
402 is zero, the channel is unbuffered.
404 allocates a new channel and initializes it.
406 frees a channel that is no longer used.
408 can be called by either sender or receiver after the last item has been
409 sent or received. Freeing the channel will be delayed if there is a thread
410 blocked on it until that thread unblocks (but
412 returns immediately).
415 sends the element pointed at by
421 is null, zeros are sent.
423 receives an element from
430 the received value is discarded.
434 return 1 on success, \-1 if interrupted.
438 behave similarly, but return 0 rather than blocking.
445 send a pointer or an unsigned long; the channel must
446 have been initialized with the appropriate
453 receive a pointer or an unsigned long;
454 they return zero when a zero is received,
460 when the operation would have blocked.
461 To distinguish between these three cases,
468 can be used to recv from or send to one of a number of channels,
469 as directed by an array of
472 each of which describes a potential send or receive operation.
479 the value pointer (which may be null); and
483 for a send operation,
485 for a recv operation;
491 is called with a varying set of operations).
494 structures is terminated by an entry with
501 structure can proceed, one of them is
502 chosen at random to be executed.
504 returns the index of the chosen structure.
505 If no operations can proceed and the list is terminated with
508 returns the index of the terminating
513 blocks until one of the operations can proceed,
514 eventually returning the index of the structure executes.
516 returns \-1 when interrupted.
523 structure are used internally by
525 and need not be initialized.
526 They are not used between
531 formats its arguments in the manner of
533 and sends the result to the channel
535 The string delivered by
539 and should be freed upon receipt.
542 prevents further elements being sent to the channel
544 After closing a channel,
553 returns \-1 if the channel is empty.
559 that failed because the channel was closed.
564 entry points to an error string stating that the
565 channel was closed and the operation was completed
567 If all entries have been selected and failed because
571 .SS Errors, notes and resources
572 Thread library functions do not return on failure;
573 if errors occur, the entire program is aborted.
576 returns \-1 if no one called
578 on the channel, and otherwise
579 the number of elements still in the channel.
581 Threaded programs should use
592 in threaded programs.
594 will print the error string and call
601 to manage the namespace, file descriptors, note group, and environment of a
603 That is, it is safe to call
613 (To create new processes, use
618 the thread library depends on all procs being in the
619 same rendezvous group; do not change the rendezvous
623 .TF /sys/lib/acid/thread
625 .B /sys/lib/acid/thread
628 functions for debugging threaded programs.
630 .B /sys/src/libthread/example.c
631 a full example program.
638 .B /sys/src/libthread