[Openmcl-cvs-notifications] r10163 - /trunk/source/doc/src/threads.xml

[gb at clozure.com]

Author: gb
Date: Sat Jul 19 20:08:07 2008
New Revision: 10163

Log:
Add a section for JOIN-PROCESS (ticket:316)
Not really a documentation issue: a thread's termination-semaphore
can apparently be signaled twice (once when the lisp code is exiting
and again in the kernel), making the issue of "how many other threads
can reliably wait for thread termination" a confusing one.

Modified:
    trunk/source/doc/src/threads.xml

Modified: trunk/source/doc/src/threads.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- trunk/source/doc/src/threads.xml (original)
+++ trunk/source/doc/src/threads.xml Sat Jul 19 20:08:07 2008
@@ -1740,7 +1740,7 @@
 	    <title>See Also</title>
 	    =

 	    <simplelist type=3D"inline">
-	      <member><xref linkend=3D"f_process-wait-with-timeout"/></member>
+<	      <member><xref linkend=3D"f_process-wait-with-timeout"/></member>
 	    </simplelist>
 	  </refsect1>
     </refentry>
@@ -2019,7 +2019,7 @@
 	      <xref linkend=3D"f_process-wait"/>, except for returning T.
 	      Otherwise, <varname>function</varname> will be tested repeatedly,
 	      in the same
-	      kind of test/yield loop as in <xref linkend=3D"f_process-wait"/>>
+	      kind of test/yield loop as in <xref linkend=3D"f_process-wait"/>
 	      until either <varname>function</varname> returns true,
 	      or the duration <varname>ticks</varname> has been exceeded.
 	    </para>
@@ -3257,5 +3257,70 @@
 	  </refsect1>
     </refentry>
 =

+    <refentry id=3D"f_join-process">
+      <indexterm zone=3D"f_join-process">
+	<primary>join-process</primary>
+      </indexterm>
+
+      <refnamediv>
+	<refname>JOIN-PROCESS</refname>
+	<refpurpose>Waits for a specified process to complete and
+	returns the values that that process's initial function
+	returned.</refpurpose>
+	<refclass>Function</refclass>
+      </refnamediv>
+
+      <refsynopsisdiv>
+	<synopsis><function>join-process</function> process
+	&optional; default =3D> values</synopsis>
+      </refsynopsisdiv>
+      =

+      <refsect1>
+	<title>Arguments and Values</title>
+
+	<variablelist>
+	  <varlistentry>
+	    <term>process</term>
+	    <listitem>
+	      <para>a process, typically created by <xref
+	      linkend=3D"f_process-run-function"/> or by <xref
+	      linkend=3D"f_make-process"/></para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>default</term>
+	    <listitem>
+	      <para>A default value to be returned if the specified
+	      process doesn't exit normally.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>values</term>
+	    <listitem>
+	      <para>The values returned by the specified process's
+	      initial function if that function returns, or the value
+	      of the default argument, otherwise.</para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </refsect1>
+
+      <refsect1>
+	<title>Description</title>
+	<para>Waits for the specified process to terminate.  If the
+	process terminates "normally" (if its initial function
+	returns), returns the values that that initial function
+	returnes.  If the process does not terminate normally (e.g.,
+	if it's terminated via <xref linkend=3D"f_process-kill"/> and a
+	default argument is provided, returns the value of that
+	default argument.  If the process doesn't terminate normally
+	and no default argument is provided, signals an error.</para>
+	=

+	<para>A process can't successfully join itself, and only one
+	process can successfully receive notification of another process's
+	termination.</para>
+      </refsect1>
+    </refentry>
+
   </sect1>
 </chapter>