sys/man/2/thread

   1 .TH THREAD 2
   2 .SH NAME
   3 alt,
   4 chanclose,
   5 chancreate,
   6 chanfree,
   7 chaninit,
   8 chanclosing,
   9 chanprint,
  10 mainstacksize,
  11 proccreate,
  12 procdata,
  13 procexec,
  14 procexecl,
  15 procrfork,
  16 recv,
  17 recvp,
  18 recvul,
  19 send,
  20 sendp,
  21 sendul,
  22 nbrecv,
  23 nbrecvp,
  24 nbrecvul,
  25 nbsend,
  26 nbsendp,
  27 nbsendul,
  28 threadcreate,
  29 threaddata,
  30 threadexits,
  31 threadexitsall,
  32 threadgetgrp,
  33 threadgetname,
  34 threadint,
  35 threadintgrp,
  36 threadkill,
  37 threadkillgrp,
  38 threadmain,
  39 threadnotify,
  40 threadid,
  41 threadpid,
  42 threadsetgrp,
  43 threadsetname,
  44 threadwaitchan,
  45 yield \- thread and proc management
  46 .SH SYNOPSIS
  47 .EX
  48 .ta 4n +4n +4n +4n +4n +4n +4n
  49 #include <u.h>
  50 #include <libc.h>
  51 #include <thread.h>
  52 .sp
  53 typedef enum {
  54         CHANEND,
  55         CHANSND,
  56         CHANRCV,
  57         CHANNOP,
  58         CHANNOBLK,
  59 } ChanOp;
  60 .sp
  61 .ta \w'    'u +\w'Channel 'u
  62 typedef struct Alt Alt;
  63 struct Alt {
  64         Channel *c;   /* channel */
  65         void    *v;   /* pointer to value */
  66         ChanOp  op;   /* operation */
  67         char    *err; /* did the op fail? */
  68         /*
  69          * the next variables are used internally to alt
  70          * they need not be initialized
  71          */
  72         Channel **tag;   /* pointer to rendez-vous tag */
  73         int     entryno; /* entry number */
  74 };
  75 .fi
  76 .de XX
  77 .ift .sp 0.5
  78 .ifn .sp
  79 ..
  80 .PP
  81 .nf
  82 .ft L
  83 .ta \w'\fLChannel* 'u +4n +4n +4n +4n
  84 void    threadmain(int argc, char *argv[])
  85 int     mainstacksize
  86 int     proccreate(void (*fn)(void*), void *arg, uint stacksize)
  87 int     procrfork(void (*fn)(void*), void *arg, uint stacksize,
  88                 int rforkflag)
  89 int     threadcreate(void (*fn)(void*), void *arg, uint stacksize)
  90 void    threadexits(char *status)
  91 void    threadexitsall(char *status)
  92 void    yield(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 void    threadintgrp(int group)
 101 void    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 int     chaninit(Channel *c, int elsize, int nel)
 111 Channel*        chancreate(int elsize, int nel)
 112 void    chanfree(Channel *c)
 113 .XX
 114 int     alt(Alt *alts)
 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);
 130 .XX
 131 void    procexecl(Channel *cpid, char *file, ...)
 132 void    procexec(Channel *cpid, 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 The thread library provides parallel programming support similar to that
 139 of the languages
 140 Alef and Newsqueak.
 141 .I Threads
 142 and
 143 .I procs
 144 occupy a shared address space,
 145 communicating and synchronizing through
 146 .I channels
 147 and shared variables.
 148 .PP
 149 A
 150 .I proc
 151 is a Plan 9 process that contains one or more cooperatively-scheduled
 152 .IR threads .
 153 Programs using threads must replace
 154 .I main
 155 by
 156 .IR threadmain .
 157 The thread library provides a
 158 .I main
 159 function that sets up a proc with a single thread executing
 160 .I threadmain
 161 on a stack of size
 162 .I mainstacksize
 163 (default eight kilobytes).
 164 To set
 165 .IR mainstacksize ,
 166 declare a global variable
 167 initialized to the desired value
 168 .RI ( e.g. ,
 169 .B int
 170 .B mainstacksize
 171 .B =
 172 .BR 1024 ).
 173 .SS Creation
 174 .I Threadcreate
 175 creates a new thread in the calling proc, returning a unique integer
 176 identifying the thread; the thread
 177 executes
 178 .I fn(arg)
 179 on a stack of size
 180 .IR stacksize .
 181 Thread stacks are allocated in shared memory, making it valid to pass
 182 pointers to stack variables between threads and procs.
 183 .I Procrfork
 184 creates a new proc, and inside that proc creates
 185 a single thread as
 186 .I threadcreate
 187 would,
 188 returning the id of the created thread.
 189 .I Procrfork
 190 creates the new proc by calling
 191 .B rfork
 192 (see
 193 .IR fork (2))
 194 with flags
 195 .BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR.
 196 (The thread library depends on all its procs
 197 running in the same rendezvous group.
 198 Do not include
 199 .B RFREND
 200 in
 201 .IR rforkflag .)
 202 .I Proccreate
 203 is identical to
 204 .I procrfork
 205 with
 206 .I rforkflag
 207 set to zero.
 208 Be aware that the calling thread may continue
 209 execution before
 210 the newly created proc and thread
 211 are scheduled.
 212 Because of this,
 213 .I arg
 214 should not point to data on the stack of a function that could
 215 return before the new process is scheduled.
 216 .PP
 217 .I Threadexits
 218 terminates the calling thread.
 219 If the thread is the last in its proc,
 220 .I threadexits
 221 also terminates the proc, using
 222 .I status
 223 as the exit status.
 224 .I Threadexitsall
 225 terminates all procs in the program,
 226 using
 227 .I status
 228 as the exit status.
 229 .SS Scheduling
 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
 235 .IR yield ,
 236 .IR proccreate ,
 237 .IR procexec ,
 238 .IR procexecl ,
 239 .IR threadexits ,
 240 .IR alt ,
 241 .IR send ,
 242 and
 243 .I recv
 244 (and the calls related to
 245 .I send
 246 and
 247 .IR recv \(emsee
 248 their descriptions further on),
 249 plus these from
 250 .IR lock (2):
 251 .IR qlock ,
 252 .IR rlock ,
 253 .IR wlock ,
 254 .IR rsleep .
 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
 258 actions using
 259 .B qlocks
 260 (see
 261 .IR lock (2))
 262 or channel communication.
 263 System calls such as
 264 .IR read (2)
 265 block the entire proc;
 266 all threads in a proc block until the system call finishes.
 267 .PP
 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.
 270 .I Threadid
 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.
 276 .I Threadgrp
 277 returns the group id for the current thread;
 278 .I threadsetgrp
 279 sets it.
 280 .I Threadpid
 281 returns the pid of the Plan 9 process containing
 282 the thread identified by
 283 .IR id ,
 284 or \-1
 285 if no such thread is found.
 286 .PP
 287 .I Threadint
 288 interrupts a thread that is blocked in a channel operation
 289 or system call.
 290 .I Threadintgrp
 291 interrupts all threads with the given group id.
 292 .I Threadkill
 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.
 297 .I Threadkillgrp
 298 kills all threads with the given group id.
 299 Note that
 300 .I threadkill
 301 and
 302 .I threadkillgrp
 303 will not terminate a thread that never relinquishes
 304 the processor.
 305 .SS Names and per-thread data
 306 Primarily for debugging,
 307 threads can have string names associated with them.
 308 .I Threadgetname
 309 returns the current thread's name;
 310 .I threadsetname
 311 sets it.
 312 The pointer returned by
 313 .I threadgetname
 314 is only valid until the next call to
 315 .IR threadsetname .
 316 .PP
 317 .I Threaddata
 318 returns a pointer to a per-thread pointer
 319 that may be modified by threaded programs for
 320 per-thread storage.
 321 Similarly,
 322 .I procdata
 323 returns a pointer to a per-proc pointer.
 324 .SS Executing new programs
 325 .I Procexecl
 326 and
 327 .I procexec
 328 are threaded analogues of
 329 .I exec
 330 and
 331 .I execl
 332 (see
 333 .IR exec (2));
 334 on success,
 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.
 338 If
 339 .I cpid
 340 is not null, the pid of the invoked program
 341 will be sent along
 342 .I cpid
 343 once the program has been started, or \-1 will be sent if an
 344 error occurs.
 345 .I Procexec
 346 and
 347 .I procexecl
 348 will not access their arguments after sending a result
 349 along
 350 .IR cpid .
 351 Thus, programs that malloc the
 352 .I argv
 353 passed to
 354 .I procexec
 355 can safely free it once they have
 356 received the
 357 .I cpid
 358 response.
 359 .PP
 360 .I Threadwaitchan
 361 returns a channel of pointers to
 362 .B Waitmsg
 363 structures (see
 364 .IR wait (2)).
 365 When an exec'ed process exits, a pointer to a
 366 .B Waitmsg
 367 is sent to this channel.
 368 These
 369 .B Waitmsg
 370 structures have been allocated with
 371 .IR malloc (2)
 372 and should be freed after use.
 373 .SS Channels
 374 A
 375 .B Channel
 376 is a buffered or unbuffered queue for fixed-size messages.
 377 Procs and threads
 378 .I send
 379 messages into the channel and
 380 .I recv
 381 messages from the channel.  If the channel is unbuffered, a
 382 .I send
 383 operation blocks until the corresponding
 384 .I recv
 385 operation occurs and
 386 .IR "vice versa" .
 387 .I Chaninit
 388 initializes a
 389 .B Channel
 390 for messages of size
 391 .I elsize
 392 and with a buffer holding
 393 .I nel
 394 messages.
 395 If
 396 .I nel
 397 is zero, the channel is unbuffered.
 398 .IR Chancreate
 399 allocates a new channel and initializes it.
 400 .I Chanfree
 401 frees a channel that is no longer used.
 402 .I Chanfree
 403 can be called by either sender or receiver after the last item has been
 404 sent or received.  Freeing the channel will be delayed if there is a thread
 405 blocked on it until that thread unblocks (but
 406 .I chanfree
 407 returns immediately).
 408 .PP
 409 .I Send
 410 sends the element pointed at by
 411 .I v
 412 to the channel
 413 .IR c .
 414 If
 415 .I v
 416 is null, zeros are sent.
 417 .I Recv
 418 receives an element from
 419 .I c
 420 and stores it in
 421 .IR v .
 422 If
 423 .I v
 424 is null,
 425 the received value is discarded.
 426 .I Send
 427 and
 428 .I recv
 429 return 1 on success, \-1 if interrupted.
 430 .I Nbsend
 431 and
 432 .I nbrecv
 433 behave similarly, but return 0 rather than blocking.
 434 .PP
 435 .IR Sendp ,
 436 .IR nbsendp ,
 437 .IR sendul ,
 438 and
 439 .I nbsendul
 440 send a pointer or an unsigned long; the channel must
 441 have been initialized with the appropriate
 442 .IR elsize .
 443 .IR Recvp ,
 444 .IR nbrecvp ,
 445 .IR recvul ,
 446 and
 447 .I nbrecvul
 448 receive a pointer or an unsigned long;
 449 they return zero when a zero is received,
 450 when interrupted, or
 451 (for
 452 .I nbrecvp
 453 and
 454 .IR nbrecvul )
 455 when the operation would have blocked.
 456 To distinguish between these three cases,
 457 use
 458 .I recv
 459 or
 460 .IR nbrecv .
 461 .PP
 462 .I Alt
 463 can be used to recv from or send to one of a number of channels,
 464 as directed by an array of
 465 .B Alt
 466 structures,
 467 each of which describes a potential send or receive operation.
 468 In an
 469 .B Alt
 470 structure,
 471 .B c
 472 is the channel;
 473 .B v
 474 the value pointer (which may be null); and
 475 .B op
 476 the operation:
 477 .B CHANSND
 478 for a send operation,
 479 .B CHANRCV
 480 for a recv operation;
 481 .B CHANNOP
 482 for no operation
 483 (useful
 484 when
 485 .I alt
 486 is called with a varying set of operations).
 487 The array of
 488 .B Alt
 489 structures is terminated by an entry with
 490 .I op
 491 .B CHANEND
 492 or
 493 .BR CHANNOBLK .
 494 If at least one
 495 .B Alt
 496 structure can proceed, one of them is
 497 chosen at random to be executed.
 498 .I Alt
 499 returns the index of the chosen structure.
 500 If no operations can proceed and the list is terminated with
 501 .BR CHANNOBLK ,
 502 .I alt
 503 returns the index of the terminating
 504 .B CHANNOBLK
 505 structure.
 506 Otherwise,
 507 .I alt
 508 blocks until one of the operations can proceed,
 509 eventually returning the index of the structure executes.
 510 .I Alt
 511 returns \-1 when interrupted.
 512 The
 513 .B tag
 514 and
 515 .B entryno
 516 fields in the
 517 .B Alt
 518 structure are used internally by
 519 .I alt
 520 and need not be initialized.
 521 They are not used between
 522 .I alt
 523 calls.
 524 .PP
 525 .I Chanprint
 526 formats its arguments in the manner of
 527 .IR print (2)
 528 and sends the result to the channel
 529 .IR c .
 530 The string delivered by
 531 .I chanprint
 532 is allocated with
 533 .IR malloc (2)
 534 and should be freed upon receipt.
 535 .PP
 536 .I Chanclose
 537 prevents further elements being sent to the channel
 538 .IR c .
 539 After closing a channel,
 540 .I send
 541 and
 542 .I recv
 543 never block.
 544 .I Send
 545 always
 546 returns \-1.
 547 .I Recv
 548 returns \-1 if the channel is empty.
 549 .I Alt
 550 may choose a
 551 .B CHANSND
 552 or
 553 .B CHANRCV
 554 that failed because the channel was closed.
 555 In this case, the
 556 .B err
 557 field of the
 558 .B Alt
 559 entry points to an error string stating that the
 560 channel was closed and the operation was completed
 561 with failure.
 562 If all entries have been selected and failed because
 563 they were closed,
 564 .I alt
 565 returns \-1.
 566 .SS Errors, notes and resources
 567 Thread library functions do not return on failure;
 568 if errors occur, the entire program is aborted.
 569 .PP
 570 .I Chanclosing
 571 returns \-1 if no one called
 572 .I closed
 573 on the channel, and otherwise
 574 the number of elements still in the channel.
 575 .PP
 576 Threaded programs should use
 577 .I threadnotify
 578 in place of
 579 .I atnotify
 580 (see
 581 .IR notify (2)).
 582 .PP
 583 It is safe to use
 584 .B sysfatal
 585 (see
 586 .IR perror (2))
 587 in threaded programs.
 588 .I Sysfatal
 589 will print the error string and call
 590 .IR threadexitsall .
 591 .PP
 592 It is safe to use
 593 .IR rfork
 594 (see
 595 .IR fork (2))
 596 to manage the namespace, file descriptors, note group, and environment of a
 597 single process.
 598 That is, it is safe to call
 599 .I rfork
 600 with the flags
 601 .BR RFNAMEG ,
 602 .BR RFFDG ,
 603 .BR RFCFDG ,
 604 .BR RFNOTEG ,
 605 .BR RFENVG ,
 606 and
 607 .BR RFCENVG.
 608 (To create new processes, use
 609 .I proccreate
 610 and
 611 .IR procrfork .)
 612 As mentioned above,
 613 the thread library depends on all procs being in the
 614 same rendezvous group; do not change the rendezvous
 615 group with
 616 .IR rfork .
 617 .SH FILES
 618 .TF /sys/lib/acid/thread
 619 .TP
 620 .B /sys/lib/acid/thread
 621 useful
 622 .IR acid (1)
 623 functions for debugging threaded programs.
 624 .TP
 625 .B /sys/src/libthread/example.c
 626 a full example program.
 627 .TP
 628 .B /mnt/temp
 629 a place for
 630 .I procexec
 631 to create pipes.
 632 .SH SOURCE
 633 .B /sys/src/libthread
 634 .SH SEE ALSO
 635 .IR intro (2),
 636 .IR ioproc (2),
 637 .IR lock (2)