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 Note that the mount point
 360 .B /mnt/temp
 361 must exist;
 362 .I procexec(l)
 363 mount pipes there.
 364 .PP
 365 .I Threadwaitchan
 366 returns a channel of pointers to
 367 .B Waitmsg
 368 structures (see
 369 .IR wait (2)).
 370 When an exec'ed process exits, a pointer to a
 371 .B Waitmsg
 372 is sent to this channel.
 373 These
 374 .B Waitmsg
 375 structures have been allocated with
 376 .IR malloc (2)
 377 and should be freed after use.
 378 .SS Channels
 379 A
 380 .B Channel
 381 is a buffered or unbuffered queue for fixed-size messages.
 382 Procs and threads
 383 .I send
 384 messages into the channel and
 385 .I recv
 386 messages from the channel.  If the channel is unbuffered, a
 387 .I send
 388 operation blocks until the corresponding
 389 .I recv
 390 operation occurs and
 391 .IR "vice versa" .
 392 .I Chaninit
 393 initializes a
 394 .B Channel
 395 for messages of size
 396 .I elsize
 397 and with a buffer holding
 398 .I nel
 399 messages.
 400 If
 401 .I nel
 402 is zero, the channel is unbuffered.
 403 .IR Chancreate
 404 allocates a new channel and initializes it.
 405 .I Chanfree
 406 frees a channel that is no longer used.
 407 .I Chanfree
 408 can be called by either sender or receiver after the last item has been
 409 sent or received.  Freeing the channel will be delayed if there is a thread
 410 blocked on it until that thread unblocks (but
 411 .I chanfree
 412 returns immediately).
 413 .PP
 414 .I Send
 415 sends the element pointed at by
 416 .I v
 417 to the channel
 418 .IR c .
 419 If
 420 .I v
 421 is null, zeros are sent.
 422 .I Recv
 423 receives an element from
 424 .I c
 425 and stores it in
 426 .IR v .
 427 If
 428 .I v
 429 is null,
 430 the received value is discarded.
 431 .I Send
 432 and
 433 .I recv
 434 return 1 on success, \-1 if interrupted.
 435 .I Nbsend
 436 and
 437 .I nbrecv
 438 behave similarly, but return 0 rather than blocking.
 439 .PP
 440 .IR Sendp ,
 441 .IR nbsendp ,
 442 .IR sendul ,
 443 and
 444 .I nbsendul
 445 send a pointer or an unsigned long; the channel must
 446 have been initialized with the appropriate
 447 .IR elsize .
 448 .IR Recvp ,
 449 .IR nbrecvp ,
 450 .IR recvul ,
 451 and
 452 .I nbrecvul
 453 receive a pointer or an unsigned long;
 454 they return zero when a zero is received,
 455 when interrupted, or
 456 (for
 457 .I nbrecvp
 458 and
 459 .IR nbrecvul )
 460 when the operation would have blocked.
 461 To distinguish between these three cases,
 462 use
 463 .I recv
 464 or
 465 .IR nbrecv .
 466 .PP
 467 .I Alt
 468 can be used to recv from or send to one of a number of channels,
 469 as directed by an array of
 470 .B Alt
 471 structures,
 472 each of which describes a potential send or receive operation.
 473 In an
 474 .B Alt
 475 structure,
 476 .B c
 477 is the channel;
 478 .B v
 479 the value pointer (which may be null); and
 480 .B op
 481 the operation:
 482 .B CHANSND
 483 for a send operation,
 484 .B CHANRCV
 485 for a recv operation;
 486 .B CHANNOP
 487 for no operation
 488 (useful
 489 when
 490 .I alt
 491 is called with a varying set of operations).
 492 The array of
 493 .B Alt
 494 structures is terminated by an entry with
 495 .I op
 496 .B CHANEND
 497 or
 498 .BR CHANNOBLK .
 499 If at least one
 500 .B Alt
 501 structure can proceed, one of them is
 502 chosen at random to be executed.
 503 .I Alt
 504 returns the index of the chosen structure.
 505 If no operations can proceed and the list is terminated with
 506 .BR CHANNOBLK ,
 507 .I alt
 508 returns the index of the terminating
 509 .B CHANNOBLK
 510 structure.
 511 Otherwise,
 512 .I alt
 513 blocks until one of the operations can proceed,
 514 eventually returning the index of the structure executes.
 515 .I Alt
 516 returns \-1 when interrupted.
 517 The
 518 .B tag
 519 and
 520 .B entryno
 521 fields in the
 522 .B Alt
 523 structure are used internally by
 524 .I alt
 525 and need not be initialized.
 526 They are not used between
 527 .I alt
 528 calls.
 529 .PP
 530 .I Chanprint
 531 formats its arguments in the manner of
 532 .IR print (2)
 533 and sends the result to the channel
 534 .IR c .
 535 The string delivered by
 536 .I chanprint
 537 is allocated with
 538 .IR malloc (2)
 539 and should be freed upon receipt.
 540 .PP
 541 .I Chanclose
 542 prevents further elements being sent to the channel
 543 .IR c .
 544 After closing a channel,
 545 .I send
 546 and
 547 .I recv
 548 never block.
 549 .I Send
 550 always
 551 returns \-1.
 552 .I Recv
 553 returns \-1 if the channel is empty.
 554 .I Alt
 555 may choose a
 556 .B CHANSND
 557 or
 558 .B CHANRCV
 559 that failed because the channel was closed.
 560 In this case, the
 561 .B err
 562 field of the
 563 .B Alt
 564 entry points to an error string stating that the
 565 channel was closed and the operation was completed
 566 with failure.
 567 If all entries have been selected and failed because
 568 they were closed,
 569 .I alt
 570 returns \-1.
 571 .SS Errors, notes and resources
 572 Thread library functions do not return on failure;
 573 if errors occur, the entire program is aborted.
 574 .PP
 575 .I Chanclosing
 576 returns \-1 if no one called
 577 .I closed
 578 on the channel, and otherwise
 579 the number of elements still in the channel.
 580 .PP
 581 Threaded programs should use
 582 .I threadnotify
 583 in place of
 584 .I atnotify
 585 (see
 586 .IR notify (2)).
 587 .PP
 588 It is safe to use
 589 .B sysfatal
 590 (see
 591 .IR perror (2))
 592 in threaded programs.
 593 .I Sysfatal
 594 will print the error string and call
 595 .IR threadexitsall .
 596 .PP
 597 It is safe to use
 598 .IR rfork
 599 (see
 600 .IR fork (2))
 601 to manage the namespace, file descriptors, note group, and environment of a
 602 single process.
 603 That is, it is safe to call
 604 .I rfork
 605 with the flags
 606 .BR RFNAMEG ,
 607 .BR RFFDG ,
 608 .BR RFCFDG ,
 609 .BR RFNOTEG ,
 610 .BR RFENVG ,
 611 and
 612 .BR RFCENVG.
 613 (To create new processes, use
 614 .I proccreate
 615 and
 616 .IR procrfork .)
 617 As mentioned above,
 618 the thread library depends on all procs being in the
 619 same rendezvous group; do not change the rendezvous
 620 group with
 621 .IR rfork .
 622 .SH FILES
 623 .TF /sys/lib/acid/thread
 624 .TP
 625 .B /sys/lib/acid/thread
 626 useful
 627 .IR acid (1)
 628 functions for debugging threaded programs.
 629 .TP
 630 .B /sys/src/libthread/example.c
 631 a full example program.
 632 .TP
 633 .B /mnt/temp
 634 a place for
 635 .I procexec
 636 to create pipes.
 637 .SH SOURCE
 638 .B /sys/src/libthread
 639 .SH SEE ALSO
 640 .IR intro (2),
 641 .IR ioproc (2),
 642 .IR lock (2)