aboutsummaryrefslogtreecommitdiff
path: root/man/man3
diff options
context:
space:
mode:
authorPetter Rodhelind <petter.rodhelind@gmail.com>2021-02-18 20:21:24 +0100
committerPetter Rodhelind <petter.rodhelind@gmail.com>2021-02-18 20:21:24 +0100
commit181d56ee64da53279bb6ecf49c24ab54cfb7193f (patch)
treefc6c8736bb97790a257c5514998c583ffce7c41c /man/man3
parent94c521bf102a74aec7e1a5c3a9ef5eaa968d4e14 (diff)
parent90971376a5e8620fc62579aa1b3be26245ec8c06 (diff)
downloadplan9port-master.tar.gz
plan9port-master.tar.bz2
plan9port-master.zip
Merge remote-tracking branch 'upstream/master'HEADmaster
Diffstat (limited to 'man/man3')
-rw-r--r--man/man3/thread.366
1 files changed, 35 insertions, 31 deletions
diff --git a/man/man3/thread.3 b/man/man3/thread.3
index 6c6b4602..c0a59091 100644
--- a/man/man3/thread.3
+++ b/man/man3/thread.3
@@ -33,6 +33,7 @@ threadintgrp,
threadkill,
threadkillgrp,
threadmain,
+threadmaybackground,
threadnotify,
threadid,
threadpid,
@@ -80,6 +81,7 @@ struct Alt {
.ft L
.ta \w'\fLChannel* 'u +4n +4n +4n +4n
void threadmain(int argc, char *argv[])
+int threadmaybackground(void)
int mainstacksize
int proccreate(void (*fn)(void*), void *arg, uint stacksize)
int threadcreate(void (*fn)(void*), void *arg, uint stacksize)
@@ -156,27 +158,21 @@ by
The thread library provides a
.I main
function that sets up a proc with a single thread executing
-.I threadmain
-on a stack of size
-.I mainstacksize
-(default eight kilobytes).
-To set
-.IR mainstacksize ,
-declare a global variable
-initialized to the desired value
-.RI ( e.g. ,
-.B int
-.B mainstacksize
-.B =
-.BR 1024 ).
-When using the
+.IR threadmain .
+.PP
+Every thread is backed by an operating system-provided
.I pthread
-library,
-.B mainstacksize
-is ignored, as is the stack size argument to
-.BR proccreate :
-the first thread in each proc
-runs on the native system stack.
+and runs on its system-provided stack;
+.I mainstacksize
+and the the stack size arguments to
+.I proccreate
+and
+.I threadcreate
+are ignored.
+Although each thread is backed by a separate
+.IR pthread ,
+the threads in a proc are still scheduled non-preemptively
+as on Plan 9 and as described below.
.PP
.I Threadcreate
creates a new thread in the calling proc, returning a unique integer
@@ -185,7 +181,7 @@ executes
.I fn(arg)
on a stack of size
.IR stacksize .
-Thread stacks are allocated in shared memory, making it valid to pass
+Thread stacks are allocated in shared memory, making it valid to pass
pointers to stack variables between threads and procs.
.I Proccreate
creates a new proc, and inside that proc creates
@@ -207,7 +203,7 @@ returning the id of the created thread.
.\" in
.\" .IR rforkflag .)
.\" .I Proccreate
-.\" is identical to
+.\" is identical to
.\" .I procrfork
.\" with
.\" .I rforkflag
@@ -238,6 +234,14 @@ When the last thread in
.IR 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.
+This functionality can only be relied upon if the program defines a function
+.I threadmaybackground
+returning a non-zero result.
+Programs that do not define such a
+.I threadmaybackground
+will crash instead should the last thread in
+.IR threadmain 's
+proc exit leaving behind other running procs.
.PP
The threads in a proc are coroutines, scheduled nonpreemptively
in a round-robin fashion.
@@ -341,18 +345,18 @@ Also for debugging,
threads have a string state associated with them.
.I Threadsetstate
sets the state string.
-There is no
+There is no
.IR threadgetstate ;
since the thread scheduler resets the state to
.B Running
-every time it runs the thread,
+every time it runs the thread,
it is only useful for debuggers to inspect the state.
.PP
.I Threaddata
returns a pointer to a per-thread pointer
that may be modified by threaded programs for
per-thread storage.
-Similarly,
+Similarly,
.I procdata
returns a pointer to a per-proc pointer.
.PP
@@ -398,11 +402,11 @@ response.
.I Threadexecl
and
.I threadexec
-will duplicate
+will duplicate
(see
.MR dup (3) )
the three file descriptors in
-.I fd
+.I fd
onto standard input, output, and error for the external program
and then close them in the calling thread.
Beware of code that sets
@@ -467,9 +471,9 @@ operation blocks until the corresponding
operation occurs and
.IR "vice versa" .
.IR Chancreate
-allocates a new channel
+allocates a new channel
for messages of size
-.I elsize
+.I elsize
and with a buffer holding
.I nel
messages.
@@ -645,7 +649,7 @@ from the main proc before any other procs have been created.
To create new processes, use
.IR proccreate .
.\" .PP
-.\" It is safe to use
+.\" It is safe to use
.\" .IR rfork
.\" (see
.\" .IR fork (3))
@@ -663,7 +667,7 @@ To create new processes, use
.\" .BR RFCENVG.
.\" (To create new processes, use
.\" .I proccreate
-.\" and
+.\" and
.\" .IR procrfork .)
.\" As mentioned above,
.\" the thread library depends on all procs being in the