44 yield \- thread and proc management
47 .ta 4n +4n +4n +4n +4n +4n +4n
60 .ta \w' 'u +\w'Channel 'u
61 typedef struct Alt Alt;
63 Channel *c; /* channel */
64 void *v; /* pointer to value */
65 ChanOp op; /* operation */
66 char *err; /* did the op fail? */
68 * the next variables are used internally to alt
69 * they need not be initialized
71 Channel **tag; /* pointer to rendez-vous tag */
72 int entryno; /* entry number */
82 .ta \w'\fLChannel* 'u +4n +4n +4n +4n
83 void threadmain(int argc, char *argv[])
85 int proccreate(void (*fn)(void*), void *arg, uint stacksize)
86 int procrfork(void (*fn)(void*), void *arg, uint stacksize,
88 int threadcreate(void (*fn)(void*), void *arg, uint stacksize)
89 void threadexits(char *status)
90 void threadexitsall(char *status)
94 int threadgetgrp(void)
95 int threadsetgrp(int group)
98 void threadint(int id)
99 void threadintgrp(int group)
100 void threadkill(int id)
101 void threadkillgrp(int group)
103 void threadsetname(char *name, ...)
104 char* threadgetname(void)
106 void** threaddata(void)
107 void** procdata(void)
109 Channel* chancreate(int elsize, int nel)
110 void chanfree(Channel *c)
113 int recv(Channel *c, void *v)
114 void* recvp(Channel *c)
115 ulong recvul(Channel *c)
116 int nbrecv(Channel *c, void *v)
117 void* nbrecvp(Channel *c)
118 ulong nbrecvul(Channel *c)
119 int send(Channel *c, void *v)
120 int sendp(Channel *c, void *v)
121 int sendul(Channel *c, ulong v)
122 int nbsend(Channel *c, void *v)
123 int nbsendp(Channel *c, void *v)
124 int nbsendul(Channel *c, ulong v)
125 int chanprint(Channel *c, char *fmt, ...)
126 int chanclose(Channel *c);
127 int chanclosing(Channel *c);
129 void procexecl(Channel *cpid, char *file, ...)
130 void procexec(Channel *cpid, char *file, char *args[])
131 Channel* threadwaitchan(void)
133 int threadnotify(int (*f)(void*, char*), int in)
136 The thread library provides parallel programming support similar to that
142 occupy a shared address space,
143 communicating and synchronizing through
145 and shared variables.
149 is a Plan 9 process that contains one or more cooperatively-scheduled
151 Programs using threads must replace
155 The thread library provides a
157 function that sets up a proc with a single thread executing
161 (default eight kilobytes).
164 declare a global variable
165 initialized to the desired value
173 creates a new thread in the calling proc, returning a unique integer
174 identifying the thread; the thread
179 Thread stacks are allocated in shared memory, making it valid to pass
180 pointers to stack variables between threads and procs.
182 creates a new proc, and inside that proc creates
186 returning the id of the created thread.
188 creates the new proc by calling
193 .BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR.
194 (The thread library depends on all its procs
195 running in the same rendezvous group.
206 Be aware that the calling thread may continue
208 the newly created proc and thread
212 should not point to data on the stack of a function that could
213 return before the new process is scheduled.
216 terminates the calling thread.
217 If the thread is the last in its proc,
219 also terminates the proc, using
223 terminates all procs in the program,
228 The threads in a proc are coroutines, scheduled non-preemptively
229 in a round-robin fashion.
230 A thread must explicitly relinquish control of the processor
231 before another thread in the same proc is run.
232 Calls that do this are
242 (and the calls related to
246 their descriptions further on),
253 Procs are scheduled by the operating system.
254 Therefore, threads in different procs can preempt one another
255 in arbitrary ways and should synchronize their
260 or channel communication.
263 block the entire proc;
264 all threads in a proc block until the system call finishes.
266 As mentioned above, each thread has a unique integer thread id.
267 Thread ids are not reused; they are unique across the life of the program.
269 returns the id for the current thread.
270 Each thread also has a thread group id.
271 The initial thread has a group id of zero.
272 Each new thread inherits the group id of
273 the thread that created it.
275 returns the group id for the current thread;
279 returns the pid of the Plan 9 process containing
280 the thread identified by
283 if no such thread is found.
286 interrupts a thread that is blocked in a channel operation
289 interrupts all threads with the given group id.
291 marks a thread to die when it next relinquishes the processor
292 (via one of the calls listed above).
293 If the thread is blocked in a channel operation or system call,
294 it is also interrupted.
296 kills all threads with the given group id.
301 will not terminate a thread that never relinquishes
303 .SS Names and per-thread data
304 Primarily for debugging,
305 threads can have string names associated with them.
307 returns the current thread's name;
310 The pointer returned by
312 is only valid until the next call to
316 returns a pointer to a per-thread pointer
317 that may be modified by threaded programs for
321 returns a pointer to a per-proc pointer.
322 .SS Executing new programs
326 are threaded analogues of
333 they replace the calling thread (which must be the only thread in its proc)
334 and invoke the external program, never returning.
335 On error, they return \-1.
338 is not null, the pid of the invoked program
341 once the program has been started, or \-1 will be sent if an
346 will not access their arguments after sending a result
349 Thus, programs that malloc the
353 can safely free it once they have
359 returns a channel of pointers to
363 When an exec'ed process exits, a pointer to a
365 is sent to this channel.
368 structures have been allocated with
370 and should be freed after use.
374 is a buffered or unbuffered queue for fixed-size messages.
377 messages into the channel and
379 messages from the channel. If the channel is unbuffered, a
381 operation blocks until the corresponding
386 allocates a new channel for messages of size
388 and with a buffer holding
393 is zero, the channel is unbuffered.
395 frees a channel that is no longer used.
397 can be called by either sender or receiver after the last item has been
398 sent or received. Freeing the channel will be delayed if there is a thread
399 blocked on it until that thread unblocks (but
401 returns immediately).
404 sends the element pointed at by
410 is null, zeros are sent.
412 receives an element from
419 the received value is discarded.
423 return 1 on success, \-1 if interrupted.
427 behave similarly, but return 0 rather than blocking.
434 send a pointer or an unsigned long; the channel must
435 have been initialized with the appropriate
442 receive a pointer or an unsigned long;
443 they return zero when a zero is received,
449 when the operation would have blocked.
450 To distinguish between these three cases,
457 can be used to recv from or send to one of a number of channels,
458 as directed by an array of
461 each of which describes a potential send or receive operation.
468 the value pointer (which may be null); and
472 for a send operation,
474 for a recv operation;
480 is called with a varying set of operations).
483 structures is terminated by an entry with
490 structure can proceed, one of them is
491 chosen at random to be executed.
493 returns the index of the chosen structure.
494 If no operations can proceed and the list is terminated with
497 returns the index of the terminating
502 blocks until one of the operations can proceed,
503 eventually returning the index of the structure executes.
505 returns \-1 when interrupted.
512 structure are used internally by
514 and need not be initialized.
515 They are not used between
520 formats its arguments in the manner of
522 and sends the result to the channel
524 The string delivered by
528 and should be freed upon receipt.
531 prevents further elements being sent to the channel
533 After closing a channel,
542 returns \-1 if the channel is empty.
548 that failed because the channel was closed.
553 entry points to an error string stating that the
554 channel was closed and the operation was completed
556 If all entries have been selected and failed because
560 .SS Errors, notes and resources
561 Thread library functions do not return on failure;
562 if errors occur, the entire program is aborted.
565 returns \-1 if no one called
567 on the channel, and otherwise
568 the number of elements still in the channel.
570 Threaded programs should use
581 in threaded programs.
583 will print the error string and call
590 to manage the namespace, file descriptors, note group, and environment of a
592 That is, it is safe to call
602 (To create new processes, use
607 the thread library depends on all procs being in the
608 same rendezvous group; do not change the rendezvous
612 .TF /sys/lib/acid/thread
614 .B /sys/lib/acid/thread
617 functions for debugging threaded programs.
619 .B /sys/src/libthread/example.c
620 a full example program.
622 .B /sys/src/libthread