thread 11 KB

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