Blob


1 .TH THREAD 3
2 .SH NAME
3 alt,
4 chancreate,
5 chanfree,
6 chaninit,
7 chanprint,
8 chansetname,
9 mainstacksize,
10 proccreate,
11 procdata,
12 recv,
13 recvp,
14 recvul,
15 send,
16 sendp,
17 sendul,
18 nbrecv,
19 nbrecvp,
20 nbrecvul,
21 nbsend,
22 nbsendp,
23 nbsendul,
24 threadcreate,
25 threaddata,
26 threadexec,
27 threadexecl,
28 threadexits,
29 threadexitsall,
30 threadgetgrp,
31 threadgetname,
32 threadint,
33 threadintgrp,
34 threadkill,
35 threadkillgrp,
36 threadmain,
37 threadnotify,
38 threadid,
39 threadpid,
40 threadsetgrp,
41 threadsetname,
42 threadsetstate,
43 threadspawn,
44 threadspawnl,
45 threadwaitchan,
46 yield \- thread and proc management
47 .SH SYNOPSIS
48 .PP
49 .EX
50 .ta 4n +4n +4n +4n +4n +4n +4n
51 #include <u.h>
52 #include <libc.h>
53 #include <thread.h>
54 .sp
55 #define CHANEND 0
56 #define CHANSND 1
57 #define CHANRCV 2
58 #define CHANNOP 3
59 #define CHANNOBLK 4
60 .sp
61 .ta \w' 'u +\w'Channel 'u
62 typedef struct Alt Alt;
63 struct Alt {
64 Channel *c;
65 void *v;
66 int op;
67 Channel **tag;
68 int entryno;
69 char *name;
70 };
71 .fi
72 .de XX
73 .if t .sp 0.5
74 .if n .sp
75 ..
76 .PP
77 .nf
78 .ft L
79 .ta \w'\fLChannel* 'u +4n +4n +4n +4n
80 void threadmain(int argc, char *argv[])
81 int mainstacksize
82 int proccreate(void (*fn)(void*), void *arg, uint stacksize)
83 int threadcreate(void (*fn)(void*), void *arg, uint stacksize)
84 void threadexits(char *status)
85 void threadexitsall(char *status)
86 void yield(void)
87 .XX
88 int threadid(void)
89 int threadgrp(void)
90 int threadsetgrp(int group)
91 int threadpid(int id)
92 .XX
93 int threadint(int id)
94 int threadintgrp(int group)
95 int threadkill(int id)
96 int threadkillgrp(int group)
97 .XX
98 void threadsetname(char *name)
99 char* threadgetname(void)
100 .XX
101 void** threaddata(void)
102 void** procdata(void)
103 .XX
104 int chaninit(Channel *c, int elsize, int nel)
105 Channel* chancreate(int elsize, int nel)
106 void chanfree(Channel *c)
107 .XX
108 int alt(Alt *alts)
109 int recv(Channel *c, void *v)
110 void* recvp(Channel *c)
111 ulong recvul(Channel *c)
112 int nbrecv(Channel *c, void *v)
113 void* nbrecvp(Channel *c)
114 ulong nbrecvul(Channel *c)
115 int send(Channel *c, void *v)
116 int sendp(Channel *c, void *v)
117 int sendul(Channel *c, ulong v)
118 int nbsend(Channel *c, void *v)
119 int nbsendp(Channel *c, void *v)
120 int nbsendul(Channel *c, ulong v)
121 int chanprint(Channel *c, char *fmt, ...)
122 .XX
123 int threadspawnl(int fd[3], char *file, ...)
124 int threadspawn(int fd[3], char *file, char *args[])
125 int threadexecl(Channel *cpid, int fd[3], char *file, ...)
126 int threadexec(Channel *cpid, int fd[3], char *file, char *args[])
127 Channel* threadwaitchan(void)
128 .XX
129 int threadnotify(int (*f)(void*, char*), int in)
130 .EE
131 .SH DESCRIPTION
132 .PP
133 The thread library provides parallel programming support similar to that
134 of the languages
135 Alef and Newsqueak.
136 Threads
137 and
138 procs
139 occupy a shared address space,
140 communicating and synchronizing through
141 .I channels
142 and shared variables.
143 .PP
145 .I proc
146 is a Plan 9 process that contains one or more cooperatively scheduled
147 .IR threads .
148 Programs using threads must replace
149 .I main
150 by
151 .IR threadmain .
152 The thread library provides a
153 .I main
154 function that sets up a proc with a single thread executing
155 .I threadmain
156 on a stack of size
157 .I mainstacksize
158 (default eight kilobytes).
159 To set
160 .IR mainstacksize ,
161 declare a global variable
162 initialized to the desired value
163 .RI ( e.g. ,
164 .B int
165 .B mainstacksize
166 .B =
167 .BR 1024 ).
168 .PP
169 .I Threadcreate
170 creates a new thread in the calling proc, returning a unique integer
171 identifying the thread; the thread
172 executes
173 .I fn(arg)
174 on a stack of size
175 .IR stacksize .
176 Thread stacks are allocated in shared memory, making it valid to pass
177 pointers to stack variables between threads and procs.
178 .I Proccreate
179 creates a new proc, and inside that proc creates
180 a single thread as
181 .I threadcreate
182 would,
183 returning the id of the created thread.
184 .\" .I Procrfork
185 .\" creates the new proc by calling
186 .\" .B rfork
187 .\" (see
188 .\" .IR fork (3))
189 .\" with flags
190 .\" .BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR.
191 .\" (The thread library depends on all its procs
192 .\" running in the same rendezvous group.
193 .\" Do not include
194 .\" .B RFREND
195 .\" in
196 .\" .IR rforkflag .)
197 .\" .I Proccreate
198 .\" is identical to
199 .\" .I procrfork
200 .\" with
201 .\" .I rforkflag
202 .\" set to zero.
203 Be aware that the calling thread may continue
204 execution before
205 the newly created proc and thread
206 are scheduled.
207 Because of this,
208 .I arg
209 should not point to data on the stack of a function that could
210 return before the new process is scheduled.
211 .PP
212 .I Threadexits
213 terminates the calling thread.
214 If the thread is the last in its proc,
215 .I threadexits
216 also terminates the proc, using
217 .I status
218 as the exit status.
219 .I Threadexitsall
220 terminates all procs in the program,
221 using
222 .I status
223 as the exit status.
224 .PP
225 When the last thread in
226 .IR threadmain 's
227 proc exits, the program will appear to its parent to have exited.
228 The remaining procs will still run together, but as a background program.
229 .PP
230 The threads in a proc are coroutines, scheduled nonpreemptively
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
235 .IR yield ,
236 .IR proccreate ,
237 .IR threadexec ,
238 .IR threadexecl ,
239 .IR threadexits ,
240 .IR threadspawn ,
241 .IR alt ,
242 .IR send ,
243 and
244 .I recv
245 (and the calls related to
246 .I send
247 and
248 .IR recv \(emsee
249 their descriptions further on).
250 Procs are scheduled by the operating system.
251 Therefore, threads in different procs can preempt one another
252 in arbitrary ways and should synchronize their
253 actions using
254 .B qlocks
255 (see
256 .IR lock (3))
257 or channel communication.
258 System calls such as
259 .IR read (3)
260 block the entire proc;
261 all threads in a proc block until the system call finishes.
262 .PP
263 As mentioned above, each thread has a unique integer thread id.
264 Thread ids are not reused; they are unique across the life of the program.
265 .I Threadid
266 returns the id for the current thread.
267 Each thread also has a thread group id.
268 The initial thread has a group id of zero.
269 Each new thread inherits the group id of
270 the thread that created it.
271 .I Threadgrp
272 returns the group id for the current thread;
273 .I threadsetgrp
274 sets it.
275 .I Threadpid
276 returns the pid of the Plan 9 process containing
277 the thread identified by
278 .IR id ,
279 or \-1
280 if no such thread is found.
281 .PP
282 .I Threadint
283 interrupts a thread that is blocked in a channel operation
284 or system call.
285 .I Threadintgrp
286 interrupts all threads with the given group id.
287 .I Threadkill
288 marks a thread to die when it next relinquishes the processor
289 (via one of the calls listed above).
290 If the thread is blocked in a channel operation or system call,
291 it is also interrupted.
292 .I Threadkillgrp
293 kills all threads with the given group id.
294 Note that
295 .I threadkill
296 and
297 .I threadkillgrp
298 will not terminate a thread that never relinquishes
299 the processor.
300 .PP
301 Primarily for debugging,
302 threads can have string names associated with them.
303 .I Threadgetname
304 returns the current thread's name;
305 .I threadsetname
306 sets it.
307 The pointer returned by
308 .I threadgetname
309 is only valid until the next call to
310 .IR threadsetname .
311 .PP
312 Also for debugging,
313 threads have a string state associated with them.
314 .I Threadsetstate
315 sets the state string.
316 There is no
317 .IR threadgetstate ;
318 since the thread scheduler resets the state to
319 .B Running
320 every time it runs the thread,
321 it is only useful for debuggers to inspect the state.
322 .PP
323 .I Threaddata
324 returns a pointer to a per-thread pointer
325 that may be modified by threaded programs for
326 per-thread storage.
327 Similarly,
328 .I procdata
329 returns a pointer to a per-proc pointer.
330 .PP
331 .I Threadexecl
332 and
333 .I threadexec
334 are threaded analogues of
335 .I exec
336 and
337 .I execl
338 (see
339 .IR exec (3));
340 on success,
341 they replace the calling thread
342 and invoke the external program, never returning.
343 (Unlike on Plan 9, the calling thread need not be the only thread in its proc\(emthe other
344 threads will continue executing.)
345 On error, they return \-1.
346 If
347 .I cpid
348 is not null, the pid of the invoked program
349 will be sent along
350 .I cpid
351 (using
352 .IR sendul )
353 once the program has been started, or \-1 will be sent if an
354 error occurs.
355 .I Threadexec
356 and
357 .I threadexecl
358 will not access their arguments after sending a result
359 along
360 .IR cpid .
361 Thus, programs that malloc the
362 .I argv
363 passed to
364 .I threadexec
365 can safely free it once they have
366 received the
367 .I cpid
368 response.
369 .PP
370 .I Threadexecl
371 and
372 .I threadexec
373 will duplicate
374 (see
375 .IR dup (3))
376 the three file descriptors in
377 .I fd
378 onto standard input, output, and error for the external program
379 and then close them in the calling thread.
380 Beware of code that sets
381 .IP
382 .EX
383 fd[0] = 0;
384 fd[1] = 1;
385 fd[2] = 2;
386 .EE
387 .LP
388 to use the current standard files. The correct code is
389 .IP
390 .EX
391 fd[0] = dup(0, -1);
392 fd[1] = dup(1, -1);
393 fd[2] = dup(2, -1);
394 .EE
395 .PP
396 .I Threadspawnl
397 and
398 .I threadspawn
399 are like
400 .I threadexecl
401 and
402 .I threadexec
403 but do not replace the current thread.
404 They return the pid of the invoked program on success, or
405 \-1 on error.
406 .PP
407 .I Threadwaitchan
408 returns a channel of pointers to
409 .B Waitmsg
410 structures (see
411 .IR wait (3)).
412 When an exec'ed process exits, a pointer to a
413 .B Waitmsg
414 is sent to this channel.
415 These
416 .B Waitmsg
417 structures have been allocated with
418 .IR malloc (3)
419 and should be freed after use.
420 .PP
422 .B Channel
423 is a buffered or unbuffered queue for fixed-size messages.
424 Procs and threads
425 .I send
426 messages into the channel and
427 .I recv
428 messages from the channel. If the channel is unbuffered, a
429 .I send
430 operation blocks until the corresponding
431 .I recv
432 operation occurs and
433 .IR "vice versa" .
434 .I Chaninit
435 initializes a
436 .B Channel
437 for messages of size
438 .I elsize
439 and with a buffer holding
440 .I nel
441 messages.
442 If
443 .I nel
444 is zero, the channel is unbuffered.
445 .IR Chancreate
446 allocates a new channel and initializes it.
447 .I Chanfree
448 frees a channel that is no longer used.
449 .I Chanfree
450 can be called by either sender or receiver after the last item has been
451 sent or received. Freeing the channel will be delayed if there is a thread
452 blocked on it until that thread unblocks (but
453 .I chanfree
454 returns immediately).
455 .PP
456 The
457 .B name
458 element in the
459 .B Channel
460 structure is a description intended for use in debugging.
461 .I Chansetname
462 sets the name.
463 .PP
464 .I Send
465 sends the element pointed at by
466 .I v
467 to the channel
468 .IR c .
469 If
470 .I v
471 is null, zeros are sent.
472 .I Recv
473 receives an element from
474 .I c
475 and stores it in
476 .IR v .
477 If
478 .I v
479 is null,
480 the received value is discarded.
481 .I Send
482 and
483 .I recv
484 return 1 on success, \-1 if interrupted.
485 .I Nbsend
486 and
487 .I nbrecv
488 behave similarly, but return 0 rather than blocking.
489 .PP
490 .IR Sendp ,
491 .IR nbsendp ,
492 .IR sendul ,
493 and
494 .I nbsendul
495 send a pointer or an unsigned long; the channel must
496 have been initialized with the appropriate
497 .IR elsize .
498 .IR Recvp ,
499 .IR nbrecvp ,
500 .IR recvul ,
501 and
502 .I nbrecvul
503 receive a pointer or an unsigned long;
504 they return zero when a zero is received,
505 when interrupted, or
506 (for
507 .I nbrecvp
508 and
509 .IR nbrecvul )
510 when the operation would have blocked.
511 To distinguish between these three cases,
512 use
513 .I recv
514 or
515 .IR nbrecv .
516 .PP
517 .I Alt
518 can be used to recv from or send to one of a number of channels,
519 as directed by an array of
520 .B Alt
521 structures,
522 each of which describes a potential send or receive operation.
523 In an
524 .B Alt
525 structure,
526 .B c
527 is the channel;
528 .B v
529 the value pointer (which may be null); and
530 .B op
531 the operation:
532 .B CHANSND
533 for a send operation,
534 .B CHANRECV
535 for a recv operation;
536 .B CHANNOP
537 for no operation
538 (useful
539 when
540 .I alt
541 is called with a varying set of operations).
542 The array of
543 .B Alt
544 structures is terminated by an entry with
545 .I op
546 .B CHANEND
547 or
548 .BR CHANNOBLK .
549 If at least one
550 .B Alt
551 structure can proceed, one of them is
552 chosen at random to be executed.
553 .I Alt
554 returns the index of the chosen structure.
555 If no operations can proceed and the list is terminated with
556 .BR CHANNOBLK ,
557 .I alt
558 returns the index of the terminating
559 .B CHANNOBLK
560 structure.
561 Otherwise,
562 .I alt
563 blocks until one of the operations can proceed,
564 eventually returning the index of the structure executes.
565 .I Alt
566 returns \-1 when interrupted.
567 The
568 .B tag
569 and
570 .B entryno
571 fields in the
572 .B Alt
573 structure are used internally by
574 .I alt
575 and need not be initialized.
576 They are not used between
577 .I alt
578 calls.
579 .PP
580 .I Chanprint
581 formats its arguments in the manner of
582 .IR print (3)
583 and sends the result to the channel
584 .IR c.
585 The string delivered by
586 .I chanprint
587 is allocated with
588 .IR malloc (3)
589 and should be freed upon receipt.
590 .PP
591 Thread library functions do not return on failure;
592 if errors occur, the entire program is aborted.
593 .PP
594 Threaded programs should use
595 .I threadnotify
596 in place of
597 .I atnotify
598 (see
599 .IR notify (3)).
600 .PP
601 It is safe to use
602 .IR sysfatal (3)
603 in threaded programs.
604 .I Sysfatal
605 will print the error string and call
606 .IR threadexitsall .
607 .PP
608 It is not safe to call
609 .IR rfork
610 in a threaded program, except to call
611 .B rfork(RFNOTEG)
612 from the main proc before any other procs have been created.
613 To create new processes, use
614 .IR proccreate .
615 .\" .PP
616 .\" It is safe to use
617 .\" .IR rfork
618 .\" (see
619 .\" .IR fork (3))
620 .\" to manage the namespace, file descriptors, note group, and environment of a
621 .\" single process.
622 .\" That is, it is safe to call
623 .\" .I rfork
624 .\" with the flags
625 .\" .BR RFNAMEG ,
626 .\" .BR RFFDG ,
627 .\" .BR RFCFDG ,
628 .\" .BR RFNOTEG ,
629 .\" .BR RFENVG ,
630 .\" and
631 .\" .BR RFCENVG.
632 .\" (To create new processes, use
633 .\" .I proccreate
634 .\" and
635 .\" .IR procrfork .)
636 .\" As mentioned above,
637 .\" the thread library depends on all procs being in the
638 .\" same rendezvous group; do not change the rendezvous
639 .\" group with
640 .\" .IR rfork .
641 .SH FILES
642 .B \*9/acid/thread
643 contains useful
644 .IR acid (1)
645 functions for debugging threaded programs.
646 .PP
647 .B \*9/src/libthread/test
648 contains some example programs.
649 .SH SOURCE
650 .B \*9/src/libthread
651 .SH SEE ALSO
652 .IR intro (3),
653 .IR ioproc (3)
654 .SH BUGS
655 To avoid name conflicts,
656 .IR alt ,
657 .IR nbrecv ,
658 .IR nbrecvp ,
659 .IR nbrecvul ,
660 .IR nbsend ,
661 .IR nbsendp ,
662 .IR nbsendul ,
663 .IR recv ,
664 .IR recvp ,
665 .IR recvul ,
666 .IR send ,
667 .IR sendp ,
668 and
669 .IR sendul
670 are defined as macros that expand to
671 .IR chanalt ,
672 .IR channbrecv ,
673 and so on.
674 .I Yield
675 is defined as a macro that expands to
676 .IR threadyield .
677 See
678 .IR intro (3).
679 .PP
680 The implementation of
681 .I threadnotify
682 may not be correct.
683 .PP
684 There appears to be a race in the Linux NPTL
685 implementation of
686 .I pthread_exit .
687 Call
688 .I threadexitsall
689 rather than coordinating a simultaneous
690 .I threadexits
691 among many threads.