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