1 cfa37a7b 2004-04-10 devnull .TH THREAD 3
4 b2cfc4e2 2003-09-30 devnull chancreate,
7 b2cfc4e2 2003-09-30 devnull chanprint,
8 058b0118 2005-01-03 devnull chansetname,
9 b2cfc4e2 2003-09-30 devnull mainstacksize,
10 b2cfc4e2 2003-09-30 devnull proccreate,
11 b2cfc4e2 2003-09-30 devnull procdata,
20 b2cfc4e2 2003-09-30 devnull nbrecvul,
23 b2cfc4e2 2003-09-30 devnull nbsendul,
24 b2cfc4e2 2003-09-30 devnull threadcreate,
25 b2cfc4e2 2003-09-30 devnull threaddata,
26 058b0118 2005-01-03 devnull threadexec,
27 058b0118 2005-01-03 devnull threadexecl,
28 b2cfc4e2 2003-09-30 devnull threadexits,
29 b2cfc4e2 2003-09-30 devnull threadexitsall,
30 b2cfc4e2 2003-09-30 devnull threadgetgrp,
31 b2cfc4e2 2003-09-30 devnull threadgetname,
32 b2cfc4e2 2003-09-30 devnull threadint,
33 b2cfc4e2 2003-09-30 devnull threadintgrp,
34 b2cfc4e2 2003-09-30 devnull threadkill,
35 b2cfc4e2 2003-09-30 devnull threadkillgrp,
36 058b0118 2005-01-03 devnull threadlinklibrary,
37 b2cfc4e2 2003-09-30 devnull threadmain,
38 b2cfc4e2 2003-09-30 devnull threadnotify,
39 b2cfc4e2 2003-09-30 devnull threadid,
40 b2cfc4e2 2003-09-30 devnull threadpid,
41 b2cfc4e2 2003-09-30 devnull threadsetgrp,
42 b2cfc4e2 2003-09-30 devnull threadsetname,
43 058b0118 2005-01-03 devnull threadsetstate,
44 058b0118 2005-01-03 devnull threadspawn,
45 b2cfc4e2 2003-09-30 devnull threadwaitchan,
46 b2cfc4e2 2003-09-30 devnull yield \- thread and proc management
47 b2cfc4e2 2003-09-30 devnull .SH SYNOPSIS
58 b2cfc4e2 2003-09-30 devnull .ta 4n +4n +4n +4n +4n +4n +4n
59 b2cfc4e2 2003-09-30 devnull #include <u.h>
60 b2cfc4e2 2003-09-30 devnull #include <libc.h>
61 b2cfc4e2 2003-09-30 devnull #include <thread.h>
63 b2cfc4e2 2003-09-30 devnull #define CHANEND 0
64 b2cfc4e2 2003-09-30 devnull #define CHANSND 1
65 b2cfc4e2 2003-09-30 devnull #define CHANRCV 2
66 b2cfc4e2 2003-09-30 devnull #define CHANNOP 3
67 b2cfc4e2 2003-09-30 devnull #define CHANNOBLK 4
69 b2cfc4e2 2003-09-30 devnull .ta \w' 'u +\w'Channel 'u
70 b2cfc4e2 2003-09-30 devnull typedef struct Alt Alt;
71 b2cfc4e2 2003-09-30 devnull struct Alt {
72 b2cfc4e2 2003-09-30 devnull Channel *c;
75 b2cfc4e2 2003-09-30 devnull Channel **tag;
76 b2cfc4e2 2003-09-30 devnull int entryno;
77 058b0118 2005-01-03 devnull char *name;
81 b5fdffee 2004-04-19 devnull .if t .sp 0.5
82 b5fdffee 2004-04-19 devnull .if n .sp
87 b2cfc4e2 2003-09-30 devnull .ta \w'\fLChannel* 'u +4n +4n +4n +4n
88 b2cfc4e2 2003-09-30 devnull void threadmain(int argc, char *argv[])
89 b2cfc4e2 2003-09-30 devnull int mainstacksize
90 b2cfc4e2 2003-09-30 devnull int proccreate(void (*fn)(void*), void *arg, uint stacksize)
91 b2cfc4e2 2003-09-30 devnull int procrfork(void (*fn)(void*), void *arg, uint stacksize,
92 b2cfc4e2 2003-09-30 devnull int rforkflag)
93 b2cfc4e2 2003-09-30 devnull int threadcreate(void (*fn)(void*), void *arg, uint stacksize)
94 b2cfc4e2 2003-09-30 devnull void threadexits(char *status)
95 b2cfc4e2 2003-09-30 devnull void threadexitsall(char *status)
96 b2cfc4e2 2003-09-30 devnull void yield(void)
98 b2cfc4e2 2003-09-30 devnull int threadid(void)
99 b2cfc4e2 2003-09-30 devnull int threadgrp(void)
100 b2cfc4e2 2003-09-30 devnull int threadsetgrp(int group)
101 b2cfc4e2 2003-09-30 devnull int threadpid(int id)
103 b2cfc4e2 2003-09-30 devnull int threadint(int id)
104 b2cfc4e2 2003-09-30 devnull int threadintgrp(int group)
105 b2cfc4e2 2003-09-30 devnull int threadkill(int id)
106 b2cfc4e2 2003-09-30 devnull int threadkillgrp(int group)
108 b2cfc4e2 2003-09-30 devnull void threadsetname(char *name)
109 b2cfc4e2 2003-09-30 devnull char* threadgetname(void)
111 b2cfc4e2 2003-09-30 devnull void** threaddata(void)
112 b2cfc4e2 2003-09-30 devnull void** procdata(void)
114 b2cfc4e2 2003-09-30 devnull int chaninit(Channel *c, int elsize, int nel)
115 b2cfc4e2 2003-09-30 devnull Channel* chancreate(int elsize, int nel)
116 b2cfc4e2 2003-09-30 devnull void chanfree(Channel *c)
118 b2cfc4e2 2003-09-30 devnull int alt(Alt *alts)
119 b2cfc4e2 2003-09-30 devnull int recv(Channel *c, void *v)
120 b2cfc4e2 2003-09-30 devnull void* recvp(Channel *c)
121 b2cfc4e2 2003-09-30 devnull ulong recvul(Channel *c)
122 b2cfc4e2 2003-09-30 devnull int nbrecv(Channel *c, void *v)
123 b2cfc4e2 2003-09-30 devnull void* nbrecvp(Channel *c)
124 b2cfc4e2 2003-09-30 devnull ulong nbrecvul(Channel *c)
125 b2cfc4e2 2003-09-30 devnull int send(Channel *c, void *v)
126 b2cfc4e2 2003-09-30 devnull int sendp(Channel *c, void *v)
127 b2cfc4e2 2003-09-30 devnull int sendul(Channel *c, ulong v)
128 b2cfc4e2 2003-09-30 devnull int nbsend(Channel *c, void *v)
129 b2cfc4e2 2003-09-30 devnull int nbsendp(Channel *c, void *v)
130 b2cfc4e2 2003-09-30 devnull int nbsendul(Channel *c, ulong v)
131 b2cfc4e2 2003-09-30 devnull int chanprint(Channel *c, char *fmt, ...)
133 058b0118 2005-01-03 devnull int threadspawn(int fd[3], char *file, char *args[])
134 058b0118 2005-01-03 devnull int threadexecl(Channel *cpid, int fd[3], char *file, ...)
135 058b0118 2005-01-03 devnull int threadexec(Channel *cpid, int fd[3], char *file, char *args[])
136 b2cfc4e2 2003-09-30 devnull Channel* threadwaitchan(void)
138 b2cfc4e2 2003-09-30 devnull int threadnotify(int (*f)(void*, char*), int in)
140 b2cfc4e2 2003-09-30 devnull .SH DESCRIPTION
142 b2cfc4e2 2003-09-30 devnull The thread library provides parallel programming support similar to that
143 b2cfc4e2 2003-09-30 devnull of the languages
144 b2cfc4e2 2003-09-30 devnull Alef and Newsqueak.
148 b2cfc4e2 2003-09-30 devnull occupy a shared address space,
149 b2cfc4e2 2003-09-30 devnull communicating and synchronizing through
150 b2cfc4e2 2003-09-30 devnull .I channels
151 b2cfc4e2 2003-09-30 devnull and shared variables.
155 b2cfc4e2 2003-09-30 devnull is a Plan 9 process that contains one or more cooperatively scheduled
156 b2cfc4e2 2003-09-30 devnull .IR threads .
157 b2cfc4e2 2003-09-30 devnull Programs using threads must replace
160 b2cfc4e2 2003-09-30 devnull .IR threadmain .
161 b2cfc4e2 2003-09-30 devnull The thread library provides a
163 b2cfc4e2 2003-09-30 devnull function that sets up a proc with a single thread executing
164 b2cfc4e2 2003-09-30 devnull .I threadmain
165 b2cfc4e2 2003-09-30 devnull on a stack of size
166 b2cfc4e2 2003-09-30 devnull .I mainstacksize
167 b2cfc4e2 2003-09-30 devnull (default eight kilobytes).
169 b2cfc4e2 2003-09-30 devnull .IR mainstacksize ,
170 b2cfc4e2 2003-09-30 devnull declare a global variable
171 b2cfc4e2 2003-09-30 devnull initialized to the desired value
172 b2cfc4e2 2003-09-30 devnull .RI ( e.g. ,
174 b2cfc4e2 2003-09-30 devnull .B mainstacksize
176 b2cfc4e2 2003-09-30 devnull .BR 1024 ).
178 b2cfc4e2 2003-09-30 devnull .I Threadcreate
179 b2cfc4e2 2003-09-30 devnull creates a new thread in the calling proc, returning a unique integer
180 b2cfc4e2 2003-09-30 devnull identifying the thread; the thread
181 b2cfc4e2 2003-09-30 devnull executes
182 b2cfc4e2 2003-09-30 devnull .I fn(arg)
183 b2cfc4e2 2003-09-30 devnull on a stack of size
184 b2cfc4e2 2003-09-30 devnull .IR stacksize .
185 b2cfc4e2 2003-09-30 devnull Thread stacks are allocated in shared memory, making it valid to pass
186 b2cfc4e2 2003-09-30 devnull pointers to stack variables between threads and procs.
187 058b0118 2005-01-03 devnull .I Proccreate
188 b2cfc4e2 2003-09-30 devnull creates a new proc, and inside that proc creates
189 b2cfc4e2 2003-09-30 devnull a single thread as
190 b2cfc4e2 2003-09-30 devnull .I threadcreate
192 b2cfc4e2 2003-09-30 devnull returning the id of the created thread.
193 058b0118 2005-01-03 devnull .\" .I Procrfork
194 058b0118 2005-01-03 devnull .\" creates the new proc by calling
195 058b0118 2005-01-03 devnull .\" .B rfork
196 058b0118 2005-01-03 devnull .\" (see
197 058b0118 2005-01-03 devnull .\" .IR fork (3))
198 058b0118 2005-01-03 devnull .\" with flags
199 058b0118 2005-01-03 devnull .\" .BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR.
200 058b0118 2005-01-03 devnull .\" (The thread library depends on all its procs
201 058b0118 2005-01-03 devnull .\" running in the same rendezvous group.
202 058b0118 2005-01-03 devnull .\" Do not include
203 058b0118 2005-01-03 devnull .\" .B RFREND
205 058b0118 2005-01-03 devnull .\" .IR rforkflag .)
206 058b0118 2005-01-03 devnull .\" .I Proccreate
207 058b0118 2005-01-03 devnull .\" is identical to
208 058b0118 2005-01-03 devnull .\" .I procrfork
209 058b0118 2005-01-03 devnull .\" with
210 058b0118 2005-01-03 devnull .\" .I rforkflag
211 058b0118 2005-01-03 devnull .\" set to zero.
212 b2cfc4e2 2003-09-30 devnull Be aware that the calling thread may continue
213 b2cfc4e2 2003-09-30 devnull execution before
214 b2cfc4e2 2003-09-30 devnull the newly created proc and thread
215 b2cfc4e2 2003-09-30 devnull are scheduled.
216 b2cfc4e2 2003-09-30 devnull Because of this,
218 b2cfc4e2 2003-09-30 devnull should not point to data on the stack of a function that could
219 b2cfc4e2 2003-09-30 devnull return before the new process is scheduled.
221 b2cfc4e2 2003-09-30 devnull .I Threadexits
222 b2cfc4e2 2003-09-30 devnull terminates the calling thread.
223 b2cfc4e2 2003-09-30 devnull If the thread is the last in its proc,
224 b2cfc4e2 2003-09-30 devnull .I threadexits
225 b2cfc4e2 2003-09-30 devnull also terminates the proc, using
226 b2cfc4e2 2003-09-30 devnull .I status
227 b2cfc4e2 2003-09-30 devnull as the exit status.
228 b2cfc4e2 2003-09-30 devnull .I Threadexitsall
229 b2cfc4e2 2003-09-30 devnull terminates all procs in the program,
231 b2cfc4e2 2003-09-30 devnull .I status
232 b2cfc4e2 2003-09-30 devnull as the exit status.
234 058b0118 2005-01-03 devnull When the last thread in
235 058b0118 2005-01-03 devnull .IR threadmain 's
236 058b0118 2005-01-03 devnull proc exits, the program will appear to its parent to have exited.
237 058b0118 2005-01-03 devnull The remaining procs will still run together, but as a background program.
239 b2cfc4e2 2003-09-30 devnull The threads in a proc are coroutines, scheduled nonpreemptively
240 b2cfc4e2 2003-09-30 devnull in a round-robin fashion.
241 b2cfc4e2 2003-09-30 devnull A thread must explicitly relinquish control of the processor
242 b2cfc4e2 2003-09-30 devnull before another thread in the same proc is run.
243 b2cfc4e2 2003-09-30 devnull Calls that do this are
244 b2cfc4e2 2003-09-30 devnull .IR yield ,
245 b2cfc4e2 2003-09-30 devnull .IR proccreate ,
246 058b0118 2005-01-03 devnull .IR threadexec ,
247 058b0118 2005-01-03 devnull .IR threadexecl ,
248 b2cfc4e2 2003-09-30 devnull .IR threadexits ,
249 058b0118 2005-01-03 devnull .IR threadspawn ,
250 b2cfc4e2 2003-09-30 devnull .IR alt ,
251 b2cfc4e2 2003-09-30 devnull .IR send ,
254 b2cfc4e2 2003-09-30 devnull (and the calls related to
257 b2cfc4e2 2003-09-30 devnull .IR recv \(emsee
258 b2cfc4e2 2003-09-30 devnull their descriptions further on).
259 b2cfc4e2 2003-09-30 devnull Procs are scheduled by the operating system.
260 b2cfc4e2 2003-09-30 devnull Therefore, threads in different procs can preempt one another
261 b2cfc4e2 2003-09-30 devnull in arbitrary ways and should synchronize their
262 b2cfc4e2 2003-09-30 devnull actions using
263 b2cfc4e2 2003-09-30 devnull .B qlocks
265 bf8a59fa 2004-04-11 devnull .IR lock (3))
266 b2cfc4e2 2003-09-30 devnull or channel communication.
267 b2cfc4e2 2003-09-30 devnull System calls such as
268 bf8a59fa 2004-04-11 devnull .IR read (3)
269 b2cfc4e2 2003-09-30 devnull block the entire proc;
270 b2cfc4e2 2003-09-30 devnull all threads in a proc block until the system call finishes.
272 b2cfc4e2 2003-09-30 devnull As mentioned above, each thread has a unique integer thread id.
273 b2cfc4e2 2003-09-30 devnull Thread ids are not reused; they are unique across the life of the program.
274 b2cfc4e2 2003-09-30 devnull .I Threadid
275 b2cfc4e2 2003-09-30 devnull returns the id for the current thread.
276 b2cfc4e2 2003-09-30 devnull Each thread also has a thread group id.
277 b2cfc4e2 2003-09-30 devnull The initial thread has a group id of zero.
278 b2cfc4e2 2003-09-30 devnull Each new thread inherits the group id of
279 b2cfc4e2 2003-09-30 devnull the thread that created it.
280 b2cfc4e2 2003-09-30 devnull .I Threadgrp
281 b2cfc4e2 2003-09-30 devnull returns the group id for the current thread;
282 b2cfc4e2 2003-09-30 devnull .I threadsetgrp
283 b2cfc4e2 2003-09-30 devnull sets it.
284 b2cfc4e2 2003-09-30 devnull .I Threadpid
285 b2cfc4e2 2003-09-30 devnull returns the pid of the Plan 9 process containing
286 b2cfc4e2 2003-09-30 devnull the thread identified by
287 b2cfc4e2 2003-09-30 devnull .IR id ,
289 b2cfc4e2 2003-09-30 devnull if no such thread is found.
291 b2cfc4e2 2003-09-30 devnull .I Threadint
292 b2cfc4e2 2003-09-30 devnull interrupts a thread that is blocked in a channel operation
293 b2cfc4e2 2003-09-30 devnull or system call.
294 b2cfc4e2 2003-09-30 devnull .I Threadintgrp
295 b2cfc4e2 2003-09-30 devnull interrupts all threads with the given group id.
296 b2cfc4e2 2003-09-30 devnull .I Threadkill
297 b2cfc4e2 2003-09-30 devnull marks a thread to die when it next relinquishes the processor
298 b2cfc4e2 2003-09-30 devnull (via one of the calls listed above).
299 b2cfc4e2 2003-09-30 devnull If the thread is blocked in a channel operation or system call,
300 b2cfc4e2 2003-09-30 devnull it is also interrupted.
301 b2cfc4e2 2003-09-30 devnull .I Threadkillgrp
302 b2cfc4e2 2003-09-30 devnull kills all threads with the given group id.
303 b2cfc4e2 2003-09-30 devnull Note that
304 b2cfc4e2 2003-09-30 devnull .I threadkill
306 b2cfc4e2 2003-09-30 devnull .I threadkillgrp
307 b2cfc4e2 2003-09-30 devnull will not terminate a thread that never relinquishes
308 b2cfc4e2 2003-09-30 devnull the processor.
310 b2cfc4e2 2003-09-30 devnull Primarily for debugging,
311 b2cfc4e2 2003-09-30 devnull threads can have string names associated with them.
312 b2cfc4e2 2003-09-30 devnull .I Threadgetname
313 b2cfc4e2 2003-09-30 devnull returns the current thread's name;
314 b2cfc4e2 2003-09-30 devnull .I threadsetname
315 b2cfc4e2 2003-09-30 devnull sets it.
316 b2cfc4e2 2003-09-30 devnull The pointer returned by
317 b2cfc4e2 2003-09-30 devnull .I threadgetname
318 b2cfc4e2 2003-09-30 devnull is only valid until the next call to
319 b2cfc4e2 2003-09-30 devnull .IR threadsetname .
321 058b0118 2005-01-03 devnull Also for debugging,
322 058b0118 2005-01-03 devnull threads have a string state associated with them.
323 058b0118 2005-01-03 devnull .I Threadsetstate
324 058b0118 2005-01-03 devnull sets the state string.
325 058b0118 2005-01-03 devnull There is no
326 058b0118 2005-01-03 devnull .IR threadgetstate ;
327 058b0118 2005-01-03 devnull since the thread scheduler resets the state to
328 058b0118 2005-01-03 devnull .B Running
329 058b0118 2005-01-03 devnull every time it runs the thread,
330 058b0118 2005-01-03 devnull it is only useful for debuggers to inspect the state.
332 b2cfc4e2 2003-09-30 devnull .I Threaddata
333 b2cfc4e2 2003-09-30 devnull returns a pointer to a per-thread pointer
334 b2cfc4e2 2003-09-30 devnull that may be modified by threaded programs for
335 b2cfc4e2 2003-09-30 devnull per-thread storage.
336 b2cfc4e2 2003-09-30 devnull Similarly,
337 b2cfc4e2 2003-09-30 devnull .I procdata
338 b2cfc4e2 2003-09-30 devnull returns a pointer to a per-proc pointer.
340 058b0118 2005-01-03 devnull .I Threadexecl
342 058b0118 2005-01-03 devnull .I threadexec
343 b2cfc4e2 2003-09-30 devnull are threaded analogues of
346 b2cfc4e2 2003-09-30 devnull .I execl
348 bf8a59fa 2004-04-11 devnull .IR exec (3));
349 b2cfc4e2 2003-09-30 devnull on success,
350 058b0118 2005-01-03 devnull they replace the calling thread
351 b2cfc4e2 2003-09-30 devnull and invoke the external program, never returning.
352 058b0118 2005-01-03 devnull (Unlike on Plan 9, the calling thread need not be the only thread in its proc\(emthe other
353 058b0118 2005-01-03 devnull threads will continue executing.)
354 b2cfc4e2 2003-09-30 devnull On error, they return \-1.
357 b2cfc4e2 2003-09-30 devnull is not null, the pid of the invoked program
358 b2cfc4e2 2003-09-30 devnull will be sent along
361 058b0118 2005-01-03 devnull .IR sendul )
362 b2cfc4e2 2003-09-30 devnull once the program has been started, or \-1 will be sent if an
363 b2cfc4e2 2003-09-30 devnull error occurs.
364 058b0118 2005-01-03 devnull .I Threadexec
366 058b0118 2005-01-03 devnull .I threadexecl
367 b2cfc4e2 2003-09-30 devnull will not access their arguments after sending a result
369 b2cfc4e2 2003-09-30 devnull .IR cpid .
370 b2cfc4e2 2003-09-30 devnull Thus, programs that malloc the
372 b2cfc4e2 2003-09-30 devnull passed to
373 058b0118 2005-01-03 devnull .I threadexec
374 b2cfc4e2 2003-09-30 devnull can safely free it once they have
375 b2cfc4e2 2003-09-30 devnull received the
377 b2cfc4e2 2003-09-30 devnull response.
379 058b0118 2005-01-03 devnull .I Threadexecl
381 058b0118 2005-01-03 devnull .I threadexec
382 058b0118 2005-01-03 devnull will duplicate
384 058b0118 2005-01-03 devnull .IR dup (3))
385 058b0118 2005-01-03 devnull the three file descriptors in
387 058b0118 2005-01-03 devnull onto standard input, output, and error for the external program
388 058b0118 2005-01-03 devnull and then close them in the calling thread.
389 058b0118 2005-01-03 devnull Beware of code that sets
392 058b0118 2005-01-03 devnull fd[0] = 0;
393 058b0118 2005-01-03 devnull fd[1] = 1;
394 058b0118 2005-01-03 devnull fd[2] = 2;
396 058b0118 2005-01-03 devnull to use the current standard files. The correct code is
399 058b0118 2005-01-03 devnull fd[0] = dup(0, -1);
400 058b0118 2005-01-03 devnull fd[1] = dup(1, -1);
401 058b0118 2005-01-03 devnull fd[2] = dup(2, -1);
404 058b0118 2005-01-03 devnull .I Threadspawn
406 058b0118 2005-01-03 devnull .I threadexec
407 058b0118 2005-01-03 devnull but does not replace the current thread.
408 058b0118 2005-01-03 devnull It returns the pid of the invoked program on success, or
409 058b0118 2005-01-03 devnull \-1 on error.
411 b2cfc4e2 2003-09-30 devnull .I Threadwaitchan
412 b2cfc4e2 2003-09-30 devnull returns a channel of pointers to
413 b2cfc4e2 2003-09-30 devnull .B Waitmsg
414 b2cfc4e2 2003-09-30 devnull structures (see
415 bf8a59fa 2004-04-11 devnull .IR wait (3)).
416 b2cfc4e2 2003-09-30 devnull When an exec'ed process exits, a pointer to a
417 b2cfc4e2 2003-09-30 devnull .B Waitmsg
418 b2cfc4e2 2003-09-30 devnull is sent to this channel.
420 b2cfc4e2 2003-09-30 devnull .B Waitmsg
421 b2cfc4e2 2003-09-30 devnull structures have been allocated with
422 bf8a59fa 2004-04-11 devnull .IR malloc (3)
423 b2cfc4e2 2003-09-30 devnull and should be freed after use.
426 b2cfc4e2 2003-09-30 devnull .B Channel
427 b2cfc4e2 2003-09-30 devnull is a buffered or unbuffered queue for fixed-size messages.
428 b2cfc4e2 2003-09-30 devnull Procs and threads
430 b2cfc4e2 2003-09-30 devnull messages into the channel and
432 b2cfc4e2 2003-09-30 devnull messages from the channel. If the channel is unbuffered, a
434 b2cfc4e2 2003-09-30 devnull operation blocks until the corresponding
436 b2cfc4e2 2003-09-30 devnull operation occurs and
437 b2cfc4e2 2003-09-30 devnull .IR "vice versa" .
438 b2cfc4e2 2003-09-30 devnull .I Chaninit
439 b2cfc4e2 2003-09-30 devnull initializes a
440 b2cfc4e2 2003-09-30 devnull .B Channel
441 b2cfc4e2 2003-09-30 devnull for messages of size
442 b2cfc4e2 2003-09-30 devnull .I elsize
443 b2cfc4e2 2003-09-30 devnull and with a buffer holding
445 b2cfc4e2 2003-09-30 devnull messages.
448 b2cfc4e2 2003-09-30 devnull is zero, the channel is unbuffered.
449 b2cfc4e2 2003-09-30 devnull .IR Chancreate
450 b2cfc4e2 2003-09-30 devnull allocates a new channel and initializes it.
451 b2cfc4e2 2003-09-30 devnull .I Chanfree
452 b2cfc4e2 2003-09-30 devnull frees a channel that is no longer used.
453 b2cfc4e2 2003-09-30 devnull .I Chanfree
454 b2cfc4e2 2003-09-30 devnull can be called by either sender or receiver after the last item has been
455 b2cfc4e2 2003-09-30 devnull sent or received. Freeing the channel will be delayed if there is a thread
456 b2cfc4e2 2003-09-30 devnull blocked on it until that thread unblocks (but
457 b2cfc4e2 2003-09-30 devnull .I chanfree
458 b2cfc4e2 2003-09-30 devnull returns immediately).
462 058b0118 2005-01-03 devnull element in the
463 058b0118 2005-01-03 devnull .B Channel
464 058b0118 2005-01-03 devnull structure is a description intended for use in debugging.
465 058b0118 2005-01-03 devnull .I Chansetname
466 058b0118 2005-01-03 devnull sets the name.
469 b2cfc4e2 2003-09-30 devnull sends the element pointed at by
471 b2cfc4e2 2003-09-30 devnull to the channel
475 b2cfc4e2 2003-09-30 devnull is null, zeros are sent.
477 b2cfc4e2 2003-09-30 devnull receives an element from
479 b2cfc4e2 2003-09-30 devnull and stores it in
483 b2cfc4e2 2003-09-30 devnull is null,
484 b2cfc4e2 2003-09-30 devnull the received value is discarded.
488 b2cfc4e2 2003-09-30 devnull return 1 on success, \-1 if interrupted.
489 b2cfc4e2 2003-09-30 devnull .I Nbsend
491 b2cfc4e2 2003-09-30 devnull .I nbrecv
492 b2cfc4e2 2003-09-30 devnull behave similarly, but return 0 rather than blocking.
494 b2cfc4e2 2003-09-30 devnull .IR Sendp ,
495 b2cfc4e2 2003-09-30 devnull .IR nbsendp ,
496 b2cfc4e2 2003-09-30 devnull .IR sendul ,
498 b2cfc4e2 2003-09-30 devnull .I nbsendul
499 b2cfc4e2 2003-09-30 devnull send a pointer or an unsigned long; the channel must
500 b2cfc4e2 2003-09-30 devnull have been initialized with the appropriate
501 b2cfc4e2 2003-09-30 devnull .IR elsize .
502 b2cfc4e2 2003-09-30 devnull .IR Recvp ,
503 b2cfc4e2 2003-09-30 devnull .IR nbrecvp ,
504 b2cfc4e2 2003-09-30 devnull .IR recvul ,
506 b2cfc4e2 2003-09-30 devnull .I nbrecvul
507 b2cfc4e2 2003-09-30 devnull receive a pointer or an unsigned long;
508 b2cfc4e2 2003-09-30 devnull they return zero when a zero is received,
509 b2cfc4e2 2003-09-30 devnull when interrupted, or
511 b2cfc4e2 2003-09-30 devnull .I nbrecvp
513 b2cfc4e2 2003-09-30 devnull .IR nbrecvul )
514 b2cfc4e2 2003-09-30 devnull when the operation would have blocked.
515 b2cfc4e2 2003-09-30 devnull To distinguish between these three cases,
519 b2cfc4e2 2003-09-30 devnull .IR nbrecv .
522 b2cfc4e2 2003-09-30 devnull can be used to recv from or send to one of a number of channels,
523 b2cfc4e2 2003-09-30 devnull as directed by an array of
525 b2cfc4e2 2003-09-30 devnull structures,
526 b2cfc4e2 2003-09-30 devnull each of which describes a potential send or receive operation.
529 b2cfc4e2 2003-09-30 devnull structure,
531 b2cfc4e2 2003-09-30 devnull is the channel;
533 b2cfc4e2 2003-09-30 devnull the value pointer (which may be null); and
535 b2cfc4e2 2003-09-30 devnull the operation:
536 b2cfc4e2 2003-09-30 devnull .B CHANSND
537 b2cfc4e2 2003-09-30 devnull for a send operation,
538 b2cfc4e2 2003-09-30 devnull .B CHANRECV
539 b2cfc4e2 2003-09-30 devnull for a recv operation;
540 b2cfc4e2 2003-09-30 devnull .B CHANNOP
541 b2cfc4e2 2003-09-30 devnull for no operation
545 b2cfc4e2 2003-09-30 devnull is called with a varying set of operations).
546 b2cfc4e2 2003-09-30 devnull The array of
548 b2cfc4e2 2003-09-30 devnull structures is terminated by an entry with
550 b2cfc4e2 2003-09-30 devnull .B CHANEND
552 b2cfc4e2 2003-09-30 devnull .BR CHANNOBLK .
553 b2cfc4e2 2003-09-30 devnull If at least one
555 b2cfc4e2 2003-09-30 devnull structure can proceed, one of them is
556 b2cfc4e2 2003-09-30 devnull chosen at random to be executed.
558 b2cfc4e2 2003-09-30 devnull returns the index of the chosen structure.
559 b2cfc4e2 2003-09-30 devnull If no operations can proceed and the list is terminated with
560 b2cfc4e2 2003-09-30 devnull .BR CHANNOBLK ,
562 b2cfc4e2 2003-09-30 devnull returns the index of the terminating
563 b2cfc4e2 2003-09-30 devnull .B CHANNOBLK
564 b2cfc4e2 2003-09-30 devnull structure.
565 b2cfc4e2 2003-09-30 devnull Otherwise,
567 b2cfc4e2 2003-09-30 devnull blocks until one of the operations can proceed,
568 b2cfc4e2 2003-09-30 devnull eventually returning the index of the structure executes.
570 b2cfc4e2 2003-09-30 devnull returns \-1 when interrupted.
574 b2cfc4e2 2003-09-30 devnull .B entryno
575 b2cfc4e2 2003-09-30 devnull fields in the
577 b2cfc4e2 2003-09-30 devnull structure are used internally by
579 b2cfc4e2 2003-09-30 devnull and need not be initialized.
580 b2cfc4e2 2003-09-30 devnull They are not used between
584 b2cfc4e2 2003-09-30 devnull .I Chanprint
585 b2cfc4e2 2003-09-30 devnull formats its arguments in the manner of
586 bf8a59fa 2004-04-11 devnull .IR print (3)
587 b2cfc4e2 2003-09-30 devnull and sends the result to the channel
589 b2cfc4e2 2003-09-30 devnull The string delivered by
590 b2cfc4e2 2003-09-30 devnull .I chanprint
591 b2cfc4e2 2003-09-30 devnull is allocated with
592 bf8a59fa 2004-04-11 devnull .IR malloc (3)
593 b2cfc4e2 2003-09-30 devnull and should be freed upon receipt.
595 b2cfc4e2 2003-09-30 devnull Thread library functions do not return on failure;
596 b2cfc4e2 2003-09-30 devnull if errors occur, the entire program is aborted.
598 b2cfc4e2 2003-09-30 devnull Threaded programs should use
599 b2cfc4e2 2003-09-30 devnull .I threadnotify
600 b2cfc4e2 2003-09-30 devnull in place of
601 b2cfc4e2 2003-09-30 devnull .I atnotify
603 bf8a59fa 2004-04-11 devnull .IR notify (3)).
605 b2cfc4e2 2003-09-30 devnull It is safe to use
606 058b0118 2005-01-03 devnull .IR sysfatal (3)
607 b2cfc4e2 2003-09-30 devnull in threaded programs.
608 b2cfc4e2 2003-09-30 devnull .I Sysfatal
609 b2cfc4e2 2003-09-30 devnull will print the error string and call
610 b2cfc4e2 2003-09-30 devnull .IR threadexitsall .
612 058b0118 2005-01-03 devnull It is not safe to call
613 b2cfc4e2 2003-09-30 devnull .IR rfork
614 058b0118 2005-01-03 devnull in a threaded program, except to call
615 058b0118 2005-01-03 devnull .B rfork(RFNOTEG)
616 058b0118 2005-01-03 devnull from the main proc before any other procs have been created.
617 058b0118 2005-01-03 devnull To create new processes, use
618 058b0118 2005-01-03 devnull .IR proccreate .
620 058b0118 2005-01-03 devnull .\" It is safe to use
621 058b0118 2005-01-03 devnull .\" .IR rfork
622 058b0118 2005-01-03 devnull .\" (see
623 058b0118 2005-01-03 devnull .\" .IR fork (3))
624 058b0118 2005-01-03 devnull .\" to manage the namespace, file descriptors, note group, and environment of a
625 058b0118 2005-01-03 devnull .\" single process.
626 058b0118 2005-01-03 devnull .\" That is, it is safe to call
627 058b0118 2005-01-03 devnull .\" .I rfork
628 058b0118 2005-01-03 devnull .\" with the flags
629 058b0118 2005-01-03 devnull .\" .BR RFNAMEG ,
630 058b0118 2005-01-03 devnull .\" .BR RFFDG ,
631 058b0118 2005-01-03 devnull .\" .BR RFCFDG ,
632 058b0118 2005-01-03 devnull .\" .BR RFNOTEG ,
633 058b0118 2005-01-03 devnull .\" .BR RFENVG ,
635 058b0118 2005-01-03 devnull .\" .BR RFCENVG.
636 058b0118 2005-01-03 devnull .\" (To create new processes, use
637 058b0118 2005-01-03 devnull .\" .I proccreate
639 058b0118 2005-01-03 devnull .\" .IR procrfork .)
640 058b0118 2005-01-03 devnull .\" As mentioned above,
641 058b0118 2005-01-03 devnull .\" the thread library depends on all procs being in the
642 058b0118 2005-01-03 devnull .\" same rendezvous group; do not change the rendezvous
643 058b0118 2005-01-03 devnull .\" group with
644 058b0118 2005-01-03 devnull .\" .IR rfork .
645 b2cfc4e2 2003-09-30 devnull .SH FILES
646 c3674de4 2005-01-11 devnull .B \*9/acid/thread
647 b2cfc4e2 2003-09-30 devnull contains useful
648 b2cfc4e2 2003-09-30 devnull .IR acid (1)
649 b2cfc4e2 2003-09-30 devnull functions for debugging threaded programs.
651 c3674de4 2005-01-11 devnull .B \*9/src/libthread/test
652 058b0118 2005-01-03 devnull contains some example programs.
653 b2cfc4e2 2003-09-30 devnull .SH SOURCE
654 c3674de4 2005-01-11 devnull .B \*9/src/libthread
655 b2cfc4e2 2003-09-30 devnull .SH SEE ALSO
656 bf8a59fa 2004-04-11 devnull .IR intro (3),
657 bf8a59fa 2004-04-11 devnull .IR ioproc (3)
658 058b0118 2005-01-03 devnull .SH BUGS
659 058b0118 2005-01-03 devnull A program that intends to use the thread library
660 058b0118 2005-01-03 devnull but does not call any of its functions will not cause Unix linkers
661 058b0118 2005-01-03 devnull to link the thread library, resulting in the unintelligible error:
664 c3674de4 2005-01-11 devnull \*9/lib/lib9.a(main.o)(.text+0x17): In function `main':
665 c3674de4 2005-01-11 devnull \*9/src/lib9/main.c:10: undefined reference to `p9main'
668 058b0118 2005-01-03 devnull or similar. To force the thread library to be linked properly in such cases,
669 058b0118 2005-01-03 devnull insert a call to the no-op function
670 058b0118 2005-01-03 devnull .I threadlinklibrary
671 058b0118 2005-01-03 devnull somewhere in your program.
673 058b0118 2005-01-03 devnull To avoid name conflicts,
674 058b0118 2005-01-03 devnull .IR alt ,
675 058b0118 2005-01-03 devnull .IR nbrecv ,
676 058b0118 2005-01-03 devnull .IR nbrecvp ,
677 058b0118 2005-01-03 devnull .IR nbrecvul ,
678 058b0118 2005-01-03 devnull .IR nbsend ,
679 058b0118 2005-01-03 devnull .IR nbsendp ,
680 058b0118 2005-01-03 devnull .IR nbsendul ,
681 058b0118 2005-01-03 devnull .IR recv ,
682 058b0118 2005-01-03 devnull .IR recvp ,
683 058b0118 2005-01-03 devnull .IR recvul ,
684 058b0118 2005-01-03 devnull .IR send ,
685 058b0118 2005-01-03 devnull .IR sendp ,
687 058b0118 2005-01-03 devnull .IR sendul
688 058b0118 2005-01-03 devnull are defined as macros that expand to
689 058b0118 2005-01-03 devnull .IR chanalt ,
690 058b0118 2005-01-03 devnull .IR channbrecv ,
691 058b0118 2005-01-03 devnull and so on.
692 058b0118 2005-01-03 devnull Similarly,
693 058b0118 2005-01-03 devnull .I yield
694 058b0118 2005-01-03 devnull is defined as a macro that expands to
695 058b0118 2005-01-03 devnull .IR threadyield .
697 058b0118 2005-01-03 devnull The implementation of
698 058b0118 2005-01-03 devnull .I threadnotify
699 058b0118 2005-01-03 devnull may not be correct.
