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