From adc93f6097615f16d57e8a24a256302f2144ec4e Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 17:37:50 +0000 Subject: cut out the html - they're going to cause diffing problems. --- man/man3/thread.html | 383 --------------------------------------------------- 1 file changed, 383 deletions(-) delete mode 100644 man/man3/thread.html (limited to 'man/man3/thread.html') diff --git a/man/man3/thread.html b/man/man3/thread.html deleted file mode 100644 index b14d97e6..00000000 --- a/man/man3/thread.html +++ /dev/null @@ -1,383 +0,0 @@ - -thread(3) - Plan 9 from User Space - - - - -
-
-
THREAD(3)THREAD(3) -
-
-

NAME
- -
- - 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
- -
-

SYNOPSIS
- -
- - -
- - #include <u.h>
- #include <libc.h>
- #include <thread.h>
- #define    CHANEND      0
- #define    CHANSND      1
- #define    CHANRCV      2
- #define    CHANNOP      3
- #define    CHANNOBLK    4
- typedef struct Alt Alt;
- struct Alt {
- -
- - Channel *c;
- void      *v;
- int       op;
- Channel **tag;
- int       entryno;
- char      *name;
- -
- };
- -
- - void       threadmain(int argc, char *argv[])
- int        mainstacksize
- int        proccreate(void (*fn)(void*), void *arg, uint stacksize)
- int        threadcreate(void (*fn)(void*), void *arg, uint stacksize)
- void       threadexits(char *status)
- void       threadexitsall(char *status)
- void       yield(void)
- int        threadid(void)
- int        threadgrp(void)
- int        threadsetgrp(int group)
- int        threadpid(int id)
- int        threadint(int id)
- int        threadintgrp(int group)
- int        threadkill(int id)
- int        threadkillgrp(int group)
- void       threadsetname(char *name)
- char*      threadgetname(void)
- void**     threaddata(void)
- void**     procdata(void)
- int        chaninit(Channel *c, int elsize, int nel)
- Channel* chancreate(int elsize, int nel)
- void       chanfree(Channel *c)
- int        alt(Alt *alts)
- int        recv(Channel *c, void *v)
- void*      recvp(Channel *c)
- ulong      recvul(Channel *c)
- int        nbrecv(Channel *c, void *v)
- void*      nbrecvp(Channel *c)
- ulong      nbrecvul(Channel *c)
- int        send(Channel *c, void *v)
- int        sendp(Channel *c, void *v)
- int        sendul(Channel *c, ulong v)
- int        nbsend(Channel *c, void *v)
- int        nbsendp(Channel *c, void *v)
- int        nbsendul(Channel *c, ulong v)
- int        chanprint(Channel *c, char *fmt, ...)
- int        threadspawn(int fd[3], char *file, char *args[])
- int        threadexecl(Channel *cpid, int fd[3], char *file, ...)
- int        threadexec(Channel *cpid, int fd[3], char *file, char *args[])
- Channel* threadwaitchan(void)
- int        threadnotify(int (*f)(void*, char*), int in)
- -
-

DESCRIPTION
- -
- - -
- - 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 channels and shared variables. -
- - A proc is a Plan 9 process that contains one or more cooperatively - scheduled threads. Programs using threads must replace main by - threadmain. The thread library provides a main function that sets - up a proc with a single thread executing threadmain on a stack - of size mainstacksize (default eight kilobytes). To set - mainstacksize, declare a global variable initialized to the desired - value (e.g., int mainstacksize = 1024). -
- - Threadcreate creates a new thread in the calling proc, returning - a unique integer identifying the thread; the thread executes fn(arg) - on a stack of size stacksize. Thread stacks are allocated in shared - memory, making it valid to pass pointers to stack variables between - threads and procs. Proccreate creates a new proc, - and inside that proc creates a single thread as threadcreate 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, arg should not point to - data on the stack of a function that could return before the - new process is scheduled. -
- - Threadexits terminates the calling thread. If the thread is the - last in its proc, threadexits also terminates the proc, using - status as the exit status. Threadexitsall terminates all procs - in the program, using status as the exit status. -
- - When the last thread in threadmain’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. -
- - 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 yield, proccreate, threadexec, - threadexecl, threadexits, threadspawn, alt, send, and recv (and - the - calls related to send and recv--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 qlocks (see lock(3)) or - channel communication. System calls such as read(3) - block the entire proc; all threads in a proc block until the system - call finishes. -
- - 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. Threadid 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. Threadgrp returns the group id for the - current thread; threadsetgrp sets it. Threadpid returns the pid - of the Plan 9 process containing the thread identified by id, - or –1 if no such thread is found. -
- - Threadint interrupts a thread that is blocked in a channel operation - or system call. Threadintgrp interrupts all threads with the given - group id. Threadkill 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. Threadkillgrp kills all threads with the given - group id. Note that threadkill and threadkillgrp will not terminate - a thread that never relinquishes the processor. -
- - Primarily for debugging, threads can have string names associated - with them. Threadgetname returns the current thread’s name; threadsetname - sets it. The pointer returned by threadgetname is only valid until - the next call to threadsetname. -
- - Also for debugging, threads have a string state associated with - them. Threadsetstate sets the state string. There is no threadgetstate; - since the thread scheduler resets the state to Running every time - it runs the thread, it is only useful for debuggers to inspect - the state. -
- - Threaddata returns a pointer to a per-thread pointer that may - be modified by threaded programs for per-thread storage. Similarly, - procdata returns a pointer to a per-proc pointer. -
- - Threadexecl and threadexec are threaded analogues of exec and - execl (see exec(3)); 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 cpid is not null, the pid of the invoked program will be - sent along cpid (using sendul) once the program has been started, - or –1 will be sent if an error occurs. Threadexec and threadexecl - will not access their arguments after sending a result along cpid. - Thus, programs that malloc the argv passed to threadexec - can safely free it once they have received the cpid response. - -
- - Threadexecl and threadexec will duplicate (see dup(3)) the three - file descriptors in fd onto standard input, output, and error - for the external program and then close them in the calling thread. - Beware of code that sets
- -
- - fd[0] = 0;
- fd[1] = 1;
- fd[2] = 2;
- -
- - -
- to use the current standard files. The correct code is
- -
- - fd[0] = dup(0, −1);
- fd[1] = dup(1, −1);
- fd[2] = dup(2, −1);
- -
- - -
- Threadspawn is like threadexec but does not replace the current - thread. It returns the pid of the invoked program on success, - or –1 on error. -
- - Threadwaitchan returns a channel of pointers to Waitmsg structures - (see wait(3)). When an exec’ed process exits, a pointer to a Waitmsg - is sent to this channel. These Waitmsg structures have been allocated - with malloc(3) and should be freed after use. -
- - A Channel is a buffered or unbuffered queue for fixed-size messages. - Procs and threads send messages into the channel and recv messages - from the channel. If the channel is unbuffered, a send operation - blocks until the corresponding recv operation occurs and vice - versa. Chaninit initializes a Channel for - messages of size elsize and with a buffer holding nel messages. - If nel is zero, the channel is unbuffered. Chancreate allocates - a new channel and initializes it. Chanfree frees a channel that - is no longer used. Chanfree 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 chanfree returns immediately). -
- - The name element in the Channel structure is a description intended - for use in debugging. Chansetname sets the name. -
- - Send sends the element pointed at by v to the channel c. If v - is null, zeros are sent. Recv receives an element from c and stores - it in v. If v is null, the received value is discarded. Send and - recv return 1 on success, –1 if interrupted. Nbsend and nbrecv - behave similarly, but return 0 rather than blocking. -
- - Sendp, nbsendp, sendul, and nbsendul send a pointer or an unsigned - long; the channel must have been initialized with the appropriate - elsize. Recvp, nbrecvp, recvul, and nbrecvul receive a pointer - or an unsigned long; they return zero when a zero is received, - when interrupted, or (for nbrecvp and nbrecvul) when the - operation would have blocked. To distinguish between these three - cases, use recv or nbrecv. -
- - Alt can be used to recv from or send to one of a number of channels, - as directed by an array of Alt structures, each of which describes - a potential send or receive operation. In an Alt structure, c - is the channel; v the value pointer (which may be null); and op - the operation: CHANSND for a send operation, - CHANRECV for a recv operation; CHANNOP for no operation (useful - when alt is called with a varying set of operations). The array - of Alt structures is terminated by an entry with op CHANEND or - CHANNOBLK. If at least one Alt structure can proceed, one of them - is chosen at random to be executed. Alt returns the - index of the chosen structure. If no operations can proceed and - the list is terminated with CHANNOBLK, alt returns the index of - the terminating CHANNOBLK structure. Otherwise, alt blocks until - one of the operations can proceed, eventually returning the index - of the structure executes. Alt returns –1 when - interrupted. The tag and entryno fields in the Alt structure are - used internally by alt and need not be initialized. They are not - used between alt calls. -
- - Chanprint formats its arguments in the manner of print(3) and - sends the result to the channel c. The string delivered by chanprint - is allocated with malloc(3) and should be freed upon receipt. - -
- - Thread library functions do not return on failure; if errors occur, - the entire program is aborted. -
- - Threaded programs should use threadnotify in place of atnotify - (see notify(3)). -
- - It is safe to use sysfatal(3) in threaded programs. Sysfatal will - print the error string and call threadexitsall. -
- - It is not safe to call rfork in a threaded program, except to - call rfork(RFNOTEG) from the main proc before any other procs - have been created. To create new processes, use proccreate.
- -
-

FILES
- -
- - /usr/local/plan9/acid/thread contains useful acid(1) functions - for debugging threaded programs. -
- - /usr/local/plan9/src/libthread/test contains some example programs.
- -
-

SOURCE
- -
- - /usr/local/plan9/src/libthread
- -
-

SEE ALSO
- -
- - intro(3), ioproc(3)
- -
-

BUGS
- -
- - To avoid name conflicts, alt, nbrecv, nbrecvp, nbrecvul, nbsend, - nbsendp, nbsendul, recv, recvp, recvul, send, sendp, and sendul - are defined as macros that expand to chanalt, channbrecv, and - so on. Yield is defined as a macro that expands to threadyield. - See intro(3). -
- - The implementation of threadnotify may not be correct.
- -
- -

 -
-
- - -
-
-
-Space Glenda -
-
- - -- cgit v1.2.3