sys/man/2/thread

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