diff options
Diffstat (limited to 'man/man3/thread.html')
| -rw-r--r-- | man/man3/thread.html | 383 |
1 files changed, 383 insertions, 0 deletions
diff --git a/man/man3/thread.html b/man/man3/thread.html new file mode 100644 index 00000000..b14d97e6 --- /dev/null +++ b/man/man3/thread.html @@ -0,0 +1,383 @@ +<head> +<title>thread(3) - Plan 9 from User Space</title> +<meta content="text/html; charset=utf-8" http-equiv=Content-Type> +</head> +<body bgcolor=#ffffff> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=10><td> +<tr><td width=20><td> +<tr><td width=20><td><b>THREAD(3)</b><td align=right><b>THREAD(3)</b> +<tr><td width=20><td colspan=2> + <br> +<p><font size=+1><b>NAME </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + alt, chancreate, chanfree, chaninit, chanprint, chansetname, mainstacksize, + proccreate, procdata, recv, recvp, recvul, send, sendp, sendul, + nbrecv, nbrecvp, nbrecvul, nbsend, nbsendp, nbsendul, threadcreate, + threaddata, threadexec, threadexecl, threadexits, threadexitsall, + threadgetgrp, threadgetname, threadint, + threadintgrp, threadkill, threadkillgrp, threadmain, threadnotify, + threadid, threadpid, threadsetgrp, threadsetname, threadsetstate, + threadspawn, threadwaitchan, yield – thread and proc management<br> + +</table> +<p><font size=+1><b>SYNOPSIS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>#include <u.h><br> + #include <libc.h><br> + #include <thread.h><br> + #define CHANEND 0<br> + #define CHANSND 1<br> + #define CHANRCV 2<br> + #define CHANNOP 3<br> + #define CHANNOBLK 4<br> + typedef struct Alt Alt;<br> + struct Alt {<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + Channel *c;<br> + void *v;<br> + int op;<br> + Channel **tag;<br> + int entryno;<br> + char *name;<br> + + </table> + };<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + void threadmain(int argc, char *argv[])<br> + int mainstacksize<br> + int proccreate(void (*fn)(void*), void *arg, uint stacksize)<br> + int threadcreate(void (*fn)(void*), void *arg, uint stacksize)<br> + void threadexits(char *status)<br> + void threadexitsall(char *status)<br> + void yield(void)<br> + int threadid(void)<br> + int threadgrp(void)<br> + int threadsetgrp(int group)<br> + int threadpid(int id)<br> + int threadint(int id)<br> + int threadintgrp(int group)<br> + int threadkill(int id)<br> + int threadkillgrp(int group)<br> + void threadsetname(char *name)<br> + char* threadgetname(void)<br> + void** threaddata(void)<br> + void** procdata(void)<br> + int chaninit(Channel *c, int elsize, int nel)<br> + Channel* chancreate(int elsize, int nel)<br> + void chanfree(Channel *c)<br> + int alt(Alt *alts)<br> + int recv(Channel *c, void *v)<br> + void* recvp(Channel *c)<br> + ulong recvul(Channel *c)<br> + int nbrecv(Channel *c, void *v)<br> + void* nbrecvp(Channel *c)<br> + ulong nbrecvul(Channel *c)<br> + int send(Channel *c, void *v)<br> + int sendp(Channel *c, void *v)<br> + int sendul(Channel *c, ulong v)<br> + int nbsend(Channel *c, void *v)<br> + int nbsendp(Channel *c, void *v)<br> + int nbsendul(Channel *c, ulong v)<br> + int chanprint(Channel *c, char *fmt, ...)<br> + int threadspawn(int fd[3], char *file, char *args[])<br> + int threadexecl(Channel *cpid, int fd[3], char *file, ...)<br> + int threadexec(Channel *cpid, int fd[3], char *file, char *args[])<br> + Channel* threadwaitchan(void)<br> + int threadnotify(int (*f)(void*, char*), int in)<br> + </font></tt> +</table> +<p><font size=+1><b>DESCRIPTION </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + The thread library provides parallel programming support similar + to that of the languages Alef and Newsqueak. Threads and procs + occupy a shared address space, communicating and synchronizing + through <i>channels</i> and shared variables. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + A <i>proc</i> is a Plan 9 process that contains one or more cooperatively + scheduled <i>threads</i>. Programs using threads must replace <i>main</i> by + <i>threadmain</i>. The thread library provides a <i>main</i> function that sets + up a proc with a single thread executing <i>threadmain</i> on a stack + of size <i>mainstacksize</i> (default eight kilobytes). To set + <i>mainstacksize</i>, declare a global variable initialized to the desired + value (<i>e.g.</i>, <tt><font size=+1>int mainstacksize = 1024</font></tt>). + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Threadcreate</i> creates a new thread in the calling proc, returning + a unique integer identifying the thread; the thread executes <i>fn(arg)</i> + on a stack of size <i>stacksize</i>. Thread stacks are allocated in shared + memory, making it valid to pass pointers to stack variables between + threads and procs. <i>Proccreate</i> creates a new proc, + and inside that proc creates a single thread as <i>threadcreate</i> would, + returning the id of the created thread. Be aware that the calling + thread may continue execution before the newly created proc and + thread are scheduled. Because of this, <i>arg</i> should not point to + data on the stack of a function that could return before the + new process is scheduled. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Threadexits</i> terminates the calling thread. If the thread is the + last in its proc, <i>threadexits</i> also terminates the proc, using + <i>status</i> as the exit status. <i>Threadexitsall</i> terminates all procs + in the program, using <i>status</i> as the exit status. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + When the last thread in <i>threadmain</i>’s proc exits, the program will + appear to its parent to have exited. The remaining procs will + still run together, but as a background program. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + The threads in a proc are coroutines, scheduled nonpreemptively + in a round-robin fashion. A thread must explicitly relinquish + control of the processor before another thread in the same proc + is run. Calls that do this are <i>yield</i>, <i>proccreate</i>, <i>threadexec</i>, + <i>threadexecl</i>, <i>threadexits</i>, <i>threadspawn</i>, <i>alt</i>, <i>send</i>, and <i>recv</i> (and + the + calls related to <i>send</i> and <i>recv</i>--see their descriptions further on). + Procs are scheduled by the operating system. Therefore, threads + in different procs can preempt one another in arbitrary ways and + should synchronize their actions using <tt><font size=+1>qlocks</font></tt> (see <a href="../man3/lock.html"><i>lock</i>(3)</a>) or + channel communication. System calls such as <a href="../man3/read.html"><i>read</i>(3)</a> + block the entire proc; all threads in a proc block until the system + call finishes. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + As mentioned above, each thread has a unique integer thread id. + Thread ids are not reused; they are unique across the life of + the program. <i>Threadid</i> returns the id for the current thread. Each + thread also has a thread group id. The initial thread has a group + id of zero. Each new thread inherits the group id of the + thread that created it. <i>Threadgrp</i> returns the group id for the + current thread; <i>threadsetgrp</i> sets it. <i>Threadpid</i> returns the pid + of the Plan 9 process containing the thread identified by <i>id</i>, + or –1 if no such thread is found. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Threadint</i> interrupts a thread that is blocked in a channel operation + or system call. <i>Threadintgrp</i> interrupts all threads with the given + group id. <i>Threadkill</i> marks a thread to die when it next relinquishes + the processor (via one of the calls listed above). If the thread + is blocked in a channel operation or system call, it is + also interrupted. <i>Threadkillgrp</i> kills all threads with the given + group id. Note that <i>threadkill</i> and <i>threadkillgrp</i> will not terminate + a thread that never relinquishes the processor. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + Primarily for debugging, threads can have string names associated + with them. <i>Threadgetname</i> returns the current thread’s name; <i>threadsetname</i> + sets it. The pointer returned by <i>threadgetname</i> is only valid until + the next call to <i>threadsetname</i>. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + Also for debugging, threads have a string state associated with + them. <i>Threadsetstate</i> sets the state string. There is no <i>threadgetstate</i>; + since the thread scheduler resets the state to <tt><font size=+1>Running</font></tt> every time + it runs the thread, it is only useful for debuggers to inspect + the state. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Threaddata</i> returns a pointer to a per-thread pointer that may + be modified by threaded programs for per-thread storage. Similarly, + <i>procdata</i> returns a pointer to a per-proc pointer. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Threadexecl</i> and <i>threadexec</i> are threaded analogues of <i>exec</i> and + <i>execl</i> (see <a href="../man3/exec.html"><i>exec</i>(3)</a>); on success, they replace the calling thread + and invoke the external program, never returning. (Unlike on Plan + 9, the calling thread need not be the only thread in its proc--the + other threads will continue executing.) On error, they return + –1. If <i>cpid</i> is not null, the pid of the invoked program will be + sent along <i>cpid</i> (using <i>sendul</i>) once the program has been started, + or –1 will be sent if an error occurs. <i>Threadexec</i> and <i>threadexecl</i> + will not access their arguments after sending a result along <i>cpid</i>. + Thus, programs that malloc the <i>argv</i> passed to <i>threadexec + </i>can safely free it once they have received the <i>cpid</i> response. + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Threadexecl</i> and <i>threadexec</i> will duplicate (see <a href="../man3/dup.html"><i>dup</i>(3)</a>) the three + file descriptors in <i>fd</i> onto standard input, output, and error + for the external program and then close them in the calling thread. + Beware of code that sets<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>fd[0] = 0;<br> + fd[1] = 1;<br> + fd[2] = 2;<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + + </table> + to use the current standard files. The correct code is<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>fd[0] = dup(0, −1);<br> + fd[1] = dup(1, −1);<br> + fd[2] = dup(2, −1);<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + + </table> + <i>Threadspawn</i> is like <i>threadexec</i> but does not replace the current + thread. It returns the pid of the invoked program on success, + or –1 on error. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Threadwaitchan</i> returns a channel of pointers to <tt><font size=+1>Waitmsg</font></tt> structures + (see <a href="../man3/wait.html"><i>wait</i>(3)</a>). When an exec’ed process exits, a pointer to a <tt><font size=+1>Waitmsg</font></tt> + is sent to this channel. These <tt><font size=+1>Waitmsg</font></tt> structures have been allocated + with <a href="../man3/malloc.html"><i>malloc</i>(3)</a> and should be freed after use. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + A <tt><font size=+1>Channel</font></tt> is a buffered or unbuffered queue for fixed-size messages. + Procs and threads <i>send</i> messages into the channel and <i>recv</i> messages + from the channel. If the channel is unbuffered, a <i>send</i> operation + blocks until the corresponding <i>recv</i> operation occurs and <i>vice + versa</i>. <i>Chaninit</i> initializes a <tt><font size=+1>Channel</font></tt> for + messages of size <i>elsize</i> and with a buffer holding <i>nel</i> messages. + If <i>nel</i> is zero, the channel is unbuffered. <i>Chancreate</i> allocates + a new channel and initializes it. <i>Chanfree</i> frees a channel that + is no longer used. <i>Chanfree</i> can be called by either sender or + receiver after the last item has been sent or received. Freeing + the + channel will be delayed if there is a thread blocked on it until + that thread unblocks (but <i>chanfree</i> returns immediately). + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + The <tt><font size=+1>name</font></tt> element in the <tt><font size=+1>Channel</font></tt> structure is a description intended + for use in debugging. <i>Chansetname</i> sets the name. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Send</i> sends the element pointed at by <i>v</i> to the channel <i>c</i>. If <i>v</i> + is null, zeros are sent. <i>Recv</i> receives an element from <i>c</i> and stores + it in <i>v</i>. If <i>v</i> is null, the received value is discarded. <i>Send</i> and + <i>recv</i> return 1 on success, –1 if interrupted. <i>Nbsend</i> and <i>nbrecv</i> + behave similarly, but return 0 rather than blocking. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Sendp</i>, <i>nbsendp</i>, <i>sendul</i>, and <i>nbsendul</i> send a pointer or an unsigned + long; the channel must have been initialized with the appropriate + <i>elsize</i>. <i>Recvp</i>, <i>nbrecvp</i>, <i>recvul</i>, and <i>nbrecvul</i> receive a pointer + or an unsigned long; they return zero when a zero is received, + when interrupted, or (for <i>nbrecvp</i> and <i>nbrecvul</i>) when the + operation would have blocked. To distinguish between these three + cases, use <i>recv</i> or <i>nbrecv</i>. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Alt</i> can be used to recv from or send to one of a number of channels, + as directed by an array of <tt><font size=+1>Alt</font></tt> structures, each of which describes + a potential send or receive operation. In an <tt><font size=+1>Alt</font></tt> structure, <tt><font size=+1>c</font></tt> + is the channel; <tt><font size=+1>v</font></tt> the value pointer (which may be null); and <tt><font size=+1>op</font></tt> + the operation: <tt><font size=+1>CHANSND</font></tt> for a send operation, + <tt><font size=+1>CHANRECV</font></tt> for a recv operation; <tt><font size=+1>CHANNOP</font></tt> for no operation (useful + when <i>alt</i> is called with a varying set of operations). The array + of <tt><font size=+1>Alt</font></tt> structures is terminated by an entry with <i>op</i> <tt><font size=+1>CHANEND</font></tt> or + <tt><font size=+1>CHANNOBLK</font></tt>. If at least one <tt><font size=+1>Alt</font></tt> structure can proceed, one of them + is chosen at random to be executed. <i>Alt</i> returns the + index of the chosen structure. If no operations can proceed and + the list is terminated with <tt><font size=+1>CHANNOBLK</font></tt>, <i>alt</i> returns the index of + the terminating <tt><font size=+1>CHANNOBLK</font></tt> structure. Otherwise, <i>alt</i> blocks until + one of the operations can proceed, eventually returning the index + of the structure executes. <i>Alt</i> returns –1 when + interrupted. The <tt><font size=+1>tag</font></tt> and <tt><font size=+1>entryno</font></tt> fields in the <tt><font size=+1>Alt</font></tt> structure are + used internally by <i>alt</i> and need not be initialized. They are not + used between <i>alt</i> calls. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Chanprint</i> formats its arguments in the manner of <a href="../man3/print.html"><i>print</i>(3)</a> and + sends the result to the channel <i>c.</i> The string delivered by <i>chanprint</i> + is allocated with <a href="../man3/malloc.html"><i>malloc</i>(3)</a> and should be freed upon receipt. + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + Thread library functions do not return on failure; if errors occur, + the entire program is aborted. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + Threaded programs should use <i>threadnotify</i> in place of <i>atnotify</i> + (see <a href="../man3/notify.html"><i>notify</i>(3)</a>). + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + It is safe to use <a href="../man3/sysfatal.html"><i>sysfatal</i>(3)</a> in threaded programs. <i>Sysfatal</i> will + print the error string and call <i>threadexitsall</i>. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + It is not safe to call <i>rfork</i> in a threaded program, except to + call <tt><font size=+1>rfork(RFNOTEG)</font></tt> from the main proc before any other procs + have been created. To create new processes, use <i>proccreate</i>.<br> + +</table> +<p><font size=+1><b>FILES </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>/usr/local/plan9/acid/thread</font></tt> contains useful <a href="../man1/acid.html"><i>acid</i>(1)</a> functions + for debugging threaded programs. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <tt><font size=+1>/usr/local/plan9/src/libthread/test</font></tt> contains some example programs.<br> + +</table> +<p><font size=+1><b>SOURCE </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>/usr/local/plan9/src/libthread<br> + </font></tt> +</table> +<p><font size=+1><b>SEE ALSO </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <a href="../man3/intro.html"><i>intro</i>(3)</a>, <a href="../man3/ioproc.html"><i>ioproc</i>(3)</a><br> + +</table> +<p><font size=+1><b>BUGS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + To avoid name conflicts, <i>alt</i>, <i>nbrecv</i>, <i>nbrecvp</i>, <i>nbrecvul</i>, <i>nbsend</i>, + <i>nbsendp</i>, <i>nbsendul</i>, <i>recv</i>, <i>recvp</i>, <i>recvul</i>, <i>send</i>, <i>sendp</i>, and <i>sendul</i> + are defined as macros that expand to <i>chanalt</i>, <i>channbrecv</i>, and + so on. <i>Yield</i> is defined as a macro that expands to <i>threadyield</i>. + See <a href="../man3/intro.html"><i>intro</i>(3)</a>. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + The implementation of <i>threadnotify</i> may not be correct.<br> + +</table> + +<td width=20> +<tr height=20><td> +</table> +<!-- TRAILER --> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=15><td width=10><td><td width=10> +<tr><td><td> +<center> +<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> +</center> +</table> +<!-- TRAILER --> +</body></html> |