Merge remote-tracking branch 'upstream/master'HEADmaster

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