thread.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.