Changeset 8520


Ignore:
Timestamp:
Feb 20, 2008, 2:18:19 PM (12 years ago)
Author:
gb
Message:

valid XML. Buggy, incomplete, valid XML

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/source/doc/src/openmcl-documentation.xml

    r8516 r8520  
    11<?xml version="1.0" encoding="US-ASCII"?>
    22<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
    3 <!ENTITY rest "<varname><property>&amp;rest</property></varname>">
    4 <!ENTITY key "<varname><property>&amp;key</property></varname>">
    5 <!ENTITY optional "<varname><property>&amp;optional</property></varname>">
    6 <!ENTITY body "<varname><property>&amp;body</property></varname>">
    7 <!ENTITY aux "<varname><property>&amp;aux</property></varname>">
    8 <!ENTITY allow-other-keys
    9          "<varname><property>&amp;allow-other-keys</property></varname>">
     3<!ENTITY rest "<varname>&amp;rest</varname>">
     4<!ENTITY key "<varname>&amp;key</varname>">
     5<!ENTITY optional "<varname>&amp;optional</varname>">
     6<!ENTITY body "<varname>&amp;body</varname>">
     7<!ENTITY aux "<varname>&amp;aux</varname>">
     8<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    109]>
    1110<book lang="en">
     
    10741073        <programlisting>
    10751074$ cd ccl                        # wherever your ccl directory is
    1076 $ ./<replaceable><kernel&gt; <boot_image&gt;</replaceable>
     1075$ ./KERNEL BOOT_IMAGE
    10771076        </programlisting>
    1078         <para>Where <replaceable><kernel&gt;</replaceable> and
    1079         <replaceable><boot_image&gt;</replaceable> are the names of
     1077        <para>Where <replaceable>KERNEL</replaceable> and
     1078        <replaceable>BOOT_IMAGE</replaceable> are the names of
    10801079        the kernel and boot image appropriate to the platform you are
    10811080        running on.  See FIXTHIS</para>
     
    12921291      scheduler may be less portable to other CL implementations, many
    12931292      of which offer a cooperative scheduler and an API similar to
    1294       OpenMCL (< 0.14) 's.) At the same time, there's a large
     1293      OpenMCL (&lt; 0.14) 's.) At the same time, there's a large
    12951294      overlap in functionality in the two scheduling models, and it'll
    12961295      hopefully be possible to write interesting and useful MP code
     
    14761475
    14771476? (process-run-function "sleeper" #'(lambda () (sleep 5) (break "broken")))
    1478 #<PROCESS sleeper(1) [Enabled] #x3063B33E&gt;
     1477#&lt;PROCESS sleeper(1) [Enabled] #x3063B33E&gt;
    14791478
    14801479?
     
    14951494;;
    14961495> Break in process sleeper(1): broken
    1497 > While executing: #<Anonymous Function #x3063B276&gt;
     1496> While executing: #&lt;Anonymous Function #x3063B276&gt;
    14981497> Type :GO to continue, :POP to abort.
    14991498> If continued: Return from BREAK.
    15001499Type :? for other options.
    1501 1 > :b
     15001 &gt; :b
    15021501(30C38E30) : 0 "Anonymous Function #x3063B276" 52
    15031502(30C38E40) : 1 "Anonymous Function #x304984A6" 376
     
    15231522
    15241523? (process-run-function "sleep-60" #'(lambda () (sleep 60) (break "Huh?")))
    1525 #<PROCESS sleep-60(1) [Enabled] #x3063BF26&gt;
     1524#&lt;PROCESS sleep-60(1) [Enabled] #x3063BF26&gt;
    15261525
    15271526? (process-run-function "sleep-5" #'(lambda () (sleep 5) (break "quicker")))
    1528 #<PROCESS sleep-5(2) [Enabled] #x3063D0A6&gt;
     1527#&lt;PROCESS sleep-5(2) [Enabled] #x3063D0A6&gt;
    15291528
    15301529? ;;
     
    16021601
    16031602    <sect1 id="The-Threads-which-OpenMCL-Uses-for-Its-Own-Purposes">
    1604       <para>The Threads which OpenMCL Uses for Its Own Purposes
     1603      <title>The Threads which OpenMCL Uses for Its Own Purposes</title>
     1604      <para>
    16051605In the "tty world", OpenMCL starts out with 2 lisp-level threads:</para>
    16061606      <programlisting>
     
    17231723    <sect1 id="Threads-Dictionary">
    17241724      <title>Threads Dictionary</title>
    1725 
    17261725      <refentry id="f_all-processes">
    17271726        <indexterm zone="f_all-processes">
     
    17591758
    17601759          <para>Returns a list of all lisp processes (threads) known
    1761           to OpenMCL as of the precise instant it&#39;s
    1762           called. It&#39;s safe to traverse this list and to modify
    1763           the cons cells that comprise that list (it&#39;s freshly
    1764           consed.) Since other threads can create and kill threads at
    1765           any time, there&#39;s generally no way to get an
     1760          to OpenMCL as of
     1761          the precise instant it&#39;s called. It&#39;s safe to traverse
     1762          this list and to modify the cons cells that comprise that list
     1763          (it&#39;s freshly consed.) Since other threads can create and kill
     1764          threads at any time, there&#39;s generally no way to get an
    17661765          &#34;accurate&#34; list of all threads, and (generally) no
    17671766          sense in which such a list can be accurate.</para>
     
    17771776      </refentry>
    17781777
    1779 
    1780        <refentry id="f_make-process">
     1778      <refentry id="f_make-process">
    17811779        <indexterm zone="f_make-process">
    17821780          <primary>make-process</primary>
     
    19451943      </refentry>
    19461944
    1947       <sect2 id="PROCESS-SUSPEND">
    1948         <para>PROCESS-SUSPEND</para>
    1949         <informalfigure>process-suspend</informalfigure>
    1950         <bridgehead renderas="sect3">Name</bridgehead>
    1951         <para>PROCESS-SUSPEND &mdash; Suspends a specified process.</para>
    1952         <para>Function</para>
    1953         <bridgehead renderas="sect3">Synopsis</bridgehead>
    1954         <programlisting>
    1955 process-suspend process
    1956           => result
    1957 </programlisting>
    1958         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    1959         <term><indexterm>process
    1960             <variablelist>a lisp process (thread).</variablelist>
    1961           </indexterm><indexterm>result
    1962             <variablelist>T if <literal>process</literal> had been runnableand is now suspended; NIL otherwise.  That is, T if<literal>process</literal>'stransitioned from 0 to 1.</variablelist>
    1963           </indexterm>
    1964         </term>
    1965         <bridgehead renderas="sect3">Description</bridgehead>
    1966         <para>Suspends <literal>process</literal>, preventing it from
    1967 running, and stopping it if it was already running. This is a fairly
    1968 expensive operation, because it involves a few
    1969 calls to the OS.  It also risks creating deadlock if used
    1970 improperly, for instance, if the process being suspended owns a
    1971 lock or other resource which another process will wait for.</para>
    1972         <para>Each
    1973 call to <literal>process-suspend</literal> must be reversed by
    1974 a matching call to
    1975 before <literal>process</literal> is able to run.  What
    1976 <literal>process-suspend</literal> actually does is increment
    1977 the  of
    1978 <literal>process</literal>.</para>
    1979         <para>A process cannot suspend itself (although that was possible in
    1980 some older OpenMCL releases and this documentation claimed that
    1981 it still was.)</para>
    1982         <bridgehead renderas="sect3">See Also</bridgehead>
    1983         <para role="continues">,</para>
    1984         <bridgehead renderas="sect3">Notes</bridgehead>
    1985         <para><literal>process-suspend</literal> was previously called
    1986 <literal>process-disable</literal>.</para>
    1987         <para>now names a function for which there is no
    1988 obvious inverse, so <literal>process-disable</literal>
    1989 is no longer
    1990 defined.</para>
    1991       </sect2>
    1992 
    1993       <sect2 id="PROCESS-RESUME">
    1994         <para>PROCESS-RESUME</para>
    1995         <informalfigure>process-resume</informalfigure>
    1996         <bridgehead renderas="sect3">Name</bridgehead>
    1997         <para>PROCESS-RESUME &mdash; Resumes a specified process which had previously
    1998 been suspended by process-suspend.</para>
    1999         <para>Function</para>
    2000         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2001         <programlisting>
    2002 process-resume process
    2003           => result
    2004 </programlisting>
    2005         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2006         <term><indexterm>process
    2007             <variablelist>a lisp process (thread).</variablelist>
    2008           </indexterm><indexterm>result
    2009             <variablelist>T if <literal>process</literal> had been suspendedand is now runnable; NIL otherwise.  That is, T if<literal>process</literal>'stransitioned from  to 0.</variablelist>
    2010           </indexterm>
    2011         </term>
    2012         <bridgehead renderas="sect3">Description</bridgehead>
    2013         <para>Undoes the effect of a previous call to
    2014 ; if
    2015 all such calls are undone, makes the process runnable. Has no
    2016 effect if the process is not suspended.  What
    2017 <literal>process-resume</literal> actually does is decrement
    2018 the  of
    2019 <literal>process</literal>, to a minimum of 0.</para>
    2020         <bridgehead renderas="sect3">See Also</bridgehead>
    2021         <para role="continues">,</para>
    2022         <bridgehead renderas="sect3">Notes</bridgehead>
    2023         <para>This was previously called PROCESS-ENABLE;
    2024  now does something slightly
    2025 different.</para>
    2026       </sect2>
    2027 
    2028       <sect2 id="PROCESS-SUSPEND-COUNT">
    2029         <para>PROCESS-SUSPEND-COUNT</para>
    2030         <informalfigure>process-suspend-count</informalfigure>
    2031         <bridgehead renderas="sect3">Name</bridgehead>
    2032         <para>PROCESS-SUSPEND-COUNT &mdash; Returns the number of currently-pending suspensions
    2033 applicable to a given process.</para>
    2034         <para>Function</para>
    2035         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2036         <programlisting>
    2037 
    2038             process-suspend-count
     1945      <refentry id="f_process-suspend">
     1946        <indexterm zone="f_process-suspend">
     1947          <primary>process-suspend</primary>
     1948        </indexterm>
     1949
     1950        <refnamediv>
     1951          <refname>PROCESS-SUSPEND</refname>
     1952          <refpurpose>Suspends a specified process.</refpurpose>
     1953          <refclass>Function</refclass>
     1954        </refnamediv>
     1955       
     1956        <refsynopsisdiv>
     1957          <synopsis><function>process-suspend</function> process
     1958          => result</synopsis>
     1959        </refsynopsisdiv>
     1960
     1961        <refsect1>
     1962          <title>Arguments and Values</title>
     1963         
     1964          <variablelist>
     1965            <varlistentry>
     1966              <term>process</term>
     1967              <listitem>
     1968                <para>a lisp process (thread).</para>
     1969              </listitem>
     1970            </varlistentry>
     1971            <varlistentry>
     1972              <term>result</term>
     1973              <listitem>
     1974                <para>T if <varname>process</varname> had been runnable
     1975                and is now suspended; NIL otherwise.  That is, T if
     1976                <varname>process</varname>'s
     1977                <xref linkend="f_process-suspend-count"/>
     1978                transitioned from 0 to 1.</para>
     1979              </listitem>
     1980            </varlistentry>
     1981          </variablelist>
     1982        </refsect1>
     1983
     1984        <refsect1>
     1985          <title>Description</title>
     1986
     1987          <para>Suspends <varname>process</varname>, preventing it from
     1988          running, and stopping it if it was already running. This is a fairly
     1989          expensive operation, because it involves a few
     1990          calls to the OS.  It also risks creating deadlock if used
     1991          improperly, for instance, if the process being suspended owns a
     1992          lock or other resource which another process will wait for.</para>
     1993
     1994          <para>
     1995          Each
     1996          call to <function>process-suspend</function> must be reversed by
     1997          a matching call to <xref linkend="f_process-resume"/>
     1998          before <varname>process</varname> is able to run.  What
     1999          <function>process-suspend</function> actually does is increment
     2000          the <xref linkend="f_process-suspend-count"/> of
     2001          <varname>process</varname>.
     2002          </para>
     2003
     2004          <para>A process can suspend itself; it it&#39;s successful in doing
     2005          so, then it can obviously only be resumed by some other
     2006          process.</para>
     2007        </refsect1>
     2008
     2009        <refsect1>
     2010          <title>See Also</title>
     2011         
     2012          <simplelist type="inline">
     2013            <member><xref linkend="f_process-resume"/></member>
     2014            <member><xref linkend="f_process-suspend-count"/></member>
     2015          </simplelist>
     2016        </refsect1>
     2017
     2018        <refsect1>
     2019          <title>Notes</title>
     2020          <para><function>process-suspend</function> was previously called
     2021          <function>process-disable</function>.
     2022          <xref linkend="f_process-enable"/>
     2023          now names a function for which there is no
     2024          obvious inverse, so <function>process-disable</function>
     2025          is no longer
     2026          defined.</para>
     2027        </refsect1>
     2028      </refentry>
     2029
     2030      <refentry id="f_process-resume">
     2031        <indexterm zone="f_process-resume">
     2032          <primary>process-resume</primary>
     2033        </indexterm>
     2034
     2035        <refnamediv>
     2036          <refname>PROCESS-RESUME</refname>
     2037          <refpurpose>Resumes a specified process which had previously
     2038          been suspended by process-suspend.</refpurpose>
     2039          <refclass>Function</refclass>
     2040        </refnamediv>
     2041
     2042        <refsynopsisdiv>
     2043          <synopsis><function>process-resume</function> process
     2044          => result</synopsis>
     2045        </refsynopsisdiv>
     2046
     2047        <refsect1>
     2048          <title>Arguments and Values</title>
     2049         
     2050          <variablelist>
     2051            <varlistentry>
     2052              <term>process</term>
     2053              <listitem>
     2054                <para>a lisp process (thread).</para>
     2055              </listitem>
     2056            </varlistentry>
     2057            <varlistentry>
     2058              <term>result</term>
     2059              <listitem>
     2060                <para>T if <varname>process</varname> had been suspended
     2061                and is now runnable; NIL otherwise.  That is, T if
     2062                <varname>process</varname>'s
     2063                <xref linkend="f_process-suspend-count"/>
     2064                transitioned from  to 0.
     2065                </para>
     2066              </listitem>
     2067            </varlistentry>
     2068          </variablelist>
     2069        </refsect1>
     2070
     2071        <refsect1>
     2072          <title>Description</title>
     2073
     2074          <para>Undoes the effect of a previous call to
     2075          <xref linkend="f_process-suspend"/>; if
     2076          all such calls are undone, makes the process runnable. Has no
     2077          effect if the process is not suspended.  What
     2078          <function>process-resume</function> actually does is decrement
     2079          the <xref linkend="f_process-suspend-count"/> of
     2080          <varname>process</varname>, to a minimum of 0.</para>
     2081        </refsect1>
     2082
     2083        <refsect1>
     2084          <title>See Also</title>
     2085         
     2086          <simplelist type="inline">
     2087            <member><xref linkend="f_process-suspend"/></member>
     2088            <member><xref linkend="f_process-suspend-count"/></member>
     2089          </simplelist>
     2090        </refsect1>
     2091
     2092        <refsect1>
     2093          <title>Notes</title>
     2094
     2095          <para>
     2096            This was previously called PROCESS-ENABLE;
     2097            <xref linkend="f_process-enable"/> now does something slightly
     2098            different.
     2099          </para>
     2100        </refsect1>
     2101      </refentry>
     2102
     2103      <refentry id="f_process-suspend-count">
     2104        <indexterm zone="f_process-suspend-count">
     2105          <primary>process-suspend-count</primary>
     2106        </indexterm>
     2107
     2108        <refnamediv>
     2109          <refname>PROCESS-SUSPEND-COUNT</refname>
     2110          <refpurpose>Returns the number of currently-pending suspensions
     2111          applicable to a given process.</refpurpose>
     2112          <refclass>Function</refclass>
     2113        </refnamediv>
     2114
     2115        <refsynopsisdiv>
     2116          <synopsis>
     2117            <function>process-suspend-count</function>
    20392118            process => result
    2040 
    2041 </programlisting>
    2042         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2043         <term><indexterm>process
    2044             <variablelist>a lisp process (thread).</variablelist>
    2045           </indexterm><indexterm>result
    2046             <variablelist>The number of "outstanding" calls on<literal>process</literal>, or NIL if<literal>process</literal> has expired.</variablelist>
    2047           </indexterm>
    2048         </term>
    2049         <bridgehead renderas="sect3">Description</bridgehead>
    2050         <para>An "outstanding"  call
    2051 is one which has not yet been reversed by a call to
    2052 .  A process expires when
    2053 its initial function returns, although it may later be
    2054 reset.</para>
    2055         <para>A process is <emphasis>runnable</emphasis> when it has a
    2056 <literal>process-suspend-count</literal> of 0, has been
    2057 preset as by , and has been
    2058 enabled as by .  Newly-created
    2059 processes have a <literal>process-suspend-count</literal> of
    2060 0.</para>
    2061         <bridgehead renderas="sect3">See Also</bridgehead>
    2062         <para role="continues">,</para>
    2063       </sect2>
    2064 
    2065       <sect2 id="PROCESS-PRESET">
    2066         <para>PROCESS-PRESET</para>
    2067         <informalfigure>process-preset</informalfigure>
    2068         <bridgehead renderas="sect3">Name</bridgehead>
    2069         <para>PROCESS-PRESET &mdash; Sets the initial function and arguments of a specified
    2070 process.</para>
    2071         <para>Function</para>
    2072         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2073         <programlisting>
    2074 process-preset
    2075           process function &amp;rest args
    2076           => result
    2077 </programlisting>
    2078         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2079         <term><indexterm>process
    2080             <variablelist>a lisp process (thread).</variablelist>
    2081           </indexterm><indexterm>function
    2082             <variablelist>a function, designated by itself or by a symbolwhich names it.</variablelist>
    2083           </indexterm><indexterm>args
    2084             <variablelist>a list of values, appropriate as arguments to<literal>function</literal>.</variablelist>
    2085           </indexterm><indexterm>result
    2086             <variablelist>undefined.</variablelist>
    2087           </indexterm>
    2088         </term>
    2089         <bridgehead renderas="sect3">Description</bridgehead>
    2090         <para>Typically used to initialize a newly-created or newly-reset
    2091 process, setting things up so that when <literal>process</literal>
    2092 becomes enabled, it will begin execution by
    2093 applying <literal>function</literal> to <literal>args</literal>.
    2094 <literal>process-preset</literal> does not enable
    2095 <literal>process</literal>,
    2096 although a process must be <literal>process-preset</literal>
    2097 before it can be enabled.  Processes are normally enabled by
    2098 .</para>
    2099         <bridgehead renderas="sect3">See Also</bridgehead>
    2100         <para role="continues">, ,</para>
    2101       </sect2>
    2102 
    2103       <sect2 id="PROCESS-ENABLE">
    2104         <para>PROCESS-ENABLE</para>
    2105         <informalfigure>process-enable</informalfigure>
    2106         <bridgehead renderas="sect3">Name</bridgehead>
    2107         <para>PROCESS-ENABLE &mdash; Begins executing the initial function of a specified
    2108 process.</para>
    2109         <para>Function</para>
    2110         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2111         <programlisting>
    2112 process-enable
    2113           process &amp;optional timeout
    2114 
    2115 </programlisting>
    2116         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2117         <term><indexterm>process
    2118             <variablelist>a lisp process (thread).</variablelist>
    2119           </indexterm><indexterm>timeout
    2120             <variablelist>a time interval in seconds.  May be anynon-negative real number the <literal>floor</literal> ofwhich fits in 32 bits.  The default is 1.</variablelist>
    2121           </indexterm><indexterm>result
    2122             <variablelist>undefined.</variablelist>
    2123           </indexterm>
    2124         </term>
    2125         <bridgehead renderas="sect3">Description</bridgehead>
    2126         <para>Tries to begin the execution of <literal>process</literal>.
    2127 An error is signaled if <literal>process</literal> has never
    2128 been .  Otherwise,
    2129 <literal>process</literal> invokes its initial function.</para>
    2130         <para><literal>process-enable</literal> attempts to
    2131 synchronize with <literal>process</literal>, which is presumed
    2132 to be reset or in the act of resetting itself.  If this attempt
    2133 is not successful within the time interval specified by
    2134 <literal>timeout</literal>, a continuable error is signaled,
    2135 which offers the opportunity to continue waiting.</para>
    2136         <para>A process cannot meaningfully attempt to enable itself.</para>
    2137         <bridgehead renderas="sect3">See Also</bridgehead>
    2138         <para role="continues">, ,</para>
    2139         <bridgehead renderas="sect3">Notes</bridgehead>
    2140         <para>It would be nice to have more discussion of what it means
    2141 to synchronize with the process.</para>
    2142       </sect2>
    2143 
    2144       <sect2 id="PROCESS-RUN-FUNCTION">
    2145         <para>PROCESS-RUN-FUNCTION</para>
    2146         <informalfigure>process-run-function</informalfigure>
    2147         <bridgehead renderas="sect3">Name</bridgehead>
    2148         <para>PROCESS-RUN-FUNCTION &mdash; Creates a process, presets it, and enables it.</para>
    2149         <para>Function</para>
    2150         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2151         <programlisting>
    2152 process-run-function
    2153           process-specifier function &amp;rest args => process
    2154 </programlisting>
    2155         <term><indexterm>process-specifier
    2156             <variablelist><literal>name</literal> |(<literal>&amp;key</literal> <literal>name</literal><literal>persistent</literal><literal>priority</literal><literal>class</literal><literal>stack-size</literal><literal>vstack-size</literal><literal>tstack-size</literal>)</variablelist>
    2157           </indexterm>
    2158         </term>
    2159         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2160         <term><indexterm>name
    2161             <variablelist>a string, used to identify the process.Passed to <literal>make-process</literal>.</variablelist>
    2162           </indexterm><indexterm>function
    2163             <variablelist>a function, designated by itself or by a symbolwhich names it.  Passed to<literal>preset-process</literal>.</variablelist>
    2164           </indexterm><indexterm>persistent
    2165             <variablelist>a boolean, passed to <literal>make-process</literal>.</variablelist>
    2166           </indexterm><indexterm>priority
    2167             <variablelist>ignored.</variablelist>
    2168           </indexterm><indexterm>class
    2169             <variablelist>a subclass of CCL:PROCESS.  Passed to<literal>make-process</literal>.</variablelist>
    2170           </indexterm><indexterm>stack-size
    2171             <variablelist>a size, in bytes.  Passed to<literal>make-process</literal>.</variablelist>
    2172           </indexterm><indexterm>vstack-size
    2173             <variablelist>a size, in bytes.  Passed to<literal>make-process</literal>.</variablelist>
    2174           </indexterm><indexterm>tstack-size
    2175             <variablelist>a size, in bytes.  Passed to<literal>make-process</literal>.</variablelist>
    2176           </indexterm><indexterm>process
    2177             <variablelist>the newly-created process.</variablelist>
    2178           </indexterm>
    2179         </term>
    2180         <bridgehead renderas="sect3">Description</bridgehead>
    2181         <para>Creates a lisp process (thread) via
    2182 ,
    2183 presets it via , and
    2184 enables it via .  This means
    2185 that <literal>process</literal> will immediately begin to
    2186 execute.
    2187 <literal>process-run-function</literal> is
    2188 the simplest way to create and run a process.</para>
    2189         <bridgehead renderas="sect3">See Also</bridgehead>
    2190         <para role="continues">, ,</para>
    2191       </sect2>
    2192 
    2193       <sect2 id="PROCESS-INTERRUPT">
    2194         <para>PROCESS-INTERRUPT</para>
    2195         <informalfigure>process-interrupt</informalfigure>
    2196         <bridgehead renderas="sect3">Name</bridgehead>
    2197         <para>PROCESS-INTERRUPT &mdash; Arranges for the target process to invoke a
    2198 specified function at some point in the near future, and then
    2199 return to what it was doing.</para>
    2200         <para>Function</para>
    2201         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2202         <programlisting>
    2203 process-interrupt
    2204           process function &amp;rest args => result
    2205 </programlisting>
    2206         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2207         <term><indexterm>process
    2208             <variablelist>a lisp process (thread).</variablelist>
    2209           </indexterm><indexterm>function
    2210             <variablelist>a function.</variablelist>
    2211           </indexterm><indexterm>args
    2212             <variablelist>a list of values, appropriate as arguments to<literal>function</literal>.</variablelist>
    2213           </indexterm><indexterm>result
    2214             <variablelist>the result of applying <literal>function</literal>to <literal>args</literal> if <literal>proceess</literal>is the <literal>current-process</literal>, otherwiseNIL.</variablelist>
    2215           </indexterm>
    2216         </term>
    2217         <bridgehead renderas="sect3">Description</bridgehead>
    2218         <para>Arranges for <literal>process</literal> to apply <literal>function</literal> to <literal>args</literal> at
    2219 some point in the near future (interrupting whatever <literal>process</literal>
    2220 was doing.) If <literal>function</literal> returns normally, <literal>process</literal>
    2221 resumes execution at the point at which it was interrupted.</para>
    2222         <para><literal>process</literal> must be in an enabled state in order to respond to a
    2223 <literal>process-interrupt</literal> request.  It's perfectly legal for a process
    2224 to call <literal>process-interrupt</literal> on itself.</para>
    2225         <para><literal>process-interrupt</literal> uses asynchronous POSIX signals to interrupt
    2226 threads. If the thread being interrupted is executing lisp code, it
    2227 can respond to the interrupt almost immediately (as soon as it has
    2228 finished pseudo-atomic operations like consing and stack-frame
    2229 initialization.)</para>
    2230         <para>If the interrupted thread is blocking in a system call, that system
    2231 call is aborted by the signal and the interrupt is handled on return.</para>
    2232         <para>Beginning with the version 1.1 prereleases of OpenMCL interrupts are
    2233 disabled in <literal>unwind-protect</literal> cleanup forms and in any stack-unwinding
    2234 code between the point of the <literal>throw</literal> and the corresponding CATCH
    2235 target.  If interrupts were enabled at the time that the CATCH was
    2236 established, then any interrupt that had been deferred during
    2237 unwinding will be taken just before the transfer to <literal>catch</literal> target
    2238 (after all of that unwinding is complete.)</para>
    2239         <para>If an <literal>unwind-protect</literal> cleanup form actually does something that
    2240 needs to be interruptible, it's necessary to use
    2241 <literal>with-interrupts-enabled</literal>.  (This actually happens somewhere in
    2242 the code which waits for external processes to complete; some of that
    2243 waiting occurred within an unwind-protect cleanup, and interrupts
    2244 needed to be explicitly enabled in that case in order to make the wait
    2245 interruptible.)</para>
    2246         <para>Note that <literal>(without-interrupts (throw ...))</literal> wouldn't have the intended
    2247 effect, since the <literal>throw</literal> would cause execution to exit the extent of
    2248 the <literal>without-interrupts</literal>.</para>
    2249         <para>In versions prior to 1.1, interrupts could occur at arbitrary times
    2250 during the process of unwinding the stack and executing intervening
    2251 cleanup forms.</para>
    2252         <para>It is still difficult to reliably interrupt arbitrary foreign code
    2253 (that may be stateful or otherwise non-reentrant); the interrupt
    2254 request is handled when such foreign code returns to or enters lisp.</para>
    2255         <bridgehead renderas="sect3">See Also</bridgehead>
    2256         <para role="continues"></para>
    2257         <bridgehead renderas="sect3">Notes</bridgehead>
    2258         <para>It would probably be better for <literal>result</literal> to always be NIL, since
    2259 the present behaviour is inconsistent.</para>
    2260         <para><literal>Process-interrupt</literal> works by sending signals between threads, via
    2261 the C function <literal>#_pthread_signal</literal>.  It could be argued that it
    2262 should be done in one of several possible other ways under Darwin, to
    2263 make it practical to asynchronously interrupt things which make heavy
    2264 use of the Mach nanokernel.</para>
    2265       </sect2>
    2266 
    2267       <sect2 id="iCURRENT-PROCESS-">
    2268         <para>*CURRENT-PROCESS*</para>
    2269         <informalfigure>*current-process*</informalfigure>
    2270         <bridgehead renderas="sect3">Name</bridgehead>
    2271         <para>*CURRENT-PROCESS* &mdash; Bound in each process, to that process
    2272 itself.</para>
    2273         <para>Variable</para>
    2274         <bridgehead renderas="sect3">Value Type</bridgehead>
    2275         <para>A lisp process (thread).</para>
    2276         <bridgehead renderas="sect3">Initial Value</bridgehead>
    2277         <para>Bound separately in each process, to that process itself.</para>
    2278         <bridgehead renderas="sect3">Description</bridgehead>
    2279         <para>Used when lisp code needs to find out what process it is
    2280 executing in.  Shouldn't be set by user code.</para>
    2281         <bridgehead renderas="sect3">See Also</bridgehead>
    2282         <para role="continues"></para>
    2283       </sect2>
    2284 
    2285       <sect2 id="PROCESS-RESET">
    2286         <para>PROCESS-RESET</para>
    2287         <informalfigure>process-reset</informalfigure>
    2288         <bridgehead renderas="sect3">Name</bridgehead>
    2289         <para>PROCESS-RESET &mdash; Causes a specified process to cleanly exit from
    2290 any ongoing computation.</para>
    2291         <para>Function</para>
    2292         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2293         <programlisting>
    2294 process-reset
    2295           process &amp;optional kill-option => result
    2296 </programlisting>
    2297         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2298         <term><indexterm>process
    2299             <variablelist>a lisp process (thread).</variablelist>
    2300           </indexterm><indexterm>kill-option
    2301             <variablelist>a generalized boolean.  The default is T.</variablelist>
    2302           </indexterm><indexterm>result
    2303             <variablelist>undefined.</variablelist>
    2304           </indexterm>
    2305         </term>
    2306         <bridgehead renderas="sect3">Description</bridgehead>
    2307         <para>Causes <literal>process</literal> to cleanly exit
    2308 from any ongoing computation.  If <literal>kill-option</literal>
    2309 is true, <literal>process</literal> then exits.  Otherwise, it
    2310 enters a state where it can be
    2311 . This
    2312 is implemented by signaling a condition of type PROCESS-RESET;
    2313 user-defined condition handlers should generally refrain from
    2314 attempting to handle conditions of this type.</para>
    2315         <para>A process can meaningfully reset itself.</para>
    2316         <para>There is in general no way to know precisely when
    2317 <literal>process</literal>
    2318 has completed the act of resetting or killing itself; a process
    2319 which has either entered the limbo of the reset state or exited
    2320 has few ways of communicating either fact.</para>
    2321         <para>can reliably determine when a process has entered
    2322 the "limbo of the reset state", but can't predict how long the
    2323 clean exit from ongoing computation might take: that depends on
    2324 the behavior of <literal>unwind-protect</literal> cleanup
    2325 forms, and of the OS scheduler.</para>
    2326         <para>Resetting a process other than
    2327  involves the
    2328 use of .</para>
    2329         <bridgehead renderas="sect3">See Also</bridgehead>
    2330         <para role="continues">,</para>
    2331       </sect2>
    2332 
    2333       <sect2 id="PROCESS-KILL">
    2334         <para>PROCESS-KILL</para>
    2335         <informalfigure>process-kill</informalfigure>
    2336         <bridgehead renderas="sect3">Name</bridgehead>
    2337         <para>PROCESS-KILL &mdash; Causes a specified process to cleanly exit from any
    2338 ongoing computation, and then exit.</para>
    2339         <para>Function</para>
    2340         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2341         <programlisting>
    2342 process-kill process
    2343           => result
    2344 </programlisting>
    2345         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2346         <term><indexterm>process
    2347             <variablelist>a lisp process (thread).</variablelist>
    2348           </indexterm><indexterm>result
    2349             <variablelist>undefined.</variablelist>
    2350           </indexterm>
    2351         </term>
    2352         <bridgehead renderas="sect3">Description</bridgehead>
    2353         <para>Entirely equivalent to calling
    2354 (PROCESS-RESET PROCESS T).  Causes <literal>process</literal>
    2355 to cleanly exit from any ongoing computation, and then exit.</para>
    2356         <bridgehead renderas="sect3">See Also</bridgehead>
    2357         <para role="continues">,</para>
    2358       </sect2>
    2359 
    2360       <sect2 id="PROCESS-ABORT">
    2361         <para>PROCESS-ABORT</para>
    2362         <informalfigure>process-abort</informalfigure>
    2363         <bridgehead renderas="sect3">Name</bridgehead>
    2364         <para>PROCESS-ABORT &mdash; Causes a specified process to process an abort
    2365 condition, as if it had invoked
    2366 <literal>abort</literal>.</para>
    2367         <para>Function</para>
    2368         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2369         <programlisting>
    2370 process-abort process
    2371           &amp;optional condition
    2372           => NIL
    2373 </programlisting>
    2374         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2375         <term><indexterm>process
    2376             <variablelist>a lisp process (thread).</variablelist>
    2377           </indexterm><indexterm>condition
    2378             <variablelist>a lisp condition.  The default is NIL.</variablelist>
    2379           </indexterm>
    2380         </term>
    2381         <bridgehead renderas="sect3">Description</bridgehead>
    2382         <para>Entirely equivalent to calling
    2383 ( <literal>process</literal>
    2384 (<literal>lambda</literal> ()
    2385 (<literal>abort</literal> <literal>condition</literal>))).
    2386 Causes <literal>process</literal> to transfer control to the
    2387 applicable handler or restart for <literal>abort</literal>.</para>
    2388         <para>If <literal>condition</literal> is non-NIL,
    2389 <literal>process-abort</literal> does not consider any
    2390 handlers which are explicitly bound to conditions other than
    2391 <literal>condition</literal>.</para>
    2392         <bridgehead renderas="sect3">See Also</bridgehead>
    2393         <para role="continues">,</para>
    2394       </sect2>
    2395 
    2396       <sect2 id="iTICKS-PER-SECOND-">
    2397         <para>*TICKS-PER-SECOND*</para>
    2398         <informalfigure>*ticks-per-second*</informalfigure>
    2399         <bridgehead renderas="sect3">Name</bridgehead>
    2400         <para>*TICKS-PER-SECOND* &mdash; Bound to the clock resolution of the OS
    2401 scheduler.</para>
    2402         <para>Variable</para>
    2403         <bridgehead renderas="sect3">Value Type</bridgehead>
    2404         <para>A positive integer.</para>
    2405         <bridgehead renderas="sect3">Initial Value</bridgehead>
    2406         <para>The clock resoluton of the OS scheduler.  Currently,
    2407 both LinuxPPC and DarwinPPC yeild an initial value of 100.</para>
    2408         <bridgehead renderas="sect3">Description</bridgehead>
    2409         <para>This value is ordinarily of marginal interest at best,
    2410 but, for backward compatibility, some functions accept timeout
    2411 values expressed in "ticks".  This value gives the number of
    2412 ticks per second.</para>
    2413         <bridgehead renderas="sect3">See Also</bridgehead>
    2414         <para role="continues"></para>
    2415       </sect2>
    2416 
    2417       <sect2 id="PROCESS-WHOSTATE">
    2418         <para>PROCESS-WHOSTATE</para>
    2419         <informalfigure>process-whostate</informalfigure>
    2420         <bridgehead renderas="sect3">Name</bridgehead>
    2421         <para>PROCESS-WHOSTATE &mdash; Returns a string which describes the status of
    2422 a specified process.</para>
    2423         <para>Function</para>
    2424         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2425         <programlisting>
    2426 process-whostate process
    2427           => whostate
    2428 </programlisting>
    2429         <term><indexterm>process
    2430             <variablelist>a lisp process (thread).</variablelist>
    2431           </indexterm><indexterm>whostate
    2432             <variablelist>a string which describes the "state" of<literal>process</literal>.</variablelist>
    2433           </indexterm>
    2434         </term>
    2435         <bridgehead renderas="sect3">Description</bridgehead>
    2436         <para>This information is primarily for the benefit of
    2437 debugging tools.  <literal>whostate</literal> is a terse report
    2438 on what <literal>process</literal> is doing, or not doing,
    2439 and why.</para>
    2440         <para>If the process is currently waiting in a call to
    2441  or
    2442 , its
    2443 <literal>process-whostate</literal> will be the value
    2444 which was passed to that function as <literal>whostate</literal>.</para>
    2445         <bridgehead renderas="sect3">See Also</bridgehead>
    2446         <para role="continues">, ,</para>
    2447         <bridgehead renderas="sect3">Notes</bridgehead>
    2448         <para>This should arguably be SETFable, but doesn't seem to
    2449 ever have been.</para>
    2450       </sect2>
    2451 
    2452       <sect2 id="PROCESS-ALLOW-SCHEDULE">
    2453         <para>PROCESS-ALLOW-SCHEDULE</para>
    2454         <informalfigure>process-allow-schedule</informalfigure>
    2455         <bridgehead renderas="sect3">Name</bridgehead>
    2456         <para>PROCESS-ALLOW-SCHEDULE &mdash; Used for cooperative multitasking; probably never
    2457 necessary.</para>
    2458         <para>Function</para>
    2459         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2460         <programlisting>
    2461 process-allow-schedule
    2462 </programlisting>
    2463         <bridgehead renderas="sect3">Description</bridgehead>
    2464         <para>Advises the OS scheduler that the current thread has nothing
    2465 useful to do and that it should try to find some other thread to
    2466 schedule in its place. There's almost always a better
    2467 alternative, such as waiting for some specific event to
    2468 occur.  For example, you could use a lock or semaphore.</para>
    2469         <bridgehead renderas="sect3">See Also</bridgehead>
    2470         <para role="continues">, , , , ,</para>
    2471         <bridgehead renderas="sect3">Notes</bridgehead>
    2472         <para>This is a holdover from the days of cooperative
    2473 multitasking.  All modern general-purpose operating systems use
    2474 preemptive multitasking.</para>
    2475       </sect2>
    2476 
    2477       <sect2 id="PROCESS-WAIT">
    2478         <para>PROCESS-WAIT</para>
    2479         <informalfigure>process-wait</informalfigure>
    2480         <bridgehead renderas="sect3">Name</bridgehead>
    2481         <para>PROCESS-WAIT &mdash; Causes the current lisp process (thread) to wait for
    2482 a given
    2483 predicate to return true.</para>
    2484         <para>Function</para>
    2485         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2486         <programlisting>
    2487 process-wait
    2488           whostate function &amp;rest args => result
    2489 </programlisting>
    2490         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2491         <term><indexterm>whostate
    2492             <variablelist>a string, which will be the value ofwhile the process is waiting.</variablelist>
    2493           </indexterm><indexterm>function
    2494             <variablelist>a function, designated by itself or by a symbolwhich names it.</variablelist>
    2495           </indexterm><indexterm>args
    2496             <variablelist>a list of values, appropriate as arguments to<literal>function</literal>.</variablelist>
    2497           </indexterm><indexterm>result
    2498             <variablelist>NIL.</variablelist>
    2499           </indexterm>
    2500         </term>
    2501         <bridgehead renderas="sect3">Description</bridgehead>
    2502         <para>Causes the current lisp process (thread) to repeatedly
    2503 apply <literal>function</literal> to
    2504 <literal>args</literal> until the call returns a true result, then
    2505 returns NIL. After
    2506 each failed call, yields the CPU as if by
    2507 .</para>
    2508         <para>As with , it's almost
    2509 always more efficient to wait for some
    2510 specific event to occur; this isn't exactly busy-waiting, but
    2511 the OS scheduler can do a better job of scheduling if it's given
    2512 the relevant information.  For example, you could use a lock
    2513 or semaphore.</para>
    2514         <bridgehead renderas="sect3">See Also</bridgehead>
    2515         <para role="continues">, , , , , , ,</para>
    2516       </sect2>
    2517 
    2518       <sect2 id="PROCESS-WAIT-WITH-TIMEOUT">
    2519         <para>PROCESS-WAIT-WITH-TIMEOUT</para>
    2520         <informalfigure>process-wait-with-timeout</informalfigure>
    2521         <bridgehead renderas="sect3">Name</bridgehead>
    2522         <para>PROCESS-WAIT-WITH-TIMEOUT &mdash; Causes the current thread to wait for a given
    2523 predicate to return true, or for a timeout to expire.</para>
    2524         <para>Function</para>
    2525         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2526         <programlisting>
    2527 process-wait-with-timeout
    2528           whostate ticks function args => result
    2529 </programlisting>
    2530         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2531         <term><indexterm>whostate
    2532             <variablelist>a string, which will be the value ofwhile the process is waiting.</variablelist>
    2533           </indexterm><indexterm>ticks
    2534             <variablelist>either a positive integer expressing a durationin "ticks" (see ),or NIL.</variablelist>
    2535           </indexterm><indexterm>function
    2536             <variablelist>a function, designated by itself or by a symbolwhich names it.</variablelist>
    2537           </indexterm><indexterm>args
    2538             <variablelist>a list of values, appropriate as arguments to<literal>function</literal>.</variablelist>
    2539           </indexterm><indexterm>result
    2540             <variablelist>T if <literal>process-wait-with-timeout</literal>returned because its <literal>function</literal> returnedtrue, or NIL if it returned because the duration<literal>ticks</literal> has been exceeded.</variablelist>
    2541           </indexterm>
    2542         </term>
    2543         <bridgehead renderas="sect3">Description</bridgehead>
    2544         <para>If <literal>ticks</literal> is NIL, behaves exactly like
    2545 , except for returning T.
    2546 Otherwise, <literal>function</literal> will be tested repeatedly,
    2547 in the same
    2548 kind of test/yield loop as in >
    2549 until either <literal>function</literal> returns true,
    2550 or the duration <literal>ticks</literal> has been exceeded.</para>
    2551         <para>Having already read the descriptions of
    2552  and
    2553 , the
    2554 astute reader has no doubt anticipated the observation that
    2555 better alternatives should be used whenever possible.</para>
    2556         <bridgehead renderas="sect3">See Also</bridgehead>
    2557         <para role="continues">, , , , , , , ,</para>
    2558       </sect2>
    2559 
    2560       <sect2 id="WITHOUT-INTERRUPTS">
    2561         <para>WITHOUT-INTERRUPTS</para>
    2562         <informalfigure>without-interrupts</informalfigure>
    2563         <bridgehead renderas="sect3">Name</bridgehead>
    2564         <para>WITHOUT-INTERRUPTS &mdash; Evaluates its body in an environment in which
    2565 process-interrupt requests are deferred.</para>
    2566         <para>Macro</para>
    2567         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2568         <programlisting>
    2569 without-interrupts
    2570           &amp;body body => result
    2571 </programlisting>
    2572         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2573         <term><indexterm>body
    2574             <variablelist>an implicit progn.</variablelist>
    2575           </indexterm><indexterm>result
    2576             <variablelist>the primary value returned by<literal>body</literal>.</variablelist>
    2577           </indexterm>
    2578         </term>
    2579         <bridgehead renderas="sect3">Description</bridgehead>
    2580         <para>Executes <literal>body</literal> in an environment in which
    2581  requests are deferred. As noted in the
    2582 description of , this has nothing to do with
    2583 the scheduling of other threads; it may be necessary to inhibit
    2584  handling when (for instance) modifying some
    2585 data structure (for which the current thread holds an appropriate
    2586 lock) in some manner that's not reentrant.</para>
    2587         <para>Beginning with the version 1.1 prereleases of OpenMCL interrupts are
    2588 disabled in <literal>unwind-protect</literal> cleanup forms and in any
    2589 stack-unwinding code between the point of the <literal>throw</literal> and the
    2590 corresponding CATCH target. If an <literal>unwind-protect</literal> cleanup form
    2591 actually does something that needs to be interruptible, it's necessary
    2592 to use <literal>with-interrupts-enabled</literal>. In versions prior to 1.1,
    2593 interrupts can occur at arbitrary times during the process of
    2594 unwinding the stack and executing intervening cleanup forms.</para>
    2595         <bridgehead renderas="sect3">See Also</bridgehead>
    2596         <para role="continues"></para>
    2597       </sect2>
    2598 
    2599       <sect2 id="MAKE-LOCK">
    2600         <para>MAKE-LOCK</para>
    2601         <informalfigure>make-lock</informalfigure>
    2602         <bridgehead renderas="sect3">Name</bridgehead>
    2603         <para>MAKE-LOCK &mdash; Creates and returns a lock object, which can
    2604 be used for synchronization between threads.</para>
    2605         <para>Function</para>
    2606         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2607         <programlisting>
    2608 make-lock &amp;optional
    2609           name => lock
    2610 </programlisting>
    2611         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2612         <term><indexterm>name
    2613             <variablelist>any lisp object; saved as part of<literal>lock</literal>.  Typically a string or symbolwhich may appear in the sof threads which are waiting for <literal>lock</literal>.</variablelist>
    2614           </indexterm><indexterm>lock
    2615             <variablelist>a newly-allocated object of type CCL:LOCK.</variablelist>
    2616           </indexterm>
    2617         </term>
    2618         <bridgehead renderas="sect3">Description</bridgehead>
    2619         <para>Creates and returns a lock object, which can
    2620 be used to synchronize access to some shared resource.
    2621 <literal>lock</literal> is
    2622 initially in a "free" state; a lock can also be
    2623 "owned" by a
    2624 thread.</para>
    2625         <bridgehead renderas="sect3">See Also</bridgehead>
    2626         <para role="continues">, , , , , , , ,</para>
    2627       </sect2>
    2628 
    2629       <sect2 id="WITH-LOCK-GRABBED">
    2630         <para>WITH-LOCK-GRABBED</para>
    2631         <informalfigure>with-lock-grabbed</informalfigure>
    2632         <bridgehead renderas="sect3">Name</bridgehead>
    2633         <para>WITH-LOCK-GRABBED &mdash; Waits until a given lock can be obtained, then
    2634 evaluates its body with the lock held.</para>
    2635         <para>Macro</para>
    2636         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2637         <programlisting>
    2638 with-lock-grabbed
    2639           (lock) &amp;body body
    2640 </programlisting>
    2641         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2642         <term><indexterm>lock
    2643             <variablelist>an object of type CCL:LOCK.</variablelist>
    2644           </indexterm><indexterm>body
    2645             <variablelist>an implicit progn.</variablelist>
    2646           </indexterm><indexterm>result
    2647             <variablelist>the primary value returned by<literal>body</literal>.</variablelist>
    2648           </indexterm>
    2649         </term>
    2650         <bridgehead renderas="sect3">Description</bridgehead>
    2651         <para>Waits until <literal>lock</literal> is either free or
    2652 owned by the calling
    2653 thread, then excutes <literal>body</literal> with the
    2654 lock owned by the calling thread. If <literal>lock</literal>
    2655 was free when <literal>with-lock-grabbed</literal> was called,
    2656 it is restored to a free state after <literal>body</literal>
    2657 is executed.</para>
    2658         <bridgehead renderas="sect3">See Also</bridgehead>
    2659         <para role="continues">, , , , , , , ,</para>
    2660       </sect2>
    2661 
    2662       <sect2 id="GRAB-LOCK">
    2663         <para>GRAB-LOCK</para>
    2664         <informalfigure>grab-lock</informalfigure>
    2665         <bridgehead renderas="sect3">Name</bridgehead>
    2666         <para>GRAB-LOCK &mdash; Waits until a given lock can be obtained, then
    2667 obtains it.</para>
    2668         <para>Function</para>
    2669         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2670         <programlisting>
    2671 grab-lock lock
    2672 </programlisting>
    2673         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2674         <term><indexterm>lock
    2675             <variablelist>an object of type CCL:LOCK.</variablelist>
    2676           </indexterm>
    2677         </term>
    2678         <bridgehead renderas="sect3">Description</bridgehead>
    2679         <para>Blocks until <literal>lock</literal> is owned by the
    2680 calling thread.</para>
    2681         <para>The macro
    2682 <emphasis>could</emphasis> be defined in
    2683 terms of <literal>grab-lock</literal> and
    2684 , but it is actually
    2685 implemented at a slightly lower level.</para>
    2686         <bridgehead renderas="sect3">See Also</bridgehead>
    2687         <para role="continues">, , , , , , , ,</para>
    2688       </sect2>
    2689 
    2690       <sect2 id="RELEASE-LOCK">
    2691         <para>RELEASE-LOCK</para>
    2692         <informalfigure>release-lock</informalfigure>
    2693         <bridgehead renderas="sect3">Name</bridgehead>
    2694         <para>RELEASE-LOCK &mdash; Relinquishes ownership of a given lock.</para>
    2695         <para>Function</para>
    2696         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2697         <programlisting>
    2698 release-lock lock
    2699 </programlisting>
    2700         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2701         <term><indexterm>lock
    2702             <variablelist>an object of type CCL:LOCK.</variablelist>
    2703           </indexterm>
    2704         </term>
    2705         <bridgehead renderas="sect3">Description</bridgehead>
    2706         <para>Signals an error of type CCL:LOCK-NOT-OWNER if
    2707 <literal>lock</literal>
    2708 is not already owned by the calling thread; otherwise, undoes the
    2709 effect of one previous
    2710 .  If this means that
    2711 <literal>release-lock</literal> has now been called on
    2712 <literal>lock</literal> the same number of times as
    2713  has, <literal>lock</literal>
    2714 becomes free.</para>
    2715         <bridgehead renderas="sect3">See Also</bridgehead>
    2716         <para role="continues">, , , , , , , ,</para>
    2717       </sect2>
    2718 
    2719       <sect2 id="TRY-LOCK">
    2720         <para>TRY-LOCK</para>
    2721         <informalfigure>try-lock</informalfigure>
    2722         <bridgehead renderas="sect3">Name</bridgehead>
    2723         <para>TRY-LOCK &mdash; Obtains the given lock, but only if it is not
    2724 necessary to wait for it.</para>
    2725         <para>Function</para>
    2726         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2727         <programlisting>
    2728 try-lock lock => result
    2729 </programlisting>
    2730         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2731         <term><indexterm>lock
    2732             <variablelist>an object of type CCL:LOCK.</variablelist>
    2733           </indexterm><indexterm>result
    2734             <variablelist>T if <literal>lock</literal> has been obtained,or NIL if it has not.</variablelist>
    2735           </indexterm>
    2736         </term>
    2737         <bridgehead renderas="sect3">Description</bridgehead>
    2738         <para>Tests whether <literal>lock</literal>
    2739 can be obtained without blocking - that is, either
    2740 <literal>lock</literal> is already free, or it is already owned
    2741 by .  If it can,
    2742 causes it to
    2743 be owned by the calling lisp process (thread) and returns T.
    2744 Otherwise, the lock
    2745 is already owned by another thread and cannot be obtained without
    2746 blocking; NIL is returned in this case.</para>
    2747         <bridgehead renderas="sect3">See Also</bridgehead>
    2748         <para role="continues">, , , , , , , ,</para>
    2749       </sect2>
    2750 
    2751       <sect2 id="MAKE-READ-WRITE-LOCK">
    2752         <para>MAKE-READ-WRITE-LOCK</para>
    2753         <informalfigure>make-read-write-lock</informalfigure>
    2754         <bridgehead renderas="sect3">Name</bridgehead>
    2755         <para>MAKE-READ-WRITE-LOCK &mdash; Creates and returns a read-write lock, which can
    2756 be used for synchronization between threads.</para>
    2757         <para>Function</para>
    2758         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2759         <programlisting>
    2760 make-read-write-lock
    2761           => read-write-lock
    2762 </programlisting>
    2763         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2764         <term><indexterm>read-write-lock
    2765             <variablelist>a newly-allocated object of typeCCL:READ-WRITE-LOCK.</variablelist>
    2766           </indexterm>
    2767         </term>
    2768         <bridgehead renderas="sect3">Description</bridgehead>
    2769         <para>Creates and returns an object of type CCL::READ-WRITE-LOCK.
    2770 A read-write lock may, at any given time, belong to any number
    2771 of lisp processes (threads) which act as "readers"; or, it may
    2772 belong to at most one process which acts as a "writer".  A
    2773 read-write lock may never be held by a reader at the same time as
    2774 a writer.  Intially, <literal>read-write-lock</literal> has
    2775 no readers and no writers.</para>
    2776         <bridgehead renderas="sect3">See Also</bridgehead>
    2777         <para role="continues">, , , , , ,</para>
    2778         <bridgehead renderas="sect3">Notes</bridgehead>
    2779         <para>There probably should be some way to
    2780 atomically "promote" a reader, making it a writer without
    2781 releasing the lock, which could otherwise cause delay.</para>
    2782       </sect2>
    2783 
    2784       <sect2 id="WITH-READ-LOCK">
    2785         <para>WITH-READ-LOCK</para>
    2786         <informalfigure>with-read-lock</informalfigure>
    2787         <bridgehead renderas="sect3">Name</bridgehead>
    2788         <para>WITH-READ-LOCK &mdash; Waits until a given lock is available for
    2789 read-only access, then evaluates its body with the lock
    2790 held.</para>
    2791         <para>Macro</para>
    2792         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2793         <programlisting>
    2794 with-read-lock
    2795           (read-write-lock) &amp;body body => result
    2796 </programlisting>
    2797         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2798         <term><indexterm>read-write-lock
    2799             <variablelist>an object of typeCCL:READ-WRITE-LOCK.</variablelist>
    2800           </indexterm><indexterm>body
    2801             <variablelist>an implicit progn.</variablelist>
    2802           </indexterm><indexterm>result
    2803             <variablelist>the primary value returned by<literal>body</literal>.</variablelist>
    2804           </indexterm>
    2805         </term>
    2806         <bridgehead renderas="sect3">Description</bridgehead>
    2807         <para>Waits until <literal>read-write-lock</literal> has no
    2808 writer,
    2809 ensures that  is a
    2810 reader of it, then executes <literal>body</literal>.</para>
    2811         <para>After executing <literal>body</literal>, if
    2812  was not a reader of
    2813 <literal>read-write-lock</literal> before
    2814 <literal>with-read-lock</literal> was called, the lock is
    2815 released.  If it was already a reader, it remains one.</para>
    2816         <bridgehead renderas="sect3">See Also</bridgehead>
    2817         <para role="continues">, , , , , ,</para>
    2818       </sect2>
    2819 
    2820       <sect2 id="WITH-WRITE-LOCK">
    2821         <para>WITH-WRITE-LOCK</para>
    2822         <informalfigure>with-write-lock</informalfigure>
    2823         <bridgehead renderas="sect3">Name</bridgehead>
    2824         <para>WITH-WRITE-LOCK &mdash; Waits until the given lock is available for write
    2825 access, then executes its body with the lock held.</para>
    2826         <para>Macro</para>
    2827         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2828         <programlisting>
    2829 with-write-lock
    2830           (read-write-lock) &amp;body body
    2831 </programlisting>
    2832         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2833         <term><indexterm>read-write-lock
    2834             <variablelist>an object of typeCCL:READ-WRITE-LOCK.</variablelist>
    2835           </indexterm><indexterm>body
    2836             <variablelist>an implicit progn.</variablelist>
    2837           </indexterm><indexterm>result
    2838             <variablelist>the primary value returned by<literal>body</literal>.</variablelist>
    2839           </indexterm>
    2840         </term>
    2841         <bridgehead renderas="sect3">Description</bridgehead>
    2842         <para>Waits until <literal>read-write-lock</literal> has no
    2843 readers and no writer other than ,
    2844 then ensures that  is the
    2845 writer of it.  With the lock held, executes <literal>body</literal>.</para>
    2846         <para>After executing <literal>body</literal>, if
    2847  was not the writer of
    2848 <literal>read-write-lock</literal> before
    2849 <literal>with-write-lock</literal> was called, the lock is
    2850 released.  If it was already the writer, it remains the
    2851 writer.</para>
    2852         <bridgehead renderas="sect3">See Also</bridgehead>
    2853         <para role="continues">, , , , , ,</para>
    2854       </sect2>
    2855 
    2856       <sect2 id="MAKE-SEMAPHORE">
    2857         <para>MAKE-SEMAPHORE</para>
    2858         <informalfigure>make-semaphore</informalfigure>
    2859         <bridgehead renderas="sect3">Name</bridgehead>
    2860         <para>MAKE-SEMAPHORE &mdash; Creates and returns a semaphore, which can be used
    2861 for synchronization between threads.</para>
    2862         <para>Function</para>
    2863         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2864         <programlisting>
    2865 make-semaphore
    2866           => semaphore
    2867 </programlisting>
    2868         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2869         <term><indexterm>semaphore
    2870             <variablelist>a newly-allocated object of type CCL:SEMAPHORE.</variablelist>
    2871           </indexterm>
    2872         </term>
    2873         <bridgehead renderas="sect3">Description</bridgehead>
    2874         <para>Creates and returns an object of type CCL:SEMAPHORE.
    2875 A semaphore has an associated "count" which may be incremented
    2876 and decremented atomically; incrementing it represents sending
    2877 a signal, and decrementing it represents handling that signal.
    2878 <literal>semaphore</literal> has an initial count of 0.</para>
    2879         <bridgehead renderas="sect3">See Also</bridgehead>
    2880         <para role="continues">, , , , , , ,</para>
    2881       </sect2>
    2882 
    2883       <sect2 id="SIGNAL-SEMAPHORE">
    2884         <para>SIGNAL-SEMAPHORE</para>
    2885         <informalfigure>signal-semaphore</informalfigure>
    2886         <bridgehead renderas="sect3">Name</bridgehead>
    2887         <para>SIGNAL-SEMAPHORE &mdash; Atomically increments the count of a given
    2888 semaphore.</para>
    2889         <para>Function</para>
    2890         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2891         <programlisting>
    2892 signal-semaphore
    2893           semaphore => result
    2894 </programlisting>
    2895         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2896         <term><indexterm>semaphore
    2897             <variablelist>an object of type CCL:SEMAPHORE.</variablelist>
    2898           </indexterm><indexterm>result
    2899             <variablelist>an integer representing an error identifierwhich was returned by the underlying OS call.</variablelist>
    2900           </indexterm>
    2901         </term>
    2902         <bridgehead renderas="sect3">Description</bridgehead>
    2903         <para>Atomically increments <literal>semaphore</literal>'s
    2904 "count" by 1; this
    2905 may enable a waiting thread to resume execution.</para>
    2906         <bridgehead renderas="sect3">See Also</bridgehead>
    2907         <para role="continues">, , , , , , ,</para>
    2908         <bridgehead renderas="sect3">Notes</bridgehead>
    2909         <para><literal>result</literal> should probably be interpreted
    2910 and acted on by <literal>signal-semaphore</literal>, because
    2911 it is not likely to be meaningful to a lisp program, and the
    2912 most common cause of failure is a type error.</para>
    2913       </sect2>
    2914 
    2915       <sect2 id="WAIT-ON-SEMAPHORE">
    2916         <para>WAIT-ON-SEMAPHORE</para>
    2917         <informalfigure>wait-on-semaphore</informalfigure>
    2918         <bridgehead renderas="sect3">Name</bridgehead>
    2919         <para>WAIT-ON-SEMAPHORE &mdash; Waits until the given semaphore has a positive
    2920 count which can be atomically decremented.</para>
    2921         <para>Function</para>
    2922         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2923         <programlisting>
    2924 wait-on-semaphore
    2925           semaphore => result
    2926 </programlisting>
    2927         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2928         <term><indexterm>semaphore
    2929             <variablelist>an object of type CCL:SEMAPHORE.</variablelist>
    2930           </indexterm><indexterm>result
    2931             <variablelist>WAIT-ON-SEMAPHORE always returns T.</variablelist>
    2932           </indexterm>
    2933         </term>
    2934         <bridgehead renderas="sect3">Description</bridgehead>
    2935         <para>Waits until <literal>semaphore</literal>
    2936 has a positive count that can be
    2937 atomically decremented; this will succeed exactly once for each
    2938 corresponding call to SIGNAL-SEMAPHORE.</para>
    2939         <bridgehead renderas="sect3">See Also</bridgehead>
    2940         <para role="continues">, , , , , , ,</para>
    2941         <bridgehead renderas="sect3">Notes</bridgehead>
    2942       </sect2>
    2943 
    2944       <sect2 id="TIMED-WAIT-ON-SEMAPHORE">
    2945         <para>TIMED-WAIT-ON-SEMAPHORE</para>
    2946         <informalfigure>timed-wait-on-semaphore</informalfigure>
    2947         <bridgehead renderas="sect3">Name</bridgehead>
    2948         <para>TIMED-WAIT-ON-SEMAPHORE &mdash; Waits until the given semaphore has a postive
    2949 count which can be atomically decremented, or until a timeout
    2950 expires.</para>
    2951         <para>Function</para>
    2952         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2953         <programlisting>
    2954 timed-wait-on-semaphore
    2955           semaphore timeout => result
    2956 </programlisting>
    2957         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2958         <term><indexterm>semaphore
    2959             <variablelist>An object of type CCL:SEMAPHORE.</variablelist>
    2960           </indexterm><indexterm>timeout
    2961             <variablelist>a time interval in seconds.  May be anynon-negative real number the <literal>floor</literal> ofwhich fits in 32 bits.  The default is 1.</variablelist>
    2962           </indexterm><indexterm>result
    2963             <variablelist>T if <literal>timed-wait-on-semaphore</literal>returned because it was able to decrement the count of<literal>semaphore</literal>; NIL if it returned becausethe duration <literal>timeout</literal> has beenexceeded.</variablelist>
    2964           </indexterm>
    2965         </term>
    2966         <bridgehead renderas="sect3">Description</bridgehead>
    2967         <para>Waits until <literal>semaphore</literal>
    2968 has a positive count that can be
    2969 atomically decremented, or until the duration
    2970 <literal>timeout</literal> has
    2971 elapsed.</para>
    2972         <bridgehead renderas="sect3">See Also</bridgehead>
    2973         <para role="continues">, , , , , ,</para>
    2974       </sect2>
    2975 
    2976       <sect2 id="PROCESS-INPUT-WAIT">
    2977         <para>PROCESS-INPUT-WAIT</para>
    2978         <informalfigure>process-input-wait</informalfigure>
    2979         <bridgehead renderas="sect3">Name</bridgehead>
    2980         <para>PROCESS-INPUT-WAIT &mdash; Waits until input is available on a given
    2981 file-descriptor.</para>
    2982         <para>Function</para>
    2983         <bridgehead renderas="sect3">Synopsis</bridgehead>
    2984         <programlisting>
    2985 process-input-wait
    2986           fd &amp;optional timeout
    2987 </programlisting>
    2988         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    2989         <term><indexterm>fd
    2990             <variablelist>a file descriptor, which is a non-negative integerused by the OS to refer to an open file, socket, or similarI/O connection.  See CCL::STREAM-DEVICE.</variablelist>
    2991           </indexterm><indexterm>timeout
    2992             <variablelist>either NIL, or a time interval in seconds.  May be anynon-negative real number the <literal>floor</literal> ofwhich fits in 32 bits.  The default is NIL.</variablelist>
    2993           </indexterm>
    2994         </term>
    2995         <bridgehead renderas="sect3">Description</bridgehead>
    2996         <para>Wait until input is available on <literal>fd</literal>.
    2997 This uses the <literal>select()</literal> system call, and is
    2998 generally a fairly
    2999 efficient way of blocking while waiting for input. More
    3000 accurately, <literal>process-input-wait</literal>
    3001 waits until it's possible to read
    3002 from fd without blocking, or until <literal>timeout</literal>, if
    3003 it is not NIL, has been exceeded.</para>
    3004         <para>Note that it's possible to read without blocking if
    3005 the file is at its end - although, of course, the read will
    3006 return zero bytes.</para>
    3007         <bridgehead renderas="sect3">See Also</bridgehead>
    3008         <para role="continues">, , , ,</para>
    3009         <bridgehead renderas="sect3">Notes</bridgehead>
    3010         <para><literal>process-input-wait</literal> has a timeout parameter,
    3011 and
    3012  does not.  This
    3013 inconsistency should probably be corrected.</para>
    3014       </sect2>
    3015 
    3016       <sect2 id="PROCESS-OUTPUT-WAIT">
    3017         <para>PROCESS-OUTPUT-WAIT</para>
    3018         <informalfigure>process-output-wait</informalfigure>
    3019         <bridgehead renderas="sect3">Name</bridgehead>
    3020         <para>PROCESS-OUTPUT-WAIT &mdash; Waits until output is possible on a given file
    3021 descriptor.</para>
    3022         <para>Function</para>
    3023         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3024         <programlisting>
    3025 process-output-wait fd
    3026 </programlisting>
    3027         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3028         <term><indexterm>fd
    3029             <variablelist>a file descriptor, which is a non-negative integerused by the OS to refer to an open file, socket, or similarI/O connection.  See CCL::STREAM-DEVICE.</variablelist>
    3030           </indexterm>
    3031         </term>
    3032         <bridgehead renderas="sect3">Description</bridgehead>
    3033         <para>Wait until output is possible on <literal>fd</literal>.
    3034 This uses the <literal>select()</literal> system call, and is
    3035 generally a fairly
    3036 efficient way of blocking while waiting to output.</para>
    3037         <para>If <literal>process-output-wait</literal> is called on
    3038 a network socket which has not yet established a connection, it
    3039 will wait until the connection is established.  This is an
    3040 important use, often overlooked.</para>
    3041         <bridgehead renderas="sect3">See Also</bridgehead>
    3042         <para role="continues">, , , ,</para>
    3043         <bridgehead renderas="sect3">Notes</bridgehead>
    3044         <para>has a timeout parameter,
    3045 and
    3046 <literal>process-output-wait</literal> does not.  This
    3047 inconsistency should probably be corrected.</para>
    3048       </sect2>
    3049 
    3050       <sect2 id="WITH-TERMINAL-INPUT">
    3051         <para>WITH-TERMINAL-INPUT</para>
    3052         <informalfigure>with-terminal-input</informalfigure>
    3053         <bridgehead renderas="sect3">Name</bridgehead>
    3054         <para>WITH-TERMINAL-INPUT &mdash; Executes its body in an environment with exclusive
    3055 read access to the terminal.</para>
    3056         <para>Macro</para>
    3057         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3058         <programlisting>
    3059 with-terminal-input
    3060           &amp;body body => result
    3061 </programlisting>
    3062         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3063         <term><indexterm>body
    3064             <variablelist>an implicit progn.</variablelist>
    3065           </indexterm><indexterm>result
    3066             <variablelist>the primary value returned by<literal>body</literal>.</variablelist>
    3067           </indexterm>
    3068         </term>
    3069         <bridgehead renderas="sect3">Description</bridgehead>
    3070         <para>Requests exclusive read access to the standard terminal
    3071 stream, <literal>*terminal-io*</literal>.  Executes
    3072 <literal>body</literal> in an environment with that access.</para>
    3073         <bridgehead renderas="sect3">See Also</bridgehead>
    3074         <para role="continues">, :Y, , , , ,</para>
    3075       </sect2>
    3076 
    3077       <sect2 id="iREQUEST-TERMINAL-INPUT-VIA-BREAK-">
    3078         <para>*REQUEST-TERMINAL-INPUT-VIA-BREAK*</para>
    3079         <informalfigure>request-terminal-input-via-break</informalfigure>
    3080         <bridgehead renderas="sect3">Name</bridgehead>
    3081         <para>*REQUEST-TERMINAL-INPUT-VIA-BREAK* &mdash; Controls how attempts to obtain ownership of
    3082 terminal input are made.</para>
    3083         <para>Variable</para>
    3084         <bridgehead renderas="sect3">Value Type</bridgehead>
    3085         <para>A boolean.</para>
    3086         <bridgehead renderas="sect3">Initial Value</bridgehead>
    3087         <para>NIL.</para>
    3088         <bridgehead renderas="sect3">Description</bridgehead>
    3089         <para>Controls how attempts to obtain ownership of terminal input
    3090 are made. When NIL, a message is printed on *TERMINAL-IO*;
    3091 it's expected that the user will later yield
    3092 control of the terminal via the :Y toplevel command. When T, a
    3093 BREAK condition is signaled in the owning process; continuing from
    3094 the break loop will yield the terminal to the requesting process
    3095 (unless the :Y command was already used to do so in the break
    3096 loop.)</para>
    3097         <bridgehead renderas="sect3">See Also</bridgehead>
    3098         <para role="continues">, :Y, , , , ,</para>
    3099       </sect2>
    3100 
    3101       <sect2 id="iY">
    3102         <para>:Y</para>
    3103         <informalfigure>:y</informalfigure>
    3104         <bridgehead renderas="sect3">Name</bridgehead>
    3105         <para>:Y &mdash; Yields control of terminal input to a specified
    3106 lisp process (thread).</para>
    3107         <para>Toplevel Command</para>
    3108         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3109         <programlisting>
    3110 (:y p)
    3111 </programlisting>
    3112         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3113         <term><indexterm>p
    3114             <variablelist>a lisp process (thread), designated either byan integer which matches its<literal>process-serial-number</literal>,or by a string which is <literal>equal</literal> toits <literal>process-name</literal>.</variablelist>
    3115           </indexterm>
    3116         </term>
    3117         <bridgehead renderas="sect3">Description</bridgehead>
    3118         <para>:Y is a toplevel command, not a function.  As such, it
    3119 can only be used interactively, and only from the initial
    3120 process.</para>
    3121         <para>The command yields control of terminal input to the
    3122 process <literal>p</literal>, which must have used
    3123  to request access to the
    3124 terminal input stream.</para>
    3125         <bridgehead renderas="sect3">See Also</bridgehead>
    3126         <para role="continues">, , , , , ,</para>
    3127       </sect2>
     2119          </synopsis>
     2120        </refsynopsisdiv>
     2121
     2122        <refsect1>
     2123          <title>Arguments and Values</title>
     2124
     2125          <variablelist>
     2126            <varlistentry>
     2127              <term>process</term>
     2128              <listitem>
     2129                <para>a lisp process (thread).</para>
     2130              </listitem>
     2131            </varlistentry>
     2132            <varlistentry>
     2133              <term>result</term>
     2134              <listitem>
     2135                <para>The number of "outstanding"
     2136                <xref linkend="f_process-suspend"/> calls on
     2137                <varname>process</varname>, or NIL if
     2138                <varname>process</varname> has expired.
     2139                </para>
     2140              </listitem>
     2141            </varlistentry>
     2142          </variablelist>
     2143        </refsect1>
     2144
     2145        <refsect1>
     2146          <title>Description</title>
     2147
     2148          <para>An "outstanding" <xref linkend="f_process-suspend"/> call
     2149          is one which has not yet been reversed by a call to
     2150          <xref linkend="f_process-resume"/>.  A process expires when
     2151          its initial function returns, although it may later be
     2152          reset.</para>
     2153
     2154          <para>A process is <emphasis>runnable</emphasis> when it has a
     2155          <function>process-suspend-count</function> of 0, has been
     2156          preset as by <xref linkend="f_process-preset"/>, and has been
     2157          enabled as by <xref linkend="f_process-enable"/>.  Newly-created
     2158          processes have a <function>process-suspend-count</function> of
     2159          0.</para>
     2160        </refsect1>
     2161
     2162        <refsect1>
     2163          <title>See Also</title>
     2164         
     2165          <simplelist type="inline">
     2166            <member><xref linkend="f_process-suspend"/></member>
     2167            <member><xref linkend="f_process-resume"/></member>
     2168          </simplelist>
     2169        </refsect1>
     2170      </refentry>
     2171
     2172      <refentry id="f_process-preset">
     2173        <indexterm zone="f_process-preset">
     2174          <primary>process-preset</primary>
     2175        </indexterm>
     2176
     2177        <refnamediv>
     2178          <refname>PROCESS-PRESET</refname>
     2179          <refpurpose>Sets the initial function and arguments of a specified
     2180          process.</refpurpose>
     2181          <refclass>Function</refclass>
     2182        </refnamediv>
     2183
     2184        <refsynopsisdiv>
     2185          <synopsis><function>process-preset</function>
     2186          process function &rest; args
     2187          => result</synopsis>
     2188        </refsynopsisdiv>
     2189
     2190        <refsect1>
     2191          <title>Arguments and Values</title>
     2192
     2193          <variablelist>
     2194            <varlistentry>
     2195              <term>process</term>
     2196              <listitem>
     2197                <para>a lisp process (thread).</para>
     2198              </listitem>
     2199            </varlistentry>
     2200            <varlistentry>
     2201              <term>function</term>
     2202              <listitem>
     2203                <para>a function, designated by itself or by a symbol
     2204                which names it.
     2205                </para>
     2206              </listitem>
     2207            </varlistentry>
     2208            <varlistentry>
     2209              <term>args</term>
     2210              <listitem>
     2211                <para>a list of values, appropriate as arguments to
     2212                <varname>function</varname>.</para>
     2213              </listitem>
     2214            </varlistentry>
     2215            <varlistentry>
     2216              <term>result</term>
     2217              <listitem>
     2218                <para>undefined.</para>
     2219              </listitem>
     2220            </varlistentry>
     2221          </variablelist>
     2222        </refsect1>
     2223
     2224        <refsect1>
     2225          <title>Description</title>
     2226
     2227          <para>Typically used to initialize a newly-created or newly-reset
     2228          process, setting things up so that when <varname>process</varname>
     2229          becomes enabled, it will begin execution by
     2230          applying <varname>function</varname> to <varname>args</varname>.
     2231          <function>process-preset</function> does not enable
     2232          <varname>process</varname>,
     2233          although a process must be <function>process-preset</function>
     2234          before it can be enabled.  Processes are normally enabled by
     2235          <xref linkend="f_process-enable"/>.
     2236          </para>
     2237        </refsect1>
     2238
     2239        <refsect1>
     2240          <title>See Also</title>
     2241         
     2242          <simplelist type="inline">
     2243            <member><xref linkend="f_make-process"/></member>
     2244            <member><xref linkend="f_process-enable"/></member>
     2245            <member><xref linkend="f_process-run-function"/></member>
     2246          </simplelist>
     2247        </refsect1>
     2248      </refentry>
     2249
     2250      <refentry id="f_process-enable">
     2251        <indexterm zone="f_process-enable">
     2252          <primary>process-enable</primary>
     2253        </indexterm>
     2254
     2255        <refnamediv>
     2256          <refname>PROCESS-ENABLE</refname>
     2257          <refpurpose>Begins executing the initial function of a specified
     2258          process.</refpurpose>
     2259          <refclass>Function</refclass>
     2260        </refnamediv>
     2261
     2262        <refsynopsisdiv>
     2263          <synopsis><function>process-enable</function>
     2264          process &optional; timeout
     2265          </synopsis>
     2266        </refsynopsisdiv>
     2267
     2268        <refsect1>
     2269          <title>Arguments and Values</title>
     2270
     2271          <variablelist>
     2272            <varlistentry>
     2273              <term>process</term>
     2274              <listitem>
     2275                <para>a lisp process (thread).</para>
     2276              </listitem>
     2277            </varlistentry>
     2278            <varlistentry>
     2279              <term>timeout</term>
     2280              <listitem>
     2281                <para>a time interval in seconds.  May be any
     2282                non-negative real number the <function>floor</function> of
     2283                which fits in 32 bits.  The default is 1.</para>
     2284              </listitem>
     2285            </varlistentry>
     2286            <varlistentry>
     2287              <term>result</term>
     2288              <listitem>
     2289                <para>undefined.</para>
     2290              </listitem>
     2291            </varlistentry>
     2292          </variablelist>
     2293        </refsect1>
     2294
     2295        <refsect1>
     2296          <title>Description</title>
     2297
     2298          <para>Tries to begin the execution of <varname>process</varname>.
     2299          An error is signaled if <varname>process</varname> has never
     2300          been <xref linkend="f_process-preset"/>.  Otherwise,
     2301          <varname>process</varname> invokes its initial function.
     2302          </para>
     2303         
     2304          <para><function>process-enable</function> attempts to
     2305          synchronize with <varname>process</varname>, which is presumed
     2306          to be reset or in the act of resetting itself.  If this attempt
     2307          is not successful within the time interval specified by
     2308          <varname>timeout</varname>, a continuable error is signaled,
     2309          which offers the opportunity to continue waiting.
     2310          </para>
     2311
     2312          <para>A process cannot meaningfully attempt to enable itself.</para>
     2313        </refsect1>
     2314
     2315        <refsect1>
     2316          <title>See Also</title>
     2317         
     2318          <simplelist type="inline">
     2319            <member><xref linkend="f_make-process"/></member>
     2320            <member><xref linkend="f_process-preset"/></member>
     2321            <member><xref linkend="f_process-run-function"/></member>
     2322          </simplelist>
     2323        </refsect1>
     2324
     2325        <refsect1>
     2326          <title>Notes</title>
     2327
     2328          <para>It would be nice to have more discussion of what it means
     2329          to synchronize with the process.</para>
     2330        </refsect1>
     2331      </refentry>
     2332
     2333      <refentry id="f_process-run-function">
     2334        <indexterm zone="f_process-run-function">
     2335          <primary>process-run-function</primary>
     2336        </indexterm>
     2337
     2338        <refnamediv>
     2339          <refname>PROCESS-RUN-FUNCTION</refname>
     2340          <refpurpose>Creates a process, presets it, and enables it.
     2341          </refpurpose>
     2342          <refclass>Function</refclass>
     2343        </refnamediv>
     2344
     2345        <refsynopsisdiv>
     2346          <synopsis><function>process-run-function</function>
     2347          process-specifier function &rest; args => process</synopsis>
     2348
     2349          <variablelist>
     2350            <varlistentry>
     2351              <term>process-specifier</term>
     2352              <listitem>
     2353                <para>
     2354                  <varname>name</varname> |
     2355                  (&key; <varname>name</varname>
     2356                  <varname>persistent</varname>
     2357                  <varname>priority</varname>
     2358                  <varname>class</varname>
     2359                  <varname>stack-size</varname>
     2360                  <varname>vstack-size</varname>
     2361                  <varname>tstack-size</varname>)
     2362                </para>
     2363              </listitem>
     2364            </varlistentry>
     2365          </variablelist>
     2366        </refsynopsisdiv>
     2367
     2368        <refsect1>
     2369          <title>Arguments and Values</title>
     2370
     2371          <variablelist>
     2372            <varlistentry>
     2373              <term>name</term>
     2374              <listitem>
     2375                <para>a string, used to identify the process.
     2376                Passed to <function>make-process</function>.</para>
     2377              </listitem>
     2378            </varlistentry>
     2379            <varlistentry>
     2380              <term>function</term>
     2381              <listitem>
     2382                <para>a function, designated by itself or by a symbol
     2383                which names it.  Passed to
     2384                <function>preset-process</function>.
     2385                </para>
     2386              </listitem>
     2387            </varlistentry>
     2388            <varlistentry>
     2389              <term>persistent</term>
     2390             
     2391              <listitem>
     2392                <para>a boolean, passed to <function>make-process</function>.
     2393                </para>
     2394              </listitem>
     2395            </varlistentry>
     2396           
     2397            <varlistentry>
     2398              <term>priority</term>
     2399             
     2400              <listitem>
     2401                <para>ignored.</para>
     2402              </listitem>
     2403            </varlistentry>
     2404           
     2405            <varlistentry>
     2406              <term>class</term>
     2407             
     2408              <listitem>
     2409                <para>a subclass of CCL:PROCESS.  Passed to
     2410                <function>make-process</function>.</para>
     2411              </listitem>
     2412            </varlistentry>
     2413           
     2414            <varlistentry>
     2415              <term>stack-size</term>
     2416             
     2417              <listitem>
     2418                <para>a size, in bytes.  Passed to
     2419                <function>make-process</function>.</para>
     2420              </listitem>
     2421            </varlistentry>
     2422           
     2423            <varlistentry>
     2424              <term>vstack-size</term>
     2425             
     2426              <listitem>
     2427                <para>a size, in bytes.  Passed to
     2428                <function>make-process</function>.</para>
     2429              </listitem>
     2430            </varlistentry>
     2431           
     2432            <varlistentry>
     2433              <term>tstack-size</term>
     2434             
     2435              <listitem>
     2436                <para>a size, in bytes.  Passed to
     2437                <function>make-process</function>.</para>
     2438              </listitem>
     2439            </varlistentry>
     2440            <varlistentry>
     2441              <term>process</term>
     2442              <listitem>
     2443                <para>the newly-created process.</para>
     2444              </listitem>
     2445            </varlistentry>
     2446          </variablelist>
     2447        </refsect1>
     2448
     2449        <refsect1>
     2450          <title>Description</title>
     2451
     2452          <para>Creates a lisp process (thread) via
     2453          <xref linkend="f_make-process"/>,
     2454          presets it via <xref linkend="f_process-preset"/>, and
     2455          enables it via <xref linkend="f_process-enable"/>.  This means
     2456          that <varname>process</varname> will immediately begin to
     2457          execute.
     2458          <function>process-run-function</function> is
     2459          the simplest way to create and run a process.
     2460          </para>
     2461        </refsect1>
     2462
     2463        <refsect1>
     2464          <title>See Also</title>
     2465         
     2466          <simplelist type="inline">
     2467            <member><xref linkend="f_make-process"/></member>
     2468            <member><xref linkend="f_process-preset"/></member>
     2469            <member><xref linkend="f_process-enable"/></member>
     2470          </simplelist>
     2471        </refsect1>
     2472      </refentry>
     2473
     2474      <refentry id="f_process-interrupt">
     2475        <indexterm zone="f_process-interrupt">
     2476          <primary>process-interrupt</primary>
     2477        </indexterm>
     2478
     2479        <refnamediv>
     2480          <refname>PROCESS-INTERRUPT</refname>
     2481          <refpurpose>Arranges for the target process to invoke a
     2482          specified function at some point in the near future, and then
     2483          return to what it was doing.</refpurpose>
     2484          <refclass>Function</refclass>
     2485        </refnamediv>
     2486
     2487        <refsynopsisdiv>
     2488          <synopsis><function>process-interrupt</function>
     2489          process function &rest; args => result</synopsis>
     2490        </refsynopsisdiv>
     2491
     2492        <refsect1>
     2493          <title>Arguments and Values</title>
     2494
     2495          <variablelist>
     2496            <varlistentry>
     2497              <term>process</term>
     2498              <listitem>
     2499                <para>a lisp process (thread).</para>
     2500              </listitem>
     2501            </varlistentry>
     2502            <varlistentry>
     2503              <term>function</term>
     2504              <listitem>
     2505                <para>a function.
     2506                </para>
     2507              </listitem>
     2508            </varlistentry>
     2509            <varlistentry>
     2510              <term>args</term>
     2511              <listitem>
     2512                <para>a list of values, appropriate as arguments to
     2513                <varname>function</varname>.</para>
     2514              </listitem>
     2515            </varlistentry>
     2516            <varlistentry>
     2517              <term>result</term>
     2518              <listitem>
     2519                <para>the result of applying <varname>function</varname>
     2520                to <varname>args</varname> if <varname>proceess</varname>
     2521                is the <function>current-process</function>, otherwise
     2522                NIL.</para>
     2523              </listitem>
     2524            </varlistentry>
     2525          </variablelist>
     2526        </refsect1>
     2527
     2528        <refsect1>
     2529          <title>Description</title>
     2530
     2531          <para>Arranges for <varname>process</varname>
     2532          to apply <varname>function</varname> to <varname>args</varname> at
     2533          some point in the near future (interrupting whatever
     2534          <varname>process</varname>
     2535          was doing.) If <varname>function</varname> returns normally,
     2536          <varname>process</varname> resumes
     2537          execution at the point at which it was interrupted.</para>
     2538
     2539          <para><varname>process</varname> must be in an enabled state in
     2540          order to respond
     2541          to a <function>process-interrupt</function> request.  It's
     2542          perfectly legal for a process to call
     2543          <function>process-interrupt</function> on itself.</para>
     2544
     2545          <para><function>process-interrupt</function>
     2546          uses asynchronous POSIX signals to interrupt threads. If the
     2547          thread being interrupted is executing lisp code, it can
     2548          respond to the interrupt almost immediately (as soon as it
     2549          has finished pseudo-atomic operations like consing and
     2550          stack-frame initialization.)</para>
     2551
     2552          <para>If the interrupted thread is
     2553          blocking in a system call, that system call is aborted by
     2554          the signal and the interrupt is handled on return.
     2555          </para>
     2556
     2557          <para>It is
     2558          still difficult to reliably interrupt arbitrary foreign code
     2559          (that may be stateful or otherwise non-reentrant); the
     2560          interrupt request is handled when such foreign code returns
     2561          to or enters lisp.</para>
     2562        </refsect1>
     2563
     2564        <refsect1>
     2565          <title>See Also</title>
     2566         
     2567          <simplelist type="inline">
     2568            <member><xref linkend="m_without-interrupts"/></member>
     2569          </simplelist>
     2570        </refsect1>
     2571
     2572        <refsect1>
     2573          <title>Notes</title>
     2574
     2575          <para>It would probably be better for <varname>result</varname>
     2576          to always be NIL, since the present behaviour is inconsistent.
     2577          </para>
     2578
     2579          <para>
     2580            <function>Process-interrupt</function> works by sending signals
     2581            between threads, via the C function
     2582            <function>#_pthread_signal</function>.  It could be argued
     2583            that it should be done in one of several possible other ways
     2584            under
     2585            Darwin, to make it practical to asynchronously interrupt
     2586            things which make heavy use of the Mach nanokernel.
     2587          </para>
     2588        </refsect1>
     2589      </refentry>
     2590
     2591      <refentry id="v_current-process">
     2592        <indexterm zone="v_current-process">
     2593          <primary>*current-process*</primary>
     2594        </indexterm>
     2595
     2596        <refnamediv>
     2597          <refname>*CURRENT-PROCESS*</refname>
     2598          <refpurpose>Bound in each process, to that process
     2599          itself.</refpurpose>
     2600          <refclass>Variable</refclass>
     2601        </refnamediv>
     2602
     2603        <refsect1>
     2604          <title>Value Type</title>
     2605
     2606          <para>A lisp process (thread).</para>
     2607        </refsect1>
     2608
     2609        <refsect1>
     2610          <title>Initial Value</title>
     2611         
     2612          <para>Bound separately in each process, to that process itself.
     2613          </para>
     2614        </refsect1>
     2615
     2616        <refsect1>
     2617          <title>Description</title>
     2618
     2619          <para>Used when lisp code needs to find out what process it is
     2620          executing in.  Shouldn't be set by user code.</para>
     2621        </refsect1>
     2622
     2623        <refsect1>
     2624          <title>See Also</title>
     2625         
     2626          <simplelist type="inline">
     2627            <member><xref linkend="f_all-processes"/></member>
     2628          </simplelist>
     2629        </refsect1>
     2630      </refentry>
     2631
     2632      <refentry id="f_process-reset">
     2633        <indexterm zone="f_process-reset">
     2634          <primary>process-reset</primary>
     2635        </indexterm>
     2636
     2637        <refnamediv>
     2638          <refname>PROCESS-RESET</refname>
     2639          <refpurpose>Causes a specified process to cleanly exit from
     2640          any ongoing computation.</refpurpose>
     2641          <refclass>Function</refclass>
     2642        </refnamediv>
     2643
     2644        <refsynopsisdiv>
     2645          <synopsis><function>process-reset</function>
     2646          process &optional; kill-option => result</synopsis>
     2647        </refsynopsisdiv>
     2648
     2649        <refsect1>
     2650          <title>Arguments and Values</title>
     2651
     2652          <variablelist>
     2653            <varlistentry>
     2654              <term>process</term>
     2655              <listitem>
     2656                <para>a lisp process (thread).</para>
     2657              </listitem>
     2658            </varlistentry>
     2659            <varlistentry>
     2660              <term>kill-option</term>
     2661              <listitem>
     2662                <para>a generalized boolean.  The default is T.</para>
     2663              </listitem>
     2664            </varlistentry>
     2665            <varlistentry>
     2666              <term>result</term>
     2667              <listitem>
     2668                <para>undefined.</para>
     2669              </listitem>
     2670            </varlistentry>
     2671          </variablelist>
     2672        </refsect1>
     2673
     2674        <refsect1>
     2675          <title>Description</title>
     2676
     2677          <para>Causes <varname>process</varname> to cleanly exit
     2678          from any ongoing computation.  If <varname>kill-option</varname>
     2679          is true, <varname>process</varname> then exits.  Otherwise, it
     2680          enters a state where it can be
     2681          <xref linkend="f_process-preset"/>. This
     2682          is implemented by signaling a condition of type PROCESS-RESET;
     2683          user-defined condition handlers should generally refrain from
     2684          attempting to handle conditions of this type.</para>
     2685
     2686          <para>A process can meaningfully reset itself.</para>
     2687
     2688          <para>There is in general no way to know precisely when
     2689          <varname>process</varname>
     2690          has completed the act of resetting or killing itself; a process
     2691          which has either entered the limbo of the reset state or exited
     2692          has few ways of communicating either fact.
     2693          <xref linkend="f_process-enable"/>
     2694          can reliably determine when a process has entered
     2695          the "limbo of the reset state", but can't predict how long the
     2696          clean exit from ongoing computation might take: that depends on
     2697          the behavior of <function>unwind-protect</function> cleanup
     2698          forms, and of the OS scheduler.</para>
     2699
     2700          <para>Resetting a process other than
     2701          <xref linkend="v_current-process"/> involves the
     2702          use of <xref linkend="f_process-interrupt"/>.</para>
     2703        </refsect1>
     2704
     2705        <refsect1>
     2706          <title>See Also</title>
     2707         
     2708          <simplelist type="inline">
     2709            <member><xref linkend="f_process-kill"/></member>
     2710            <member><xref linkend="f_process-abort"/></member>
     2711          </simplelist>
     2712        </refsect1>
     2713      </refentry>
     2714
     2715      <refentry id="f_process-kill">
     2716        <indexterm zone="f_process-kill">
     2717          <primary>process-kill</primary>
     2718        </indexterm>
     2719
     2720        <refnamediv>
     2721          <refname>PROCESS-KILL</refname>
     2722          <refpurpose>Causes a specified process to cleanly exit from any
     2723          ongoing computation, and then exit.</refpurpose>
     2724          <refclass>Function</refclass>
     2725        </refnamediv>
     2726
     2727        <refsynopsisdiv>
     2728          <synopsis><function>process-kill</function> process
     2729          => result</synopsis>
     2730        </refsynopsisdiv>
     2731
     2732        <refsect1>
     2733          <title>Arguments and Values</title>
     2734
     2735          <variablelist>
     2736            <varlistentry>
     2737              <term>process</term>
     2738              <listitem>
     2739                <para>a lisp process (thread).</para>
     2740              </listitem>
     2741            </varlistentry>
     2742            <varlistentry>
     2743              <term>result</term>
     2744              <listitem>
     2745                <para>undefined.</para>
     2746              </listitem>
     2747            </varlistentry>
     2748          </variablelist>
     2749        </refsect1>
     2750
     2751        <refsect1>
     2752          <title>Description</title>
     2753
     2754          <para>Entirely equivalent to calling
     2755          (PROCESS-RESET PROCESS T).  Causes <varname>process</varname>
     2756          to cleanly exit from any ongoing computation, and then exit.</para>
     2757        </refsect1>
     2758
     2759        <refsect1>
     2760          <title>See Also</title>
     2761         
     2762          <simplelist type="inline">
     2763            <member><xref linkend="f_process-reset"/></member>
     2764            <member><xref linkend="f_process-abort"/></member>
     2765          </simplelist>
     2766        </refsect1>
     2767      </refentry>
     2768
     2769      <refentry id="f_process-abort">
     2770        <indexterm zone="f_process-abort">
     2771          <primary>process-abort</primary>
     2772        </indexterm>
     2773
     2774        <refnamediv>
     2775          <refname>PROCESS-ABORT</refname>
     2776          <refpurpose>Causes a specified process to process an abort
     2777          condition, as if it had invoked
     2778          <function>abort</function>.</refpurpose>
     2779          <refclass>Function</refclass>
     2780        </refnamediv>
     2781
     2782        <refsynopsisdiv>
     2783          <synopsis><function>process-abort</function> process
     2784          &optional; condition
     2785          => NIL</synopsis>
     2786        </refsynopsisdiv>
     2787
     2788        <refsect1>
     2789          <title>Arguments and Values</title>
     2790
     2791          <variablelist>
     2792            <varlistentry>
     2793              <term>process</term>
     2794              <listitem>
     2795                <para>a lisp process (thread).</para>
     2796              </listitem>
     2797            </varlistentry>
     2798            <varlistentry>
     2799              <term>condition</term>
     2800              <listitem>
     2801                <para>a lisp condition.  The default is NIL.</para>
     2802              </listitem>
     2803            </varlistentry>
     2804          </variablelist>
     2805        </refsect1>
     2806
     2807        <refsect1>
     2808          <title>Description</title>
     2809
     2810          <para>Entirely equivalent to calling
     2811          (<xref linkend="f_process-interrupt"/> <varname>process</varname>
     2812          (<function>lambda</function> ()
     2813          (<function>abort</function> <varname>condition</varname>))).
     2814          Causes <varname>process</varname> to transfer control to the
     2815          applicable handler or restart for <function>abort</function>.</para>
     2816
     2817          <para>If <varname>condition</varname> is non-NIL,
     2818          <function>process-abort</function> does not consider any
     2819          handlers which are explicitly bound to conditions other than
     2820          <varname>condition</varname>.</para>
     2821        </refsect1>
     2822
     2823        <refsect1>
     2824          <title>See Also</title>
     2825         
     2826          <simplelist type="inline">
     2827            <member><xref linkend="f_process-reset"/></member>
     2828            <member><xref linkend="f_process-kill"/></member>
     2829          </simplelist>
     2830        </refsect1>
     2831      </refentry>
     2832
     2833      <refentry id="v_ticks-per-second">
     2834        <indexterm zone="v_ticks-per-second">
     2835          <primary>*ticks-per-second*</primary>
     2836        </indexterm>
     2837
     2838        <refnamediv>
     2839          <refname>*TICKS-PER-SECOND*</refname>
     2840          <refpurpose>Bound to the clock resolution of the OS
     2841          scheduler.</refpurpose>
     2842          <refclass>Variable</refclass>
     2843        </refnamediv>
     2844
     2845          <refsect1>
     2846            <title>Value Type</title>
     2847
     2848            <para>A positive integer.</para>
     2849          </refsect1>
     2850
     2851          <refsect1>
     2852            <title>Initial Value</title>
     2853           
     2854            <para>The clock resoluton of the OS scheduler.  Currently,
     2855            both LinuxPPC and DarwinPPC yeild an initial value of 100.
     2856            </para>
     2857          </refsect1>
     2858
     2859        <refsect1>
     2860          <title>Description</title>
     2861
     2862          <para>This value is ordinarily of marginal interest at best,
     2863          but, for backward compatibility, some functions accept timeout
     2864          values expressed in "ticks".  This value gives the number of
     2865          ticks per second.</para>
     2866        </refsect1>
     2867
     2868        <refsect1>
     2869          <title>See Also</title>
     2870         
     2871          <simplelist type="inline">
     2872            <member><xref linkend="f_process-wait-with-timeout"/></member>
     2873          </simplelist>
     2874        </refsect1>
     2875      </refentry>
     2876
     2877      <refentry id="f_process-whostate">
     2878        <indexterm zone="f_process-whostate">
     2879          <primary>process-whostate</primary>
     2880        </indexterm>
     2881
     2882        <refnamediv>
     2883          <refname>PROCESS-WHOSTATE</refname>
     2884          <refpurpose>Returns a string which describes the status of
     2885          a specified process.</refpurpose>
     2886          <refclass>Function</refclass>
     2887        </refnamediv>
     2888
     2889        <refsynopsisdiv>
     2890          <synopsis><function>process-whostate</function> process
     2891          => whostate</synopsis>
     2892          <variablelist>
     2893            <varlistentry>
     2894              <term>process</term>
     2895              <listitem>
     2896                <para>a lisp process (thread).</para>
     2897              </listitem>
     2898            </varlistentry>
     2899            <varlistentry>
     2900              <term>whostate</term>
     2901              <listitem>
     2902                <para>a string which describes the "state" of
     2903                <varname>process</varname>.</para>
     2904              </listitem>
     2905            </varlistentry>
     2906          </variablelist>
     2907        </refsynopsisdiv>
     2908
     2909        <refsect1>
     2910          <title>Description</title>
     2911
     2912          <para>This information is primarily for the benefit of
     2913          debugging tools.  <varname>whostate</varname> is a terse report
     2914          on what <varname>process</varname> is doing, or not doing,
     2915          and why.</para>
     2916
     2917          <para>If the process is currently waiting in a call to
     2918          <xref linkend="f_process-wait"/> or
     2919          <xref linkend="f_process-wait-with-timeout"/>, its
     2920          <function>process-whostate</function> will be the value
     2921          which was passed to that function as <varname>whostate</varname>.
     2922          </para>
     2923        </refsect1>
     2924
     2925        <refsect1>
     2926          <title>See Also</title>
     2927         
     2928          <simplelist type="inline">
     2929            <member><xref linkend="f_process-wait"/></member>
     2930            <member><xref linkend="f_process-wait-with-timeout"/></member>
     2931            <member><xref linkend="m_with-terminal-input"/></member>
     2932          </simplelist>
     2933        </refsect1>
     2934
     2935        <refsect1>
     2936          <title>Notes</title>
     2937
     2938          <para>This should arguably be SETFable, but doesn't seem to
     2939          ever have been.</para>
     2940        </refsect1>
     2941      </refentry>
     2942
     2943      <refentry id="f_process-allow-schedule">
     2944        <indexterm zone="f_process-allow-schedule">
     2945          <primary>process-allow-schedule</primary>
     2946        </indexterm>
     2947
     2948        <refnamediv>
     2949          <refname>PROCESS-ALLOW-SCHEDULE</refname>
     2950          <refpurpose>Used for cooperative multitasking; probably never
     2951          necessary.</refpurpose>
     2952          <refclass>Function</refclass>
     2953        </refnamediv>
     2954
     2955        <refsynopsisdiv>
     2956          <synopsis><function>process-allow-schedule</function></synopsis>
     2957        </refsynopsisdiv>
     2958
     2959        <refsect1>
     2960          <title>Description</title>
     2961
     2962          <para>Advises the OS scheduler that the current thread has nothing
     2963          useful to do and that it should try to find some other thread to
     2964          schedule in its place. There's almost always a better
     2965          alternative, such as waiting for some specific event to
     2966          occur.  For example, you could use a lock or semaphore.</para>
     2967        </refsect1>
     2968
     2969        <refsect1>
     2970          <title>See Also</title>
     2971         
     2972          <simplelist type="inline">
     2973            <member><xref linkend="f_make-lock"/></member>
     2974            <member><xref linkend="f_make-read-write-lock"/></member>
     2975            <member><xref linkend="f_make-semaphore"/></member>
     2976            <member><xref linkend="f_process-input-wait"/></member>
     2977            <member><xref linkend="f_process-output-wait"/></member>
     2978            <member><xref linkend="m_with-terminal-input"/></member>
     2979          </simplelist>
     2980        </refsect1>
     2981
     2982        <refsect1>
     2983          <title>Notes</title>
     2984
     2985          <para>This is a holdover from the days of cooperative
     2986          multitasking.  All modern general-purpose operating systems use
     2987          preemptive multitasking.</para>
     2988        </refsect1>
     2989      </refentry>
     2990
     2991      <refentry id="f_process-wait">
     2992        <indexterm zone="f_process-wait">
     2993          <primary>process-wait</primary>
     2994        </indexterm>
     2995
     2996        <refnamediv>
     2997          <refname>PROCESS-WAIT</refname>
     2998          <refpurpose>Causes the current lisp process (thread) to wait for
     2999          a given
     3000          predicate to return true.</refpurpose>
     3001          <refclass>Function</refclass>
     3002        </refnamediv>
     3003
     3004        <refsynopsisdiv>
     3005          <synopsis><function>process-wait</function>
     3006          whostate function &rest; args => result</synopsis>
     3007        </refsynopsisdiv>
     3008
     3009        <refsect1>
     3010          <title>Arguments and Values</title>
     3011
     3012          <variablelist>
     3013            <varlistentry>
     3014              <term>whostate</term>
     3015
     3016              <listitem>
     3017                <para>a string, which will be the value of
     3018                <xref linkend="f_process-whostate"/>
     3019                while the process is waiting.</para>
     3020              </listitem>
     3021            </varlistentry>
     3022            <varlistentry>
     3023              <term>function</term>
     3024              <listitem>
     3025                <para>a function, designated by itself or by a symbol
     3026                which names it.
     3027                </para>
     3028              </listitem>
     3029            </varlistentry>
     3030            <varlistentry>
     3031              <term>args</term>
     3032              <listitem>
     3033                <para>a list of values, appropriate as arguments to
     3034                <varname>function</varname>.</para>
     3035              </listitem>
     3036            </varlistentry>
     3037            <varlistentry>
     3038              <term>result</term>
     3039              <listitem>
     3040                <para>NIL.</para>
     3041              </listitem>
     3042            </varlistentry>
     3043          </variablelist>
     3044        </refsect1>
     3045
     3046        <refsect1>
     3047          <title>Description</title>
     3048
     3049          <para>Causes the current lisp process (thread) to repeatedly
     3050          apply <varname>function</varname> to
     3051          <varname>args</varname> until the call returns a true result, then
     3052          returns NIL. After
     3053          each failed call, yields the CPU as if by
     3054          <xref linkend="f_process-allow-schedule"/>.</para>
     3055         
     3056          <para>
     3057          As with <xref linkend="f_process-allow-schedule"/>, it's almost
     3058          always more efficient to wait for some
     3059          specific event to occur; this isn't exactly busy-waiting, but
     3060          the OS scheduler can do a better job of scheduling if it's given
     3061          the relevant information.  For example, you could use a lock
     3062          or semaphore.</para>
     3063        </refsect1>
     3064
     3065        <refsect1>
     3066          <title>See Also</title>
     3067         
     3068          <simplelist type="inline">
     3069            <member><xref linkend="f_process-whostate"/></member>
     3070            <member><xref linkend="f_process-wait-with-timeout"/></member>
     3071            <member><xref linkend="f_make-lock"/></member>
     3072            <member><xref linkend="f_make-read-write-lock"/></member>
     3073            <member><xref linkend="f_make-semaphore"/></member>
     3074            <member><xref linkend="f_process-input-wait"/></member>
     3075            <member><xref linkend="f_process-output-wait"/></member>
     3076            <member><xref linkend="m_with-terminal-input"/></member>
     3077          </simplelist>
     3078        </refsect1>
     3079      </refentry>
     3080
     3081      <refentry id="f_process-wait-with-timeout">
     3082        <indexterm zone="f_process-wait-with-timeout">
     3083          <primary>process-wait-with-timeout</primary>
     3084        </indexterm>
     3085
     3086        <refnamediv>
     3087          <refname>PROCESS-WAIT-WITH-TIMEOUT</refname>
     3088          <refpurpose>Causes the current thread to wait for a given
     3089          predicate to return true, or for a timeout to expire.</refpurpose>
     3090          <refclass>Function</refclass>
     3091        </refnamediv>
     3092
     3093        <refsynopsisdiv>
     3094          <synopsis><function>process-wait-with-timeout</function>
     3095          whostate ticks function args => result</synopsis>
     3096        </refsynopsisdiv>
     3097
     3098        <refsect1>
     3099          <title>Arguments and Values</title>
     3100
     3101          <variablelist>
     3102            <varlistentry>
     3103              <term>whostate</term>
     3104              <listitem>
     3105                <para>a string, which will be the value of
     3106                <xref linkend="f_process-whostate"/>
     3107                while the process is waiting.</para>
     3108              </listitem>
     3109            </varlistentry>
     3110            <varlistentry>
     3111              <term>ticks</term>
     3112              <listitem>
     3113                <para>either a positive integer expressing a duration
     3114                in "ticks" (see <xref linkend="v_ticks-per-second"/>),
     3115                or NIL.</para>
     3116              </listitem>
     3117            </varlistentry>
     3118            <varlistentry>
     3119              <term>function</term>
     3120              <listitem>
     3121                <para>a function, designated by itself or by a symbol
     3122                which names it.</para>
     3123              </listitem>
     3124            </varlistentry>
     3125            <varlistentry>
     3126              <term>args</term>
     3127              <listitem>
     3128                <para>a list of values, appropriate as arguments to
     3129                <varname>function</varname>.</para>
     3130              </listitem>
     3131            </varlistentry>
     3132            <varlistentry>
     3133              <term>result</term>
     3134              <listitem>
     3135                <para>T if <function>process-wait-with-timeout</function>
     3136                returned because its <varname>function</varname> returned
     3137                true, or NIL if it returned because the duration
     3138                <varname>ticks</varname> has been exceeded.</para>
     3139              </listitem>
     3140            </varlistentry>
     3141          </variablelist>
     3142        </refsect1>
     3143
     3144        <refsect1>
     3145          <title>Description</title>
     3146
     3147          <para>If <varname>ticks</varname> is NIL, behaves exactly like
     3148          <xref linkend="f_process-wait"/>, except for returning T.
     3149          Otherwise, <varname>function</varname> will be tested repeatedly,
     3150          in the same
     3151          kind of test/yield loop as in <xref linkend="f_process-wait"/>>
     3152          until either <varname>function</varname> returns true,
     3153          or the duration <varname>ticks</varname> has been exceeded.
     3154          </para>
     3155
     3156          <para> Having already read the descriptions of
     3157          <xref linkend="f_process-allow-schedule"/> and
     3158          <xref linkend="f_process-wait"/>, the
     3159          astute reader has no doubt anticipated the observation that
     3160          better alternatives should be used whenever possible.</para>
     3161        </refsect1>
     3162
     3163        <refsect1>
     3164          <title>See Also</title>
     3165         
     3166          <simplelist type="inline">
     3167            <member><xref linkend="v_ticks-per-second"/></member>
     3168            <member><xref linkend="f_process-whostate"/></member>
     3169            <member><xref linkend="f_process-wait"/></member>
     3170            <member><xref linkend="f_make-lock"/></member>
     3171            <member><xref linkend="f_make-read-write-lock"/></member>
     3172            <member><xref linkend="f_make-semaphore"/></member>
     3173            <member><xref linkend="f_process-input-wait"/></member>
     3174            <member><xref linkend="f_process-output-wait"/></member>
     3175            <member><xref linkend="m_with-terminal-input"/></member>
     3176          </simplelist>
     3177        </refsect1>
     3178      </refentry>
     3179
     3180      <refentry id="m_without-interrupts">
     3181        <indexterm zone="m_without-interrupts">
     3182          <primary>without-interrupts</primary>
     3183        </indexterm>
     3184
     3185        <refnamediv>
     3186          <refname>WITHOUT-INTERRUPTS</refname>
     3187          <refpurpose>Evaluates its body in an environment in which
     3188          process-interrupt requests are deferred.</refpurpose>
     3189          <refclass>Macro</refclass>
     3190        </refnamediv>
     3191
     3192        <refsynopsisdiv>
     3193          <synopsis><function>without-interrupts</function>
     3194          &body; body => result</synopsis>
     3195        </refsynopsisdiv>
     3196
     3197        <refsect1>
     3198          <title>Arguments and Values</title>
     3199
     3200          <variablelist>
     3201            <varlistentry>
     3202              <term>body</term>
     3203              <listitem>
     3204                <para>an implicit progn.</para>
     3205              </listitem>
     3206            </varlistentry>
     3207            <varlistentry>
     3208              <term>result</term>
     3209              <listitem>
     3210                <para>the primary value returned by
     3211                <varname>body</varname>.</para>
     3212              </listitem>
     3213            </varlistentry>
     3214          </variablelist>
     3215        </refsect1>
     3216
     3217        <refsect1>
     3218          <title>Description</title>
     3219
     3220          <para>Executes <varname>body</varname>
     3221          in an environment in which <xref linkend="f_process-interrupt"/>
     3222          requests are
     3223          deferred. As noted in the description of
     3224          <xref linkend="f_process-interrupt"/>, this has nothing to do
     3225          with the
     3226          scheduling of other threads; it may be necessary to inhibit
     3227          <xref linkend="f_process-interrupt"/> handling when
     3228          (for instance) modifying some data
     3229          structure (for which the current thread holds an appropriate lock)
     3230          in some manner that&#39;s not reentrant.</para>
     3231        </refsect1>
     3232
     3233        <refsect1>
     3234          <title>See Also</title>
     3235         
     3236          <simplelist type="inline">
     3237            <member><xref linkend="f_process-interrupt"/></member>
     3238          </simplelist>
     3239        </refsect1>
     3240      </refentry>
     3241
     3242      <refentry id="f_make-lock">
     3243        <indexterm zone="f_make-lock">
     3244          <primary>make-lock</primary>
     3245        </indexterm>
     3246
     3247        <refnamediv>
     3248          <refname>MAKE-LOCK</refname>
     3249          <refpurpose>Creates and returns a lock object, which can
     3250          be used for synchronization between threads.</refpurpose>
     3251          <refclass>Function</refclass>
     3252        </refnamediv>
     3253
     3254        <refsynopsisdiv>
     3255          <synopsis><function>make-lock</function> &optional;
     3256          name => lock</synopsis>
     3257        </refsynopsisdiv>
     3258
     3259        <refsect1>
     3260          <title>Arguments and Values</title>
     3261
     3262          <variablelist>
     3263            <varlistentry>
     3264              <term>name</term>
     3265              <listitem>
     3266                <para>any lisp object; saved as part of
     3267                <varname>lock</varname>.  Typically a string or symbol
     3268                which may appear in the <xref linkend="f_process-whostate"/>s
     3269                of threads which are waiting for <varname>lock</varname>.
     3270                </para>
     3271              </listitem>
     3272            </varlistentry>
     3273            <varlistentry>
     3274              <term>lock</term>
     3275              <listitem>
     3276                <para>a newly-allocated object of type CCL:LOCK.</para>
     3277              </listitem>
     3278            </varlistentry>
     3279          </variablelist>
     3280        </refsect1>
     3281
     3282        <refsect1>
     3283          <title>Description</title>
     3284
     3285          <para>Creates and returns a lock object, which can
     3286          be used to synchronize access to some shared resource.
     3287          <varname>lock</varname> is
     3288          initially in a &#34;free&#34; state; a lock can also be
     3289          &#34;owned&#34; by a
     3290          thread.</para>
     3291        </refsect1>
     3292
     3293        <refsect1>
     3294          <title>See Also</title>
     3295         
     3296          <simplelist type="inline">
     3297            <member><xref linkend="m_with-lock-grabbed"/></member>
     3298            <member><xref linkend="f_grab-lock"/></member>
     3299            <member><xref linkend="f_release-lock"/></member>
     3300            <member><xref linkend="f_try-lock"/></member>
     3301            <member><xref linkend="f_make-read-write-lock"/></member>
     3302            <member><xref linkend="f_make-semaphore"/></member>
     3303            <member><xref linkend="f_process-input-wait"/></member>
     3304            <member><xref linkend="f_process-output-wait"/></member>
     3305            <member><xref linkend="m_with-terminal-input"/></member>
     3306          </simplelist>
     3307        </refsect1>
     3308      </refentry>
     3309
     3310      <refentry id="m_with-lock-grabbed">
     3311        <indexterm zone="m_with-lock-grabbed">
     3312          <primary>with-lock-grabbed</primary>
     3313        </indexterm>
     3314
     3315        <refnamediv>
     3316          <refname>WITH-LOCK-GRABBED</refname>
     3317          <refpurpose>Waits until a given lock can be obtained, then
     3318          evaluates its body with the lock held.</refpurpose>
     3319          <refclass>Macro</refclass>
     3320        </refnamediv>
     3321
     3322        <refsynopsisdiv>
     3323          <synopsis><function>with-lock-grabbed</function>
     3324          (lock) &body; body</synopsis>
     3325        </refsynopsisdiv>
     3326
     3327        <refsect1>
     3328          <title>Arguments and Values</title>
     3329
     3330          <variablelist>
     3331            <varlistentry>
     3332              <term>lock</term>
     3333              <listitem>
     3334                <para>an object of type CCL:LOCK.</para>
     3335              </listitem>
     3336            </varlistentry>
     3337            <varlistentry>
     3338              <term>body</term>
     3339              <listitem>
     3340                <para>an implicit progn.</para>
     3341              </listitem>
     3342            </varlistentry>
     3343            <varlistentry>
     3344              <term>result</term>
     3345              <listitem>
     3346                <para>the primary value returned by
     3347                <varname>body</varname>.</para>
     3348              </listitem>
     3349            </varlistentry>
     3350          </variablelist>
     3351        </refsect1>
     3352
     3353        <refsect1>
     3354          <title>Description</title>
     3355
     3356          <para>Waits until <varname>lock</varname> is either free or
     3357          owned by the calling
     3358          thread, then excutes <varname>body</varname> with the
     3359          lock owned by the calling thread. If <varname>lock</varname>
     3360          was free when <function>with-lock-grabbed</function> was called,
     3361          it is restored to a free state after <varname>body</varname>
     3362          is executed.</para>
     3363        </refsect1>
     3364
     3365        <refsect1>
     3366          <title>See Also</title>
     3367         
     3368          <simplelist type="inline">
     3369            <member><xref linkend="f_make-lock"/></member>
     3370            <member><xref linkend="f_grab-lock"/></member>
     3371            <member><xref linkend="f_release-lock"/></member>
     3372            <member><xref linkend="f_try-lock"/></member>
     3373            <member><xref linkend="f_make-read-write-lock"/></member>
     3374            <member><xref linkend="f_make-semaphore"/></member>
     3375            <member><xref linkend="f_process-input-wait"/></member>
     3376            <member><xref linkend="f_process-output-wait"/></member>
     3377            <member><xref linkend="m_with-terminal-input"/></member>
     3378          </simplelist>
     3379        </refsect1>
     3380      </refentry>
     3381
     3382      <refentry id="f_grab-lock">
     3383        <indexterm zone="f_grab-lock">
     3384          <primary>grab-lock</primary>
     3385        </indexterm>
     3386
     3387        <refnamediv>
     3388          <refname>GRAB-LOCK</refname>
     3389          <refpurpose>Waits until a given lock can be obtained, then
     3390          obtains it.</refpurpose>
     3391          <refclass>Function</refclass>
     3392        </refnamediv>
     3393
     3394        <refsynopsisdiv>
     3395          <synopsis><function>grab-lock</function> lock</synopsis>
     3396        </refsynopsisdiv>
     3397
     3398        <refsect1>
     3399          <title>Arguments and Values</title>
     3400
     3401          <variablelist>
     3402            <varlistentry>
     3403              <term>lock</term>
     3404              <listitem>
     3405                <para>an object of type CCL:LOCK.</para>
     3406              </listitem>
     3407            </varlistentry>
     3408          </variablelist>
     3409        </refsect1>
     3410
     3411        <refsect1>
     3412          <title>Description</title>
     3413
     3414          <para>Blocks until <varname>lock</varname> is owned by the
     3415          calling thread.</para>
     3416
     3417          <para>The macro <xref linkend="m_with-lock-grabbed"/>
     3418          <emphasis>could</emphasis> be defined in
     3419          terms of <function>grab-lock</function> and
     3420          <xref linkend="f_release-lock"/>, but it is actually
     3421          implemented at a slightly lower level.</para>
     3422        </refsect1>
     3423
     3424        <refsect1>
     3425          <title>See Also</title>
     3426         
     3427          <simplelist type="inline">
     3428            <member><xref linkend="f_make-lock"/></member>
     3429            <member><xref linkend="m_with-lock-grabbed"/></member>
     3430            <member><xref linkend="f_release-lock"/></member>
     3431            <member><xref linkend="f_try-lock"/></member>
     3432            <member><xref linkend="f_make-read-write-lock"/></member>
     3433            <member><xref linkend="f_make-semaphore"/></member>
     3434            <member><xref linkend="f_process-input-wait"/></member>
     3435            <member><xref linkend="f_process-output-wait"/></member>
     3436            <member><xref linkend="m_with-terminal-input"/></member>
     3437          </simplelist>
     3438        </refsect1>
     3439      </refentry>
     3440
     3441      <refentry id="f_release-lock">
     3442        <indexterm zone="f_release-lock">
     3443          <primary>release-lock</primary>
     3444        </indexterm>
     3445
     3446        <refnamediv>
     3447          <refname>RELEASE-LOCK</refname>
     3448          <refpurpose>Relinquishes ownership of a given lock.</refpurpose>
     3449          <refclass>Function</refclass>
     3450        </refnamediv>
     3451
     3452        <refsynopsisdiv>
     3453          <synopsis><function>release-lock</function> lock</synopsis>
     3454        </refsynopsisdiv>
     3455
     3456        <refsect1>
     3457          <title>Arguments and Values</title>
     3458
     3459          <variablelist>
     3460            <varlistentry>
     3461              <term>lock</term>
     3462              <listitem>
     3463                <para>an object of type CCL:LOCK.</para>
     3464              </listitem>
     3465            </varlistentry>
     3466          </variablelist>
     3467        </refsect1>
     3468
     3469        <refsect1>
     3470          <title>Description</title>
     3471
     3472          <para>Signals an error of type CCL:LOCK-NOT-OWNER if
     3473          <varname>lock</varname>
     3474          is not already owned by the calling thread; otherwise, undoes the
     3475          effect of one previous
     3476          <xref linkend="f_grab-lock"/>.  If this means that
     3477          <function>release-lock</function> has now been called on
     3478          <varname>lock</varname> the same number of times as
     3479          <xref linkend="f_grab-lock"/> has, <varname>lock</varname>
     3480          becomes free.</para>
     3481        </refsect1>
     3482
     3483        <refsect1>
     3484          <title>See Also</title>
     3485         
     3486          <simplelist type="inline">
     3487            <member><xref linkend="f_make-lock"/></member>
     3488            <member><xref linkend="m_with-lock-grabbed"/></member>
     3489            <member><xref linkend="f_grab-lock"/></member>
     3490            <member><xref linkend="f_try-lock"/></member>
     3491            <member><xref linkend="f_make-read-write-lock"/></member>
     3492            <member><xref linkend="f_make-semaphore"/></member>
     3493            <member><xref linkend="f_process-input-wait"/></member>
     3494            <member><xref linkend="f_process-output-wait"/></member>
     3495            <member><xref linkend="m_with-terminal-input"/></member>
     3496          </simplelist>
     3497        </refsect1>
     3498      </refentry>
     3499
     3500      <refentry id="f_try-lock">
     3501        <indexterm zone="f_try-lock">
     3502          <primary>try-lock</primary>
     3503        </indexterm>
     3504
     3505        <refnamediv>
     3506          <refname>TRY-LOCK</refname>
     3507          <refpurpose>Obtains the given lock, but only if it is not
     3508          necessary to wait for it.</refpurpose>
     3509          <refclass>Function</refclass>
     3510        </refnamediv>
     3511
     3512        <refsynopsisdiv>
     3513          <synopsis><function>try-lock</function> lock => result</synopsis>
     3514        </refsynopsisdiv>
     3515
     3516        <refsect1>
     3517          <title>Arguments and Values</title>
     3518
     3519          <variablelist>
     3520            <varlistentry>
     3521              <term>lock</term>
     3522              <listitem>
     3523                <para>an object of type CCL:LOCK.</para>
     3524              </listitem>
     3525            </varlistentry>
     3526            <varlistentry>
     3527              <term>result</term>
     3528              <listitem>
     3529                <para>T if <varname>lock</varname> has been obtained,
     3530                or NIL if it has not.</para>
     3531              </listitem>
     3532            </varlistentry>
     3533          </variablelist>
     3534        </refsect1>
     3535
     3536        <refsect1>
     3537          <title>Description</title>
     3538
     3539          <para>Tests whether <varname>lock</varname>
     3540          can be obtained without blocking - that is, either
     3541          <varname>lock</varname> is already free, or it is already owned
     3542          by <xref linkend="v_current-process"/>.  If it can,
     3543          causes it to
     3544          be owned by the calling lisp process (thread) and returns T.
     3545          Otherwise, the lock
     3546          is already owned by another thread and cannot be obtained without
     3547          blocking; NIL is returned in this case.</para>
     3548        </refsect1>
     3549
     3550        <refsect1>
     3551          <title>See Also</title>
     3552         
     3553          <simplelist type="inline">
     3554            <member><xref linkend="f_make-lock"/></member>
     3555            <member><xref linkend="m_with-lock-grabbed"/></member>
     3556            <member><xref linkend="f_grab-lock"/></member>
     3557            <member><xref linkend="f_release-lock"/></member>
     3558            <member><xref linkend="f_make-read-write-lock"/></member>
     3559            <member><xref linkend="f_make-semaphore"/></member>
     3560            <member><xref linkend="f_process-input-wait"/></member>
     3561            <member><xref linkend="f_process-output-wait"/></member>
     3562            <member><xref linkend="m_with-terminal-input"/></member>
     3563          </simplelist>
     3564        </refsect1>
     3565      </refentry>
     3566
     3567      <refentry id="f_make-read-write-lock">
     3568        <indexterm zone="f_make-read-write-lock">
     3569          <primary>make-read-write-lock</primary>
     3570        </indexterm>
     3571
     3572        <refnamediv>
     3573          <refname>MAKE-READ-WRITE-LOCK</refname>
     3574          <refpurpose>Creates and returns a read-write lock, which can
     3575          be used for synchronization between threads.</refpurpose>
     3576          <refclass>Function</refclass>
     3577        </refnamediv>
     3578
     3579        <refsynopsisdiv>
     3580          <synopsis><function>make-read-write-lock</function>
     3581          => read-write-lock</synopsis>
     3582        </refsynopsisdiv>
     3583
     3584        <refsect1>
     3585          <title>Arguments and Values</title>
     3586
     3587          <variablelist>
     3588            <varlistentry>
     3589              <term>read-write-lock</term>
     3590              <listitem>
     3591                <para>a newly-allocated object of type
     3592                CCL:READ-WRITE-LOCK.</para>
     3593              </listitem>
     3594            </varlistentry>
     3595          </variablelist>
     3596        </refsect1>
     3597
     3598        <refsect1>
     3599          <title>Description</title>
     3600
     3601          <para>Creates and returns an object of type CCL::READ-WRITE-LOCK.
     3602          A read-write lock may, at any given time, belong to any number
     3603          of lisp processes (threads) which act as "readers"; or, it may
     3604          belong to at most one process which acts as a "writer".  A
     3605          read-write lock may never be held by a reader at the same time as
     3606          a writer.  Intially, <varname>read-write-lock</varname> has
     3607          no readers and no writers.</para>
     3608        </refsect1>
     3609
     3610        <refsect1>
     3611          <title>See Also</title>
     3612         
     3613          <simplelist type="inline">
     3614            <member><xref linkend="m_with-read-lock"/></member>
     3615            <member><xref linkend="m_with-write-lock"/></member>
     3616            <member><xref linkend="f_make-lock"/></member>
     3617            <member><xref linkend="f_make-semaphore"/></member>
     3618            <member><xref linkend="f_process-input-wait"/></member>
     3619            <member><xref linkend="f_process-output-wait"/></member>
     3620            <member><xref linkend="m_with-terminal-input"/></member>
     3621          </simplelist>
     3622        </refsect1>
     3623
     3624        <refsect1>
     3625          <title>Notes</title>
     3626
     3627          <para>There probably should be some way to
     3628          atomically &#34;promote&#34; a reader, making it a writer without
     3629          releasing the lock, which could otherwise cause delay.</para>
     3630        </refsect1>
     3631      </refentry>
     3632
     3633      <refentry id="m_with-read-lock">
     3634        <indexterm zone="m_with-read-lock">
     3635          <primary>with-read-lock</primary>
     3636        </indexterm>
     3637
     3638        <refnamediv>
     3639          <refname>WITH-READ-LOCK</refname>
     3640          <refpurpose>Waits until a given lock is available for
     3641          read-only access, then evaluates its body with the lock
     3642          held.</refpurpose>
     3643          <refclass>Macro</refclass>
     3644        </refnamediv>
     3645
     3646        <refsynopsisdiv>
     3647          <synopsis><function>with-read-lock</function>
     3648          (read-write-lock) &body; body => result</synopsis>
     3649        </refsynopsisdiv>
     3650
     3651        <refsect1>
     3652          <title>Arguments and Values</title>
     3653
     3654          <variablelist>
     3655            <varlistentry>
     3656              <term>read-write-lock</term>
     3657              <listitem>
     3658                <para>an object of type
     3659                CCL:READ-WRITE-LOCK.</para>
     3660              </listitem>
     3661            </varlistentry>
     3662            <varlistentry>
     3663              <term>body</term>
     3664              <listitem>
     3665                <para>an implicit progn.</para>
     3666              </listitem>
     3667            </varlistentry>
     3668            <varlistentry>
     3669              <term>result</term>
     3670              <listitem>
     3671                <para>the primary value returned by
     3672                <varname>body</varname>.</para>
     3673              </listitem>
     3674            </varlistentry>
     3675          </variablelist>
     3676        </refsect1>
     3677
     3678        <refsect1>
     3679          <title>Description</title>
     3680
     3681          <para>Waits until <varname>read-write-lock</varname> has no
     3682          writer,
     3683          ensures that <xref linkend="v_current-process"/> is a
     3684          reader of it, then executes <varname>body</varname>.
     3685          </para>
     3686
     3687          <para>After executing <varname>body</varname>, if
     3688          <xref linkend="v_current-process"/> was not a reader of
     3689          <varname>read-write-lock</varname> before
     3690          <function>with-read-lock</function> was called, the lock is
     3691          released.  If it was already a reader, it remains one.</para>
     3692        </refsect1>
     3693
     3694        <refsect1>
     3695          <title>See Also</title>
     3696         
     3697          <simplelist type="inline">
     3698            <member><xref linkend="f_make-read-write-lock"/></member>
     3699            <member><xref linkend="m_with-write-lock"/></member>
     3700            <member><xref linkend="f_make-lock"/></member>
     3701            <member><xref linkend="f_make-semaphore"/></member>
     3702            <member><xref linkend="f_process-input-wait"/></member>
     3703            <member><xref linkend="f_process-output-wait"/></member>
     3704            <member><xref linkend="m_with-terminal-input"/></member>
     3705          </simplelist>
     3706        </refsect1>
     3707      </refentry>
     3708
     3709      <refentry id="m_with-write-lock">
     3710        <indexterm zone="m_with-write-lock">
     3711          <primary>with-write-lock</primary>
     3712        </indexterm>
     3713
     3714        <refnamediv>
     3715          <refname>WITH-WRITE-LOCK</refname>
     3716          <refpurpose>Waits until the given lock is available for write
     3717          access, then executes its body with the lock held.</refpurpose>
     3718          <refclass>Macro</refclass>
     3719        </refnamediv>
     3720
     3721        <refsynopsisdiv>
     3722          <synopsis><function>with-write-lock</function>
     3723          (read-write-lock) &body; body</synopsis>
     3724        </refsynopsisdiv>
     3725
     3726        <refsect1>
     3727          <title>Arguments and Values</title>
     3728
     3729          <variablelist>
     3730            <varlistentry>
     3731              <term>read-write-lock</term>
     3732              <listitem>
     3733                <para>an object of type
     3734                CCL:READ-WRITE-LOCK.</para>
     3735              </listitem>
     3736            </varlistentry>
     3737            <varlistentry>
     3738              <term>body</term>
     3739              <listitem>
     3740                <para>an implicit progn.</para>
     3741              </listitem>
     3742            </varlistentry>
     3743            <varlistentry>
     3744              <term>result</term>
     3745              <listitem>
     3746                <para>the primary value returned by
     3747                <varname>body</varname>.</para>
     3748              </listitem>
     3749            </varlistentry>
     3750          </variablelist>
     3751        </refsect1>
     3752
     3753        <refsect1>
     3754          <title>Description</title>
     3755
     3756          <para>Waits until <varname>read-write-lock</varname> has no
     3757          readers and no writer other than <xref linkend="v_current-process"/>,
     3758          then ensures that <xref linkend="v_current-process"/> is the
     3759          writer of it.  With the lock held, executes <varname>body</varname>.
     3760          </para>
     3761
     3762          <para>After executing <varname>body</varname>, if
     3763          <xref linkend="v_current-process"/> was not the writer of
     3764          <varname>read-write-lock</varname> before
     3765          <function>with-write-lock</function> was called, the lock is
     3766          released.  If it was already the writer, it remains the
     3767          writer.</para>
     3768        </refsect1>
     3769
     3770        <refsect1>
     3771          <title>See Also</title>
     3772         
     3773          <simplelist type="inline">
     3774            <member><xref linkend="f_make-read-write-lock"/></member>
     3775            <member><xref linkend="m_with-read-lock"/></member>
     3776            <member><xref linkend="f_make-lock"/></member>
     3777            <member><xref linkend="f_make-semaphore"/></member>
     3778            <member><xref linkend="f_process-input-wait"/></member>
     3779            <member><xref linkend="f_process-output-wait"/></member>
     3780            <member><xref linkend="m_with-terminal-input"/></member>
     3781          </simplelist>
     3782        </refsect1>
     3783      </refentry>
     3784
     3785      <refentry id="f_make-semaphore">
     3786        <indexterm zone="f_make-semaphore">
     3787          <primary>make-semaphore</primary>
     3788        </indexterm>
     3789
     3790        <refnamediv>
     3791          <refname>MAKE-SEMAPHORE</refname>
     3792          <refpurpose>Creates and returns a semaphore, which can be used
     3793          for synchronization between threads.</refpurpose>
     3794          <refclass>Function</refclass>
     3795        </refnamediv>
     3796
     3797        <refsynopsisdiv>
     3798          <synopsis><function>make-semaphore</function>
     3799          => semaphore</synopsis>
     3800        </refsynopsisdiv>
     3801
     3802        <refsect1>
     3803          <title>Arguments and Values</title>
     3804         
     3805          <variablelist>
     3806            <varlistentry>
     3807              <term>semaphore</term>
     3808              <listitem>
     3809                <para>a newly-allocated object of type CCL:SEMAPHORE.</para>
     3810              </listitem>
     3811            </varlistentry>
     3812          </variablelist>
     3813        </refsect1>
     3814
     3815        <refsect1>
     3816          <title>Description</title>
     3817
     3818          <para>Creates and returns an object of type CCL:SEMAPHORE.
     3819          A semaphore has an associated "count" which may be incremented
     3820          and decremented atomically; incrementing it represents sending
     3821          a signal, and decrementing it represents handling that signal.
     3822          <varname>semaphore</varname> has an initial count of 0.</para>
     3823        </refsect1>
     3824
     3825        <refsect1>
     3826          <title>See Also</title>
     3827         
     3828          <simplelist type="inline">
     3829            <member><xref linkend="f_signal-semaphore"/></member>
     3830            <member><xref linkend="f_wait-on-semaphore"/></member>
     3831            <member><xref linkend="f_timed-wait-on-semaphore"/></member>
     3832            <member><xref linkend="f_make-lock"/></member>
     3833            <member><xref linkend="f_make-read-write-lock"/></member>
     3834            <member><xref linkend="f_process-input-wait"/></member>
     3835            <member><xref linkend="f_process-output-wait"/></member>
     3836            <member><xref linkend="m_with-terminal-input"/></member>
     3837          </simplelist>
     3838        </refsect1>
     3839      </refentry>
     3840
     3841      <refentry id="f_signal-semaphore">
     3842        <indexterm zone="f_signal-semaphore">
     3843          <primary>signal-semaphore</primary>
     3844        </indexterm>
     3845
     3846        <refnamediv>
     3847          <refname>SIGNAL-SEMAPHORE</refname>
     3848          <refpurpose>Atomically increments the count of a given
     3849          semaphore.</refpurpose>
     3850          <refclass>Function</refclass>
     3851        </refnamediv>
     3852
     3853        <refsynopsisdiv>
     3854          <synopsis><function>signal-semaphore</function>
     3855          semaphore => result</synopsis>
     3856        </refsynopsisdiv>
     3857
     3858        <refsect1>
     3859          <title>Arguments and Values</title>
     3860         
     3861          <variablelist>
     3862            <varlistentry>
     3863              <term>semaphore</term>
     3864              <listitem>
     3865                <para>an object of type CCL:SEMAPHORE.</para>
     3866              </listitem>
     3867            </varlistentry>
     3868            <varlistentry>
     3869              <term>result</term>
     3870              <listitem>
     3871                <para>an integer representing an error identifier
     3872                which was returned by the underlying OS call.</para>
     3873              </listitem>
     3874            </varlistentry>
     3875          </variablelist>
     3876        </refsect1>
     3877
     3878        <refsect1>
     3879          <title>Description</title>
     3880
     3881          <para>Atomically increments <varname>semaphore</varname>'s
     3882          "count" by 1; this
     3883          may enable a waiting thread to resume execution.</para>
     3884        </refsect1>
     3885
     3886        <refsect1>
     3887          <title>See Also</title>
     3888         
     3889          <simplelist type="inline">
     3890            <member><xref linkend="f_make-semaphore"/></member>
     3891            <member><xref linkend="f_wait-on-semaphore"/></member>
     3892            <member><xref linkend="f_timed-wait-on-semaphore"/></member>
     3893            <member><xref linkend="f_make-lock"/></member>
     3894            <member><xref linkend="f_make-read-write-lock"/></member>
     3895            <member><xref linkend="f_process-input-wait"/></member>
     3896            <member><xref linkend="f_process-output-wait"/></member>
     3897            <member><xref linkend="m_with-terminal-input"/></member>
     3898          </simplelist>
     3899        </refsect1>
     3900
     3901        <refsect1>
     3902          <title>Notes</title>
     3903
     3904          <para><varname>result</varname> should probably be interpreted
     3905          and acted on by <function>signal-semaphore</function>, because
     3906          it is not likely to be meaningful to a lisp program, and the
     3907          most common cause of failure is a type error.</para>
     3908        </refsect1>
     3909      </refentry>
     3910
     3911      <refentry id="f_wait-on-semaphore">
     3912        <indexterm zone="f_wait-on-semaphore">
     3913          <primary>wait-on-semaphore</primary>
     3914        </indexterm>
     3915
     3916        <refnamediv>
     3917          <refname>WAIT-ON-SEMAPHORE</refname>
     3918          <refpurpose>Waits until the given semaphore has a positive
     3919          count which can be atomically decremented.</refpurpose>
     3920          <refclass>Function</refclass>
     3921        </refnamediv>
     3922
     3923        <refsynopsisdiv>
     3924          <synopsis><function>wait-on-semaphore</function>
     3925          semaphore => result</synopsis>
     3926        </refsynopsisdiv>
     3927
     3928        <refsect1>
     3929          <title>Arguments and Values</title>
     3930         
     3931          <variablelist>
     3932            <varlistentry>
     3933              <term>semaphore</term>
     3934              <listitem>
     3935                <para>an object of type CCL:SEMAPHORE.</para>
     3936              </listitem>
     3937            </varlistentry>
     3938            <varlistentry>
     3939              <term>result</term>
     3940              <listitem>
     3941                <para>an integer representing an error identifier
     3942                which was returned by the underlying OS call.</para>
     3943              </listitem>
     3944            </varlistentry>
     3945          </variablelist>
     3946        </refsect1>
     3947
     3948        <refsect1>
     3949          <title>Description</title>
     3950
     3951          <para>Waits until <varname>semaphore</varname>
     3952          has a positive count that can be
     3953          atomically decremented; this will succeed exactly once for each
     3954          corresponding call to SIGNAL-SEMAPHORE.</para>
     3955        </refsect1>
     3956
     3957        <refsect1>
     3958          <title>See Also</title>
     3959         
     3960          <simplelist type="inline">
     3961            <member><xref linkend="f_make-semaphore"/></member>
     3962            <member><xref linkend="f_signal-semaphore"/></member>
     3963            <member><xref linkend="f_timed-wait-on-semaphore"/></member>
     3964            <member><xref linkend="f_make-lock"/></member>
     3965            <member><xref linkend="f_make-read-write-lock"/></member>
     3966            <member><xref linkend="f_process-input-wait"/></member>
     3967            <member><xref linkend="f_process-output-wait"/></member>
     3968            <member><xref linkend="m_with-terminal-input"/></member>
     3969          </simplelist>
     3970        </refsect1>
     3971
     3972        <refsect1>
     3973          <title>Notes</title>
     3974
     3975          <para><varname>result</varname> should probably be interpreted
     3976          and acted on by <function>wait-on-semaphore</function>, because
     3977          it is not likely to be meaningful to a lisp program, and the
     3978          most common cause of failure is a type error.</para>
     3979        </refsect1>
     3980      </refentry>
     3981
     3982      <refentry id="f_timed-wait-on-semaphore">
     3983        <indexterm zone="f_timed-wait-on-semaphore">
     3984          <primary>timed-wait-on-semaphore</primary>
     3985        </indexterm>
     3986
     3987        <refnamediv>
     3988          <refname>TIMED-WAIT-ON-SEMAPHORE</refname>
     3989          <refpurpose>Waits until the given semaphore has a postive
     3990          count which can be atomically decremented, or until a timeout
     3991          expires.</refpurpose>
     3992          <refclass>Function</refclass>
     3993        </refnamediv>
     3994
     3995        <refsynopsisdiv>
     3996          <synopsis><function>timed-wait-on-semaphore</function>
     3997          semaphore timeout => result</synopsis>
     3998        </refsynopsisdiv>
     3999
     4000        <refsect1>
     4001          <title>Arguments and Values</title>
     4002         
     4003          <variablelist>
     4004            <varlistentry>
     4005              <term>semaphore</term>
     4006              <listitem>
     4007                <para>An object of type CCL:SEMAPHORE.</para>
     4008              </listitem>
     4009            </varlistentry>
     4010            <varlistentry>
     4011              <term>timeout</term>
     4012              <listitem>
     4013                <para>a time interval in seconds.  May be any
     4014                non-negative real number the <function>floor</function> of
     4015                which fits in 32 bits.  The default is 1.</para>
     4016              </listitem>
     4017            </varlistentry>
     4018            <varlistentry>
     4019              <term>result</term>
     4020              <listitem>
     4021                <para>T if <function>timed-wait-on-semaphore</function>
     4022                returned because it was able to decrement the count of
     4023                <varname>semaphore</varname>; NIL if it returned because
     4024                the duration <varname>timeout</varname> has been
     4025                exceeded.</para>
     4026              </listitem>
     4027            </varlistentry>
     4028          </variablelist>
     4029        </refsect1>
     4030
     4031        <refsect1>
     4032          <title>Description</title>
     4033
     4034          <para>Waits until <varname>semaphore</varname>
     4035          has a positive count that can be
     4036          atomically decremented, or until the duration
     4037          <varname>timeout</varname> has
     4038          elapsed.</para>
     4039        </refsect1>
     4040
     4041        <refsect1>
     4042          <title>See Also</title>
     4043         
     4044          <simplelist type="inline">
     4045            <member><xref linkend="f_make-semaphore"/></member>
     4046            <member><xref linkend="f_wait-on-semaphore"/></member>
     4047            <member><xref linkend="f_make-lock"/></member>
     4048            <member><xref linkend="f_make-read-write-lock"/></member>
     4049            <member><xref linkend="f_process-input-wait"/></member>
     4050            <member><xref linkend="f_process-output-wait"/></member>
     4051            <member><xref linkend="m_with-terminal-input"/></member>
     4052          </simplelist>
     4053        </refsect1>
     4054      </refentry>
     4055
     4056      <refentry id="f_process-input-wait">
     4057        <indexterm zone="f_process-input-wait">
     4058          <primary>process-input-wait</primary>
     4059        </indexterm>
     4060
     4061        <refnamediv>
     4062          <refname>PROCESS-INPUT-WAIT</refname>
     4063          <refpurpose>Waits until input is available on a given
     4064          file-descriptor.</refpurpose>
     4065          <refclass>Function</refclass>
     4066        </refnamediv>
     4067
     4068        <refsynopsisdiv>
     4069          <synopsis><function>process-input-wait</function>
     4070          fd &optional; timeout</synopsis>
     4071        </refsynopsisdiv>
     4072
     4073        <refsect1>
     4074          <title>Arguments and Values</title>
     4075         
     4076          <variablelist>
     4077            <varlistentry>
     4078              <term>fd</term>
     4079              <listitem>
     4080                <para>a file descriptor, which is a non-negative integer
     4081                used by the OS to refer to an open file, socket, or similar
     4082                I/O connection.  See <xref linkend="f_stream-device"/>.</para>
     4083              </listitem>
     4084            </varlistentry>
     4085            <varlistentry>
     4086              <term>timeout</term>
     4087              <listitem>
     4088                <para>either NIL, or a time interval in seconds.  May be any
     4089                non-negative real number the <function>floor</function> of
     4090                which fits in 32 bits.  The default is NIL.</para>
     4091              </listitem>
     4092            </varlistentry>
     4093          </variablelist>
     4094        </refsect1>
     4095
     4096        <refsect1>
     4097          <title>Description</title>
     4098
     4099          <para>Wait until input is available on <varname>fd</varname>.
     4100          This uses the <function>select()</function> system call, and is
     4101          generally a fairly
     4102          efficient way of blocking while waiting for input. More
     4103          accurately, <function>process-input-wait</function>
     4104          waits until it&#39;s possible to read
     4105          from fd without blocking, or until <varname>timeout</varname>, if
     4106          it is not NIL, has been exceeded.</para>
     4107
     4108          <para>
     4109          Note that it&#39;s possible to read without blocking if
     4110          the file is at its end - although, of course, the read will
     4111          return zero bytes.</para>
     4112        </refsect1>
     4113       
     4114        <refsect1>
     4115          <title>See Also</title>
     4116         
     4117          <simplelist type="inline">
     4118            <member><xref linkend="f_make-lock"/></member>
     4119            <member><xref linkend="f_make-read-write-lock"/></member>
     4120            <member><xref linkend="f_make-semaphore"/></member>
     4121            <member><xref linkend="f_process-output-wait"/></member>
     4122            <member><xref linkend="m_with-terminal-input"/></member>
     4123          </simplelist>
     4124        </refsect1>
     4125
     4126        <refsect1>
     4127          <title>Notes</title>
     4128
     4129          <para>
     4130          <function>process-input-wait</function> has a timeout parameter,
     4131          and
     4132          <xref linkend="f_process-output-wait"/> does not.  This
     4133          inconsistency should probably be corrected.
     4134          </para>
     4135        </refsect1>
     4136      </refentry>
     4137
     4138      <refentry id="f_process-output-wait">
     4139        <indexterm zone="f_process-output-wait">
     4140          <primary>process-output-wait</primary>
     4141        </indexterm>
     4142
     4143        <refnamediv>
     4144          <refname>PROCESS-OUTPUT-WAIT</refname>
     4145          <refpurpose>Waits until output is possible on a given file
     4146          descriptor.</refpurpose>
     4147          <refclass>Function</refclass>
     4148        </refnamediv>
     4149
     4150        <refsynopsisdiv>
     4151          <synopsis><function>process-output-wait</function> fd</synopsis>
     4152        </refsynopsisdiv>
     4153
     4154        <refsect1>
     4155          <title>Arguments and Values</title>
     4156         
     4157          <variablelist>
     4158            <varlistentry>
     4159              <term>fd</term>
     4160              <listitem>
     4161                <para>a file descriptor, which is a non-negative integer
     4162                used by the OS to refer to an open file, socket, or similar
     4163                I/O connection.  See <xref linkend="f_stream-device"/>.</para>
     4164              </listitem>
     4165            </varlistentry>
     4166          </variablelist>
     4167        </refsect1>
     4168
     4169        <refsect1>
     4170          <title>Description</title>
     4171
     4172          <para>Wait until output is possible on <varname>fd</varname>.
     4173          This uses the <function>select()</function> system call, and is
     4174          generally a fairly
     4175          efficient way of blocking while waiting to output.</para>
     4176
     4177          <para>If <function>process-output-wait</function> is called on
     4178          a network socket which has not yet established a connection, it
     4179          will wait until the connection is established.  This is an
     4180          important use, often overlooked.</para>
     4181        </refsect1>
     4182
     4183        <refsect1>
     4184          <title>See Also</title>
     4185         
     4186          <simplelist type="inline">
     4187            <member><xref linkend="f_make-lock"/></member>
     4188            <member><xref linkend="f_make-read-write-lock"/></member>
     4189            <member><xref linkend="f_make-semaphore"/></member>
     4190            <member><xref linkend="f_process-input-wait"/></member>
     4191            <member><xref linkend="m_with-terminal-input"/></member>
     4192          </simplelist>
     4193        </refsect1>
     4194
     4195        <refsect1>
     4196          <title>Notes</title>
     4197
     4198          <para>
     4199          <xref linkend="f_process-input-wait"/> has a timeout parameter,
     4200          and
     4201          <function>process-output-wait</function> does not.  This
     4202          inconsistency should probably be corrected.
     4203          </para>
     4204        </refsect1>
     4205      </refentry>
     4206
     4207      <refentry id="m_with-terminal-input">
     4208        <indexterm zone="m_with-terminal-input">
     4209          <primary>with-terminal-input</primary>
     4210        </indexterm>
     4211
     4212        <refnamediv>
     4213          <refname>WITH-TERMINAL-INPUT</refname>
     4214          <refpurpose>Executes its body in an environment with exclusive
     4215          read access to the terminal.</refpurpose>
     4216          <refclass>Macro</refclass>
     4217        </refnamediv>
     4218
     4219        <refsynopsisdiv>
     4220          <synopsis><function>with-terminal-input</function>
     4221          &body; body => result</synopsis>
     4222        </refsynopsisdiv>
     4223
     4224        <refsect1>
     4225          <title>Arguments and Values</title>
     4226         
     4227          <variablelist>
     4228            <varlistentry>
     4229              <term>body</term>
     4230              <listitem>
     4231                <para>an implicit progn.</para>
     4232              </listitem>
     4233            </varlistentry>
     4234            <varlistentry>
     4235              <term>result</term>
     4236              <listitem>
     4237                <para>the primary value returned by
     4238                <varname>body</varname>.</para>
     4239              </listitem>
     4240            </varlistentry>
     4241          </variablelist>
     4242        </refsect1>
     4243
     4244        <refsect1>
     4245          <title>Description</title>
     4246
     4247          <para>Requests exclusive read access to the standard terminal
     4248          stream, <varname>*terminal-io*</varname>.  Executes
     4249          <varname>body</varname> in an environment with that access.
     4250          </para>
     4251        </refsect1>
     4252
     4253        <refsect1>
     4254          <title>See Also</title>
     4255         
     4256          <simplelist type="inline">
     4257            <member><xref
     4258                      linkend="v_request-terminal-input-via-break"/></member>
     4259            <member><xref linkend="cmd_y"/></member>
     4260            <member><xref linkend="f_make-lock"/></member>
     4261            <member><xref linkend="f_make-read-write-lock"/></member>
     4262            <member><xref linkend="f_make-semaphore"/></member>
     4263            <member><xref linkend="f_process-input-wait"/></member>
     4264            <member><xref linkend="f_process-output-wait"/></member>
     4265          </simplelist>
     4266        </refsect1>
     4267      </refentry>
     4268
     4269      <refentry id="v_request-terminal-input-via-break">
     4270        <indexterm zone="v_request-terminal-input-via-break">
     4271          <primary>request-terminal-input-via-break</primary>
     4272        </indexterm>
     4273
     4274        <refnamediv>
     4275          <refname>*REQUEST-TERMINAL-INPUT-VIA-BREAK*</refname>
     4276          <refpurpose>Controls how attempts to obtain ownership of
     4277          terminal input are made.</refpurpose>
     4278          <refclass>Variable</refclass>
     4279        </refnamediv>
     4280
     4281        <refsect1>
     4282          <title>Value Type</title>
     4283
     4284          <para>A boolean.</para>
     4285        </refsect1>
     4286
     4287        <refsect1>
     4288          <title>Initial Value</title>
     4289         
     4290          <para>NIL.</para>
     4291        </refsect1>
     4292
     4293        <refsect1>
     4294          <title>Description</title>
     4295
     4296          <para>Controls how attempts to obtain ownership of terminal input
     4297          are made. When NIL, a message is printed on *TERMINAL-IO*;
     4298          it's expected that the user will later yield
     4299          control of the terminal via the :Y toplevel command. When T, a
     4300          BREAK condition is signaled in the owning process; continuing from
     4301          the break loop will yield the terminal to the requesting process
     4302          (unless the :Y command was already used to do so in the break
     4303          loop.)</para>
     4304        </refsect1>
     4305
     4306        <refsect1>
     4307          <title>See Also</title>
     4308         
     4309          <simplelist type="inline">
     4310            <member><xref linkend="m_with-terminal-input"/></member>
     4311            <member><xref linkend="cmd_y"/></member>
     4312            <member><xref linkend="f_make-lock"/></member>
     4313            <member><xref linkend="f_make-read-write-lock"/></member>
     4314            <member><xref linkend="f_make-semaphore"/></member>
     4315            <member><xref linkend="f_process-input-wait"/></member>
     4316            <member><xref linkend="f_process-output-wait"/></member>
     4317          </simplelist>
     4318        </refsect1>
     4319      </refentry>
     4320
     4321      <refentry id="cmd_y">
     4322        <indexterm zone="cmd_y">
     4323          <primary>:y</primary>
     4324        </indexterm>
     4325
     4326        <refnamediv>
     4327          <refname>:Y</refname>
     4328          <refpurpose>Yields control of terminal input to a specified
     4329          lisp process (thread).</refpurpose>
     4330          <refclass>Toplevel Command</refclass>
     4331        </refnamediv>
     4332
     4333        <refsynopsisdiv>
     4334          <synopsis>(<function>:y</function> p)</synopsis>
     4335        </refsynopsisdiv>
     4336
     4337        <refsect1>
     4338          <title>Arguments and Values</title>
     4339
     4340          <variablelist>
     4341            <varlistentry>
     4342              <term>p</term>
     4343              <listitem>
     4344                <para>a lisp process (thread), designated either by
     4345                an integer which matches its
     4346                <function>process-serial-number</function>,
     4347                or by a string which is <function>equal</function> to
     4348                its <function>process-name</function>.</para>
     4349              </listitem>
     4350            </varlistentry>
     4351          </variablelist>
     4352        </refsect1>
     4353
     4354        <refsect1>
     4355          <title>Description</title>
     4356
     4357          <para>:Y is a toplevel command, not a function.  As such, it
     4358          can only be used interactively, and only from the initial
     4359          process.</para>
     4360
     4361          <para>The command yields control of terminal input to the
     4362          process <varname>p</varname>, which must have used
     4363          <xref linkend="m_with-terminal-input"/> to request access to the
     4364          terminal input stream.</para>
     4365        </refsect1>
     4366
     4367        <refsect1>
     4368          <title>See Also</title>
     4369         
     4370          <simplelist type="inline">
     4371            <member><xref linkend="m_with-terminal-input"/></member>
     4372            <member><xref
     4373                      linkend="v_request-terminal-input-via-break"/></member>
     4374            <member><xref linkend="f_make-lock"/></member>
     4375            <member><xref linkend="f_make-read-write-lock"/></member>
     4376            <member><xref linkend="f_make-semaphore"/></member>
     4377            <member><xref linkend="f_process-input-wait"/></member>
     4378            <member><xref linkend="f_process-output-wait"/></member>
     4379          </simplelist>
     4380        </refsect1>
     4381      </refentry>
     4382
    31284383    </sect1>
    31294384  </chapter>
     
    31334388
    31344389    <sect1 id="Sockets-Overview">
    3135       <para>OverviewOpenMCL supports the socket abstraction for
     4390      <title>Overview</title>
     4391
     4392      <para>OpenMCL supports the socket abstraction for
    31364393      interprocess communication. A socket represents a connection to
    31374394      another process, typically (but not necessarily) a TCP/IP
     
    31444401      sockets, and Unix-domain sockets.  This should be enough for all
    31454402      but the most esoteric network situations.  All sockets are
    3146       created by .  The type of socket depends on the arguments to it,
    3147       as follows:</para>
    3148       <term><indexterm>tcp-stream
    3149           <variablelist>A buffered bi-directional stream over a TCP/IP connection.tcp-stream is a subclass of stream, and you can read and write to itusing all the usual stream functions. Created by (make-socket:addess-family :internet :type :stream :connect :active ...) or by(accept-connection ...).</variablelist>
    3150         </indexterm><indexterm>file-socket-stream
    3151           <variablelist>A buffered bi-directional stream over a "UNIX domain"connection. file-socket-stream is a subclass of stream, and you canread and write to it using all the usual stream functions. Createdby (make-socket :address-family :file :type :stream :connect :active...) or by (accept-connection ...),</variablelist>
    3152         </indexterm><indexterm>listener-socket
    3153           <variablelist>A passive socket used to listen for incoming TCP/IPconnections on a particular port. A listener-socket is not a stream.It doesn't support I/O. It can only be used to create newtcp-streams by accept-connection. Created by (make-socket :type:stream :connect :passive ...)</variablelist>
    3154         </indexterm><indexterm>file-listener-socket
    3155           <variablelist>A passive socket used to listen for incoming UNIX domainconnections named by a file in the local filesystem. Alistener-socket is not a stream. It doesn't support I/O. It canonly be used to create new file-socket-streams by accept-connection.Created by (make-socket :address-family :file :type :stream :connect:passive ...)</variablelist>
    3156         </indexterm><indexterm>udp-socket
    3157           <variablelist>A socket representing a packet-based UDP/IP connection. Audp-socket supports I/O but it is not a stream. Instead, you mustuse the special functions send-to and receive-from to read and writeto it. Created by (make-socket :type :datagram ...)</variablelist>
    3158         </indexterm>
    3159       </term>
     4403      created by <xref linkend="f_make-socket"/>.  The type of socket
     4404      depends on the arguments to it, as follows:</para>
     4405
     4406      <variablelist>
     4407        <varlistentry>
     4408          <term>tcp-stream</term>
     4409
     4410          <listitem>
     4411            <para>A buffered bi-directional stream over a TCP/IP connection.
     4412            tcp-stream is a subclass of stream, and you can read and write to it
     4413            using all the usual stream functions. Created by (make-socket
     4414            :addess-family :internet :type :stream :connect :active ...) or by
     4415            (accept-connection ...).</para>
     4416          </listitem>
     4417        </varlistentry>
     4418
     4419        <varlistentry>
     4420          <term>file-socket-stream</term>
     4421
     4422          <listitem>
     4423            <para>A buffered bi-directional stream over a &#34;UNIX domain&#34;
     4424            connection. file-socket-stream is a subclass of stream, and you can
     4425            read and write to it using all the usual stream functions. Created
     4426            by (make-socket :address-family :file :type :stream :connect :active
     4427            ...) or by (accept-connection ...),</para>
     4428          </listitem>
     4429        </varlistentry>
     4430
     4431        <varlistentry>
     4432          <term>listener-socket</term>
     4433
     4434          <listitem>
     4435            <para>A passive socket used to listen for incoming TCP/IP
     4436            connections on a particular port. A listener-socket is not a stream.
     4437            It doesn&#39;t support I/O. It can only be used to create new
     4438            tcp-streams by accept-connection. Created by (make-socket :type
     4439            :stream :connect :passive ...)</para>
     4440          </listitem>
     4441        </varlistentry>
     4442
     4443        <varlistentry>
     4444          <term>file-listener-socket</term>
     4445
     4446          <listitem>
     4447            <para>A passive socket used to listen for incoming UNIX domain
     4448            connections named by a file in the local filesystem. A
     4449            listener-socket is not a stream. It doesn&#39;t support I/O. It can
     4450            only be used to create new file-socket-streams by accept-connection.
     4451            Created by (make-socket :address-family :file :type :stream :connect
     4452            :passive ...)</para>
     4453          </listitem>
     4454        </varlistentry>
     4455
     4456        <varlistentry>
     4457          <term>udp-socket</term>
     4458
     4459          <listitem>
     4460            <para>A socket representing a packet-based UDP/IP connection. A
     4461            udp-socket supports I/O but it is not a stream. Instead, you must
     4462            use the special functions send-to and receive-from to read and write
     4463            to it. Created by (make-socket :type :datagram ...)</para>
     4464          </listitem>
     4465        </varlistentry>
     4466      </variablelist>
    31604467    </sect1>
    31614468
    31624469    <sect1 id="Sockets-Dictionary">
    31634470      <title>Sockets Dictionary</title>
    3164 
    3165       <sect2 id="MAKE-SOCKET">
    3166         <para>MAKE-SOCKET</para>
    3167         <informalfigure>make-socket</informalfigure>
    3168         <bridgehead renderas="sect3">Name</bridgehead>
    3169         <para>MAKE-SOCKET &mdash;</para>
    3170         <para>Function</para>
    3171         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3172         <programlisting>
    3173 make-socket
    3174           &amp;key address-family type connect eol format
     4471      <refentry id="f_make-socket">
     4472        <indexterm zone="f_make-socket">
     4473          <primary>make-socket</primary>
     4474        </indexterm>
     4475        <refnamediv>
     4476          <refname>MAKE-SOCKET</refname>
     4477          <refpurpose></refpurpose>
     4478          <refclass>Function</refclass>
     4479        </refnamediv>
     4480
     4481        <refsynopsisdiv>
     4482          <synopsis><function>make-socket</function>
     4483          &key; address-family type connect eol format
    31754484          remote-host remote-port local-host local-port local-filename
    31764485          remote-filename keepalive reuse-address nodelay broadcast linger
    3177           backlog
    3178 </programlisting>
    3179         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3180         <term><indexterm>address-family
    3181             <variablelist>The address/protocol family of this socket. Currentlyonly :internet (the default), meaning IP, and :file,referring to UNIX domain addresses, are supported.</variablelist>
    3182           </indexterm><indexterm>type
    3183             <variablelist>One of :stream (the default) to request aconnection-oriented socket, or :datagram to request aconnectionless socket. The default is :stream.</variablelist>
    3184           </indexterm><indexterm>connect
    3185             <variablelist>This argument is only relevant to sockets of type:stream. One of :active (the default) to request a :passiveto request a file or TCP listener socket.</variablelist>
    3186           </indexterm><indexterm>eol
    3187             <variablelist>This argument is currently ignored (it is accepted forcompatibility with Franz Allegro).</variablelist>
    3188           </indexterm><indexterm>format
    3189             <variablelist>One of :text (the default), :binary, or :bivalent.This argument is ignored for :stream sockets for now, as:stream sockets are currently always bivalent (i.e. theysupport both character and byte I/O). For :datagram sockets,the format determines the type of buffer created byreceive-from.</variablelist>
    3190           </indexterm><indexterm>remote-host
    3191             <variablelist>Required for TCP streams, it specifies the host toconnect to (in any format acceptable to lookup-hostname).Ignored for listener sockets. For UDP sockets, it can beused to specify a default host for subsequent calls tosend-to or receive-from.</variablelist>
    3192           </indexterm><indexterm>remote-port
    3193             <variablelist>Required for TCP streams, it specifies the port toconnect to (in any format acceptable to lookup-port).Ignored for listener sockets. For UDP sockets, it can beused to specify a default port for subsequent calls to forsubsequent calls to send-to or receive-from.</variablelist>
    3194           </indexterm><indexterm>remote-filename
    3195             <variablelist>Required for file-socket streams, it specifies thename of a file in the local filesystem (e.g., NOT mountedvia NFS, AFP, SMB, ...) which names and controls access to aUNIX-domain socket.</variablelist>
    3196           </indexterm><indexterm>local-host
    3197             <variablelist>Allows you to specify a local host address for alistener or UDP socket, for the rare case where you want torestrict connections to those coming to a specific localaddress for security reasons.</variablelist>
    3198           </indexterm><indexterm>local-port
    3199             <variablelist>Specify a local port for a socket. Most useful forlistener sockets, where it is the port on which the socketwill listen for connections.</variablelist>
    3200           </indexterm><indexterm>local-filename
    3201             <variablelist>Required for file-listener-sockets. Specifies the nameof a file in the local filesystem which is used to name aUNIX-domain socket. The actual filesystem file should notpreviously exist when the file-listener-socket is created;its parent directory should exist and be writable by thecaller. The file used to name the socket will be deletedwhen the file-listener-socket is closed.</variablelist>
    3202           </indexterm><indexterm>keepalive
    3203             <variablelist>If true, enables the periodic transmission of"keepalive" messages.</variablelist>
    3204           </indexterm><indexterm>reuse-address
    3205             <variablelist>If true, allows the reuse of local ports in listenersockets, overriding some TCP/IP protocol specifications. Youwill need this if you are debugging a server..</variablelist>
    3206           </indexterm><indexterm>nodelay
    3207             <variablelist>If true, disables Nagle's algorithm, which triesto minimize TCP packet fragmentation by introducingtransmission delays in the absence of replies. Try settingthis if you are using a protocol which involves sending asteady stream of data with no replies and are seeingsignificant degradations in throughput.</variablelist>
    3208           </indexterm><indexterm>broadcast
    3209             <variablelist>If true, requests permission to broadcast datagrams ona UDP socket.</variablelist>
    3210           </indexterm><indexterm>linger
    3211             <variablelist>If specified and non-nil, should be the number ofseconds the OS is allowed to wait for data to be pushedthrough when a close is done. Only relevant for TCP sockets.</variablelist>
    3212           </indexterm><indexterm>backlog
    3213             <variablelist>For a listener socket, specifies the number ofconnections which can be pending but not accepted. Thedefault is 5, which is also the maximum on some operatingsystems.</variablelist>
    3214           </indexterm>
    3215         </term>
    3216         <bridgehead renderas="sect3">Description</bridgehead>
    3217         <para>Creates and returns a new socket</para>
    3218       </sect2>
    3219 
    3220       <sect2 id="ACCEPT-CONNECTION">
    3221         <para>ACCEPT-CONNECTION</para>
    3222         <informalfigure>accept-connection</informalfigure>
    3223         <bridgehead renderas="sect3">Name</bridgehead>
    3224         <para>ACCEPT-CONNECTION &mdash;</para>
    3225         <para>Function</para>
    3226         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3227         <programlisting>
    3228 accept-connection
    3229           (socket listener-socket) &amp;key wait
    3230 </programlisting>
    3231         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3232         <term><indexterm>socket
    3233             <variablelist>The listener-socket to listen on.</variablelist>
    3234           </indexterm><indexterm>wait
    3235             <variablelist>If true (the default), and there are no connectionswaiting to be accepted, waits until one arrives. If false,returns NIL immediately.</variablelist>
    3236           </indexterm>
    3237         </term>
    3238         <bridgehead renderas="sect3">Description</bridgehead>
    3239         <para>Extracts the first connection on the queue of pending
    3240 connections, accepts it (i.e. completes the connection startup
    3241 protocol) and returns a new tcp-stream or file-socket-stream
    3242 representing the newly established connection. The tcp stream
    3243 inherits any properties of the listener socket that are relevant
    3244 (e.g. :keepalive, :nodelay, etc.) The original listener socket
    3245 continues to be open listening for more connections, so you can
    3246 call accept-connection on it again.</para>
    3247       </sect2>
    3248 
    3249       <sect2 id="DOTTED-TO-IPADDR">
    3250         <para>DOTTED-TO-IPADDR</para>
    3251         <informalfigure>dotted-to-ipaddr</informalfigure>
    3252         <bridgehead renderas="sect3">Name</bridgehead>
    3253         <para>DOTTED-TO-IPADDR &mdash;</para>
    3254         <para>Function</para>
    3255         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3256         <programlisting>
    3257 dotted-to-ipaddr
    3258           dotted &amp;key errorp
    3259 </programlisting>
    3260         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3261         <term><indexterm>dotted
    3262             <variablelist>A string representing an IP address in the"nn.nn.nn.nn" format</variablelist>
    3263           </indexterm><indexterm>errorp
    3264             <variablelist>If true (the default) an error is signaled if dottedis invalid. If false, NIL is returned.</variablelist>
    3265           </indexterm>
    3266         </term>
    3267         <bridgehead renderas="sect3">Description</bridgehead>
    3268         <para>Converts a dotted-string representation of a host address to
    3269 a 32-bit unsigned IP address.</para>
    3270       </sect2>
    3271 
    3272       <sect2 id="IPADDR-TO-DOTTED">
    3273         <para>IPADDR-TO-DOTTED</para>
    3274         <informalfigure>ipaddr-to-dotted</informalfigure>
    3275         <bridgehead renderas="sect3">Name</bridgehead>
    3276         <para>IPADDR-TO-DOTTED &mdash;</para>
    3277         <para>Function</para>
    3278         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3279         <programlisting>
    3280 ipaddr-to-dotted
    3281           ipaddr &amp;key values
    3282 </programlisting>
    3283         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3284         <term><indexterm>ipaddr
    3285             <variablelist>A 32-bit integer representing an internet host address</variablelist>
    3286           </indexterm><indexterm>values
    3287             <variablelist>If false (the default), returns a string in the form"nn.nn.nn.nn". If true, returns four valuesrepresenting the four octets of the address as unsigned8-bit integers.</variablelist>
    3288           </indexterm>
    3289         </term>
    3290         <bridgehead renderas="sect3">Description</bridgehead>
    3291         <para>Converts a 32-bit unsigned IP address into octets.</para>
    3292       </sect2>
    3293 
    3294       <sect2 id="IPADDR-TO-HOSTNAME">
    3295         <para>IPADDR-TO-HOSTNAME</para>
    3296         <informalfigure>ipaddr-to-hostname</informalfigure>
    3297         <bridgehead renderas="sect3">Name</bridgehead>
    3298         <para>IPADDR-TO-HOSTNAME &mdash;</para>
    3299         <para>Function</para>
    3300         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3301         <programlisting>
    3302 ipaddr-to-hostname
    3303           ipaddr &amp;key ignore-cache
    3304 </programlisting>
    3305         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3306         <term><indexterm>ipaddr
    3307             <variablelist>a 32-bit integer representing an internet host address</variablelist>
    3308           </indexterm><indexterm>ignore-cache
    3309             <variablelist>This argument is ignored (it is accepted forcompatibility with Franz Allegro)</variablelist>
    3310           </indexterm>
    3311         </term>
    3312         <bridgehead renderas="sect3">Description</bridgehead>
    3313         <para>Converts a 32-bit unsigned IP address into a host name
    3314 string</para>
    3315       </sect2>
    3316 
    3317       <sect2 id="LOOKUP-HOSTNAME">
    3318         <para>LOOKUP-HOSTNAME</para>
    3319         <informalfigure>lookup-hostname</informalfigure>
    3320         <bridgehead renderas="sect3">Name</bridgehead>
    3321         <para>LOOKUP-HOSTNAME &mdash;</para>
    3322         <para>Function</para>
    3323         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3324         <programlisting>
    3325 lookup-hostname
    3326           host
    3327 </programlisting>
    3328         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3329         <term><indexterm>host
    3330             <variablelist>Specifies the host. It can be either a host namestring such as "clozure.com", or a dotted addressstring such as "192.168.0.1", or a 32-bit unsignedIP address such as 3232235521.</variablelist>
    3331           </indexterm>
    3332         </term>
    3333         <bridgehead renderas="sect3">Description</bridgehead>
    3334         <para>Converts a host spec in any of the acceptable formats into a
    3335 32-bit unsigned IP address</para>
    3336       </sect2>
    3337 
    3338       <sect2 id="LOOKUP-PORT">
    3339         <para>LOOKUP-PORT</para>
    3340         <informalfigure>lookup-port</informalfigure>
    3341         <bridgehead renderas="sect3">Name</bridgehead>
    3342         <para>LOOKUP-PORT &mdash;</para>
    3343         <para>Function</para>
    3344         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3345         <programlisting>
    3346 lookup-port
    3347           port protocol
    3348 </programlisting>
    3349         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3350         <term><indexterm>port
    3351             <variablelist>Specifies the port. It can be either a string, such as"http" or a symbol, such as :http, or an unsignedport number. Note that a string is case-sensitive. A symbolis lowercased before lookup.</variablelist>
    3352           </indexterm><indexterm>protocol
    3353             <variablelist>Must be one of "tcp" or "udp".</variablelist>
    3354           </indexterm>
    3355         </term>
    3356         <bridgehead renderas="sect3">Description</bridgehead>
    3357         <para>Finds the port number for the specified port and protocol</para>
    3358       </sect2>
    3359 
    3360       <sect2 id="RECEIVE-FROM">
    3361         <para>RECEIVE-FROM</para>
    3362         <informalfigure>receive-from</informalfigure>
    3363         <bridgehead renderas="sect3">Name</bridgehead>
    3364         <para>RECEIVE-FROM &mdash;</para>
    3365         <para>Function</para>
    3366         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3367         <programlisting>
    3368 receive-from
    3369           (socket udp-socket) size &amp;key buffer
    3370           extract offset
    3371 </programlisting>
    3372         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3373         <term><indexterm>socket
    3374             <variablelist>The socket to read from</variablelist>
    3375           </indexterm><indexterm>size
    3376             <variablelist>Maximum number of bytes to read. If the packet islarger than this, any extra bytes are discarded.</variablelist>
    3377           </indexterm><indexterm>buffer
    3378             <variablelist>If specified, must be either a string or a byte vectorwhich will be used to read in the data. If not specified, anew buffer will be created (of type determined bysocket-format).</variablelist>
    3379           </indexterm><indexterm>extract
    3380             <variablelist>If true, the subsequence of the buffer correspondingonly to the data read in is extracted and returned as thefirst value. If false (the default) the original buffer isreturned even if it is only partially filled.</variablelist>
    3381           </indexterm><indexterm>offset
    3382             <variablelist>Specifies the start offset into the buffer at whichdata is to be stored. The default is 0.</variablelist>
    3383           </indexterm>
    3384         </term>
    3385         <bridgehead renderas="sect3">Description</bridgehead>
    3386         <para>Reads a UDP packet from a socket. If no packets are
    3387 available, waits for a packet to arrive. Returns four values:</para>
    3388         <varlistentry numeration="arabic">
    3389           <variablelist>The buffer with the data</variablelist>
    3390           <variablelist>The number of bytes read</variablelist>
    3391           <variablelist>The 32-bit unsigned IP address of the sender of the data</variablelist>
    3392           <variablelist>The port number of the sender of the data</variablelist>
    3393         </varlistentry>
    3394       </sect2>
    3395 
    3396       <sect2 id="SEND-TO">
    3397         <para>SEND-TO</para>
    3398         <informalfigure>send-to</informalfigure>
    3399         <bridgehead renderas="sect3">Name</bridgehead>
    3400         <para>SEND-TO &mdash;</para>
    3401         <para>Function</para>
    3402         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3403         <programlisting>
    3404 send-to
    3405           (socket udp-socket) buffer size &amp;key remote-host
    3406           remote-port offset
    3407 </programlisting>
    3408         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3409         <term><indexterm>socket
    3410             <variablelist>The socket to write to</variablelist>
    3411           </indexterm><indexterm>buffer
    3412             <variablelist>A vector containing the data to send. It must beeither a string or a byte vector (either one is acceptableregardless of the stream format).</variablelist>
    3413           </indexterm><indexterm>size
    3414             <variablelist>Number of bytes to send</variablelist>
    3415           </indexterm><indexterm>remote-host
    3416             <variablelist>The host to send the packet to, in any formatacceptable to lookup-hostname. The default is the remotehost specified in the call to make-socket.</variablelist>
    3417           </indexterm><indexterm>remote-port
    3418             <variablelist>The port to send the packet to, in any formatacceptable to lookup-port. The default is the remote portspecified in the call to make-socket.</variablelist>
    3419           </indexterm><indexterm>offset
    3420             <variablelist>The offset in the buffer where the packet data starts</variablelist>
    3421           </indexterm>
    3422         </term>
    3423         <bridgehead renderas="sect3">Description</bridgehead>
    3424         <para>Send a UDP packet over a socket.</para>
    3425       </sect2>
    3426 
    3427       <sect2 id="SHUTDOWN">
    3428         <para>SHUTDOWN</para>
    3429         <informalfigure>shutdown</informalfigure>
    3430         <bridgehead renderas="sect3">Name</bridgehead>
    3431         <para>SHUTDOWN &mdash;</para>
    3432         <para>Function</para>
    3433         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3434         <programlisting>
    3435 shutdown
    3436           socket &amp;key direction
    3437 </programlisting>
    3438         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3439         <term><indexterm>socket
    3440             <variablelist>The socket to shut down (typically a tcp-stream)</variablelist>
    3441           </indexterm><indexterm>direction
    3442             <variablelist>One of :input to disallow further input, or :output todisallow further output.</variablelist>
    3443           </indexterm>
    3444         </term>
    3445         <bridgehead renderas="sect3">Description</bridgehead>
    3446         <para>Shuts down part of a bidirectional connection. This is
    3447 useful if e.g. you need to read responses after sending an
    3448 end-of-file signal.</para>
    3449       </sect2>
    3450 
    3451       <sect2 id="SOCKET-OS-FD">
    3452         <para>SOCKET-OS-FD</para>
    3453         <informalfigure>socket-os-fd</informalfigure>
    3454         <bridgehead renderas="sect3">Name</bridgehead>
    3455         <para>SOCKET-OS-FD &mdash;</para>
    3456         <para>Function</para>
    3457         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3458         <programlisting>
    3459 socket-os-fd
    3460           socket
    3461 </programlisting>
    3462         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3463         <term><indexterm>socket
    3464             <variablelist>The socket</variablelist>
    3465           </indexterm>
    3466         </term>
    3467         <bridgehead renderas="sect3">Description</bridgehead>
    3468         <para>Returns the native OS's representation of the socket, or
    3469 NIL if the socket is closed. On Unix, this is the Unix 'file
    3470 descriptor', a small non-negative integer. Note that it is
    3471 rather dangerous to mess around with tcp-stream fd's, as there
    3472 is all sorts of buffering and asynchronous I/O going on above the
    3473 OS level. listener-socket and udp-socket fd's are safer to
    3474 mess with directly as there is less magic going on.</para>
    3475       </sect2>
    3476 
    3477       <sect2 id="REMOTE-HOST">
    3478         <para>REMOTE-HOST</para>
    3479         <informalfigure>remote-host</informalfigure>
    3480         <bridgehead renderas="sect3">Name</bridgehead>
    3481         <para>REMOTE-HOST &mdash;</para>
    3482         <para>Function</para>
    3483         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3484         <programlisting>
    3485 remote-host
    3486           socket
    3487 </programlisting>
    3488         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3489         <term><indexterm>socket
    3490             <variablelist>The socket</variablelist>
    3491           </indexterm>
    3492         </term>
    3493         <bridgehead renderas="sect3">Description</bridgehead>
    3494         <para>Returns the 32-bit unsigned IP address of the remote host,
    3495 or NIL if the socket is not connected.</para>
    3496       </sect2>
    3497 
    3498       <sect2 id="REMOTE-PORT">
    3499         <para>REMOTE-PORT</para>
    3500         <informalfigure>remote-port</informalfigure>
    3501         <bridgehead renderas="sect3">Name</bridgehead>
    3502         <para>REMOTE-PORT &mdash;</para>
    3503         <para>Function</para>
    3504         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3505         <programlisting>
    3506 remote-port
    3507           socket
    3508 </programlisting>
    3509         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3510         <term><indexterm>socket
    3511             <variablelist>The socket</variablelist>
    3512           </indexterm>
    3513         </term>
    3514         <bridgehead renderas="sect3">Description</bridgehead>
    3515         <para>Returns the remote port number, or NIL if the socket is not
    3516 connected.</para>
    3517       </sect2>
    3518 
    3519       <sect2 id="LOCAL-HOST">
    3520         <para>LOCAL-HOST</para>
    3521         <informalfigure>local-host</informalfigure>
    3522         <bridgehead renderas="sect3">Name</bridgehead>
    3523         <para>LOCAL-HOST &mdash;</para>
    3524         <para>Function</para>
    3525         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3526         <programlisting>
    3527 local-host
    3528           socket
    3529 </programlisting>
    3530         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3531         <term><indexterm>socket
    3532             <variablelist>The socket</variablelist>
    3533           </indexterm>
    3534         </term>
    3535         <bridgehead renderas="sect3">Description</bridgehead>
    3536         <para>Returns 32-bit unsigned IP address of the local host.</para>
    3537       </sect2>
    3538 
    3539       <sect2 id="LOCAL-PORT">
    3540         <para>LOCAL-PORT</para>
    3541         <informalfigure>local-port</informalfigure>
    3542         <bridgehead renderas="sect3">Name</bridgehead>
    3543         <para>LOCAL-PORT &mdash;</para>
    3544         <para>Function</para>
    3545         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3546         <programlisting>
    3547 local-port
    3548           socket
    3549 </programlisting>
    3550         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3551         <term><indexterm>socket
    3552             <variablelist>The socket</variablelist>
    3553           </indexterm>
    3554         </term>
    3555         <bridgehead renderas="sect3">Description</bridgehead>
    3556         <para>Returns the local port number</para>
    3557       </sect2>
    3558 
    3559       <sect2 id="SOCKET-ADDRESS-FAMILY">
    3560         <para>SOCKET-ADDRESS-FAMILY</para>
    3561         <informalfigure>socket-address-family</informalfigure>
    3562         <bridgehead renderas="sect3">Name</bridgehead>
    3563         <para>SOCKET-ADDRESS-FAMILY &mdash;</para>
    3564         <para>Function</para>
    3565         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3566         <programlisting>
    3567 socket-address-family
    3568           socket
    3569 </programlisting>
    3570         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3571         <term><indexterm>socket
    3572             <variablelist>The socket</variablelist>
    3573           </indexterm>
    3574         </term>
    3575         <bridgehead renderas="sect3">Description</bridgehead>
    3576         <para>Returns :internet or :file, as appropriate.</para>
    3577       </sect2>
    3578 
    3579       <sect2 id="SOCKET-CONNECT">
    3580         <para>SOCKET-CONNECT</para>
    3581         <informalfigure>socket-connect</informalfigure>
    3582         <bridgehead renderas="sect3">Name</bridgehead>
    3583         <para>SOCKET-CONNECT &mdash;</para>
    3584         <para>Function</para>
    3585         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3586         <programlisting>
    3587 socket-connect
    3588           socket
    3589 </programlisting>
    3590         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3591         <term><indexterm>socket
    3592             <variablelist>The socket</variablelist>
    3593           </indexterm>
    3594         </term>
    3595         <bridgehead renderas="sect3">Description</bridgehead>
    3596         <para>Returns :active for tcp-stream, :passive for
    3597 listener-socket, and NIL for udp-socket</para>
    3598       </sect2>
    3599 
    3600       <sect2 id="SOCKET-FORMAT">
    3601         <para>SOCKET-FORMAT</para>
    3602         <informalfigure>socket-format</informalfigure>
    3603         <bridgehead renderas="sect3">Name</bridgehead>
    3604         <para>SOCKET-FORMAT &mdash;</para>
    3605         <para>Function</para>
    3606         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3607         <programlisting>
    3608 socket-format
    3609           socket
    3610 </programlisting>
    3611         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3612         <term><indexterm>socket
    3613             <variablelist>The socket</variablelist>
    3614           </indexterm>
    3615         </term>
    3616         <bridgehead renderas="sect3">Description</bridgehead>
    3617         <para>Returns the socket format as specified by the :format
    3618 argument to make-socket.</para>
    3619       </sect2>
    3620 
    3621       <sect2 id="SOCKET-TYPE">
    3622         <para>SOCKET-TYPE</para>
    3623         <informalfigure>socket-type</informalfigure>
    3624         <bridgehead renderas="sect3">Name</bridgehead>
    3625         <para>SOCKET-TYPE &mdash;</para>
    3626         <para>Function</para>
    3627         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3628         <programlisting>
    3629 socket-type
    3630           socket
    3631 </programlisting>
    3632         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3633         <term><indexterm>socket
    3634             <variablelist>The socket</variablelist>
    3635           </indexterm>
    3636         </term>
    3637         <bridgehead renderas="sect3">Description</bridgehead>
    3638         <para>returns :stream for tcp-stream and listener-socket, and
    3639 :datagram for udp-socket.</para>
    3640       </sect2>
    3641 
    3642       <sect2 id="SOCKET-ERROR">
    3643         <para>SOCKET-ERROR</para>
    3644         <informalfigure>socket-error</informalfigure>
    3645         <bridgehead renderas="sect3">Name</bridgehead>
    3646         <para>SOCKET-ERROR &mdash;</para>
    3647         <para>Class</para>
    3648         <bridgehead renderas="sect3">Description</bridgehead>
    3649         <para>The class of OS errors signaled by socket functions</para>
    3650         <bridgehead renderas="sect3">Superclasses</bridgehead>
    3651         <para>simple-error</para>
    3652       </sect2>
    3653 
    3654       <sect2 id="SOCKET-ERROR-CODE">
    3655         <para>SOCKET-ERROR-CODE</para>
    3656         <informalfigure>socket-error-code</informalfigure>
    3657         <bridgehead renderas="sect3">Name</bridgehead>
    3658         <para>SOCKET-ERROR-CODE &mdash;</para>
    3659         <para>Function</para>
    3660         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3661         <programlisting>
    3662 socket-error-code
    3663           socket-error
    3664 </programlisting>
    3665         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3666         <term><indexterm>socket-error
    3667             <variablelist>the condition</variablelist>
    3668           </indexterm>
    3669         </term>
    3670         <bridgehead renderas="sect3">Description</bridgehead>
    3671         <para>The OS error code of the error</para>
    3672       </sect2>
    3673 
    3674       <sect2 id="SOCKET-ERROR-IDENTIFIER">
    3675         <para>SOCKET-ERROR-IDENTIFIER</para>
    3676         <informalfigure>socket-error-identifier</informalfigure>
    3677         <bridgehead renderas="sect3">Name</bridgehead>
    3678         <para>SOCKET-ERROR-IDENTIFIER &mdash;</para>
    3679         <para>Function</para>
    3680         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3681         <programlisting>
    3682 socket-error-identifier
    3683           socket-error
    3684 </programlisting>
    3685         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3686         <term><indexterm>socket-error
    3687             <variablelist>the condition</variablelist>
    3688           </indexterm>
    3689         </term>
    3690         <bridgehead renderas="sect3">Description</bridgehead>
    3691         <para>A symbol representing the error code in a more
    3692 OS-independent way.</para>
    3693         <para>One of: :address-in-use :connection-aborted :no-buffer-space
    3694 :connection-timed-out :connection-refused :host-unreachable
    3695 :host-down :network-down :address-not-available :network-reset
    3696 :connection-reset :shutdown :access-denied or :unknown.</para>
    3697       </sect2>
    3698 
    3699       <sect2 id="SOCKET-ERROR-SITUATION">
    3700         <para>SOCKET-ERROR-SITUATION</para>
    3701         <informalfigure>socket-error-situation</informalfigure>
    3702         <bridgehead renderas="sect3">Name</bridgehead>
    3703         <para>SOCKET-ERROR-SITUATION &mdash;</para>
    3704         <para>Function</para>
    3705         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3706         <programlisting>
    3707 socket-error-situation
    3708           socket-error
    3709 </programlisting>
    3710         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3711         <term><indexterm>socket-error
    3712             <variablelist>the condition</variablelist>
    3713           </indexterm>
    3714         </term>
    3715         <bridgehead renderas="sect3">Description</bridgehead>
    3716         <para>A string describing the context where the error happened. On
    3717 Linux, this is the name of the system call which returned the
    3718 error.</para>
    3719       </sect2>
    3720 
    3721       <sect2 id="CLOSE">
    3722         <para>CLOSE</para>
    3723         <informalfigure>close</informalfigure>
    3724         <bridgehead renderas="sect3">Name</bridgehead>
    3725         <para>CLOSE &mdash;</para>
    3726         <para>Method</para>
    3727         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3728         <programlisting>
    3729 close
    3730           (socket socket) &amp;key abort
    3731 </programlisting>
    3732         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3733         <term><indexterm>socket
    3734             <variablelist>The socket to close</variablelist>
    3735           </indexterm><indexterm>abort
    3736             <variablelist>If false (the default), closes the socket in anorderly fashion, finishing up any buffered pending I/O,before closing the connection. If true, aborts/ignorespending I/O. (For listener and udp sockets, this argument iseffectively ignored since there is never any buffered I/O toclean up).</variablelist>
    3737           </indexterm>
    3738         </term>
    3739         <bridgehead renderas="sect3">Description</bridgehead>
    3740         <para>The close generic function can be applied to sockets. It
    3741 releases the operating system resources associated with the
    3742 socket.</para>
    3743       </sect2>
    3744 
    3745       <sect2 id="WITH-OPEN-SOCKET">
    3746         <para>WITH-OPEN-SOCKET</para>
    3747         <informalfigure>with-open-socket</informalfigure>
    3748         <bridgehead renderas="sect3">Name</bridgehead>
    3749         <para>WITH-OPEN-SOCKET &mdash;</para>
    3750         <para>Macro</para>
    3751         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3752         <programlisting>
    3753 with-open-socket
    3754           (var . make-socket-args) &amp;body body
    3755 </programlisting>
    3756         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3757         <term><indexterm>var
    3758             <variablelist>variable to bind</variablelist>
    3759           </indexterm><indexterm>make-socket-args
    3760             <variablelist>arguments suitable for passing to make-socket</variablelist>
    3761           </indexterm><indexterm>body
    3762             <variablelist>body to execute</variablelist>
    3763           </indexterm>
    3764         </term>
    3765         <bridgehead renderas="sect3">Description</bridgehead>
    3766         <para>executes body with var bound to the result of applying
    3767 make-socket to make-socket-args. The socket gets closed on exit.</para>
    3768       </sect2>
     4486          backlog</synopsis>
     4487        </refsynopsisdiv>
     4488
     4489        <refsect1>
     4490          <title>Arguments and Values</title>
     4491
     4492          <variablelist>
     4493            <varlistentry>
     4494              <term>address-family</term>
     4495
     4496              <listitem>
     4497                <para>The address/protocol family of this socket. Currently
     4498                only :internet (the default), meaning IP, and :file,
     4499                referring to UNIX domain addresses, are supported.</para>
     4500              </listitem>
     4501            </varlistentry>
     4502
     4503            <varlistentry>
     4504              <term>type</term>
     4505
     4506              <listitem>
     4507                <para>One of :stream (the default) to request a
     4508                connection-oriented socket, or :datagram to request a
     4509                connectionless socket. The default is :stream.</para>
     4510              </listitem>
     4511            </varlistentry>
     4512
     4513            <varlistentry>
     4514              <term>connect</term>
     4515
     4516              <listitem>
     4517                <para>This argument is only relevant to sockets of type
     4518                :stream. One of :active (the default) to request a :passive
     4519                to request a file or TCP listener socket.</para>
     4520              </listitem>
     4521            </varlistentry>
     4522
     4523            <varlistentry>
     4524              <term>eol</term>
     4525
     4526              <listitem>
     4527                <para>This argument is currently ignored (it is accepted for
     4528                compatibility with Franz Allegro).</para>
     4529              </listitem>
     4530            </varlistentry>
     4531
     4532            <varlistentry>
     4533              <term>format</term>
     4534
     4535              <listitem>
     4536                <para>One of :text (the default), :binary, or :bivalent.
     4537                This argument is ignored for :stream sockets for now, as
     4538                :stream sockets are currently always bivalent (i.e. they
     4539                support both character and byte I/O). For :datagram sockets,
     4540                the format determines the type of buffer created by
     4541                receive-from.</para>
     4542              </listitem>
     4543            </varlistentry>
     4544
     4545            <varlistentry>
     4546              <term>remote-host</term>
     4547
     4548              <listitem>
     4549                <para>Required for TCP streams, it specifies the host to
     4550                connect to (in any format acceptable to lookup-hostname).
     4551                Ignored for listener sockets. For UDP sockets, it can be
     4552                used to specify a default host for subsequent calls to
     4553                send-to or receive-from.</para>
     4554              </listitem>
     4555            </varlistentry>
     4556
     4557            <varlistentry>
     4558              <term>remote-port</term>
     4559
     4560              <listitem>
     4561                <para>Required for TCP streams, it specifies the port to
     4562                connect to (in any format acceptable to lookup-port).
     4563                Ignored for listener sockets. For UDP sockets, it can be
     4564                used to specify a default port for subsequent calls to for
     4565                subsequent calls to send-to or receive-from.</para>
     4566              </listitem>
     4567            </varlistentry>
     4568
     4569            <varlistentry>
     4570              <term>remote-filename</term>
     4571
     4572              <listitem>
     4573                <para>Required for file-socket streams, it specifies the
     4574                name of a file in the local filesystem (e.g., NOT mounted
     4575                via NFS, AFP, SMB, ...) which names and controls access to a
     4576                UNIX-domain socket.</para>
     4577              </listitem>
     4578            </varlistentry>
     4579
     4580            <varlistentry>
     4581              <term>local-host</term>
     4582
     4583              <listitem>
     4584                <para>Allows you to specify a local host address for a
     4585                listener or UDP socket, for the rare case where you want to
     4586                restrict connections to those coming to a specific local
     4587                address for security reasons.</para>
     4588              </listitem>
     4589            </varlistentry>
     4590
     4591            <varlistentry>
     4592              <term>local-port</term>
     4593
     4594              <listitem>
     4595                <para>Specify a local port for a socket. Most useful for
     4596                listener sockets, where it is the port on which the socket
     4597                will listen for connections.</para>
     4598              </listitem>
     4599            </varlistentry>
     4600
     4601            <varlistentry>
     4602              <term>local-filename</term>
     4603
     4604              <listitem>
     4605                <para>Required for file-listener-sockets. Specifies the name
     4606                of a file in the local filesystem which is used to name a
     4607                UNIX-domain socket. The actual filesystem file should not
     4608                previously exist when the file-listener-socket is created;
     4609                its parent directory should exist and be writable by the
     4610                caller. The file used to name the socket will be deleted
     4611                when the file-listener-socket is closed.</para>
     4612              </listitem>
     4613            </varlistentry>
     4614
     4615            <varlistentry>
     4616              <term>keepalive</term>
     4617
     4618              <listitem>
     4619                <para>If true, enables the periodic transmission of
     4620                &#34;keepalive&#34; messages.</para>
     4621              </listitem>
     4622            </varlistentry>
     4623
     4624            <varlistentry>
     4625              <term>reuse-address</term>
     4626
     4627              <listitem>
     4628                <para>If true, allows the reuse of local ports in listener
     4629                sockets, overriding some TCP/IP protocol specifications. You
     4630                will need this if you are debugging a server..</para>
     4631              </listitem>
     4632            </varlistentry>
     4633
     4634            <varlistentry>
     4635              <term>nodelay</term>
     4636
     4637              <listitem>
     4638                <para>If true, disables Nagle&#39;s algorithm, which tries
     4639                to minimize TCP packet fragmentation by introducing
     4640                transmission delays in the absence of replies. Try setting
     4641                this if you are using a protocol which involves sending a
     4642                steady stream of data with no replies and are seeing
     4643                significant degradations in throughput.</para>
     4644              </listitem>
     4645            </varlistentry>
     4646
     4647            <varlistentry>
     4648              <term>broadcast</term>
     4649
     4650              <listitem>
     4651                <para>If true, requests permission to broadcast datagrams on
     4652                a UDP socket.</para>
     4653              </listitem>
     4654            </varlistentry>
     4655
     4656            <varlistentry>
     4657              <term>linger</term>
     4658
     4659              <listitem>
     4660                <para>If specified and non-nil, should be the number of
     4661                seconds the OS is allowed to wait for data to be pushed
     4662                through when a close is done. Only relevant for TCP sockets.</para>
     4663              </listitem>
     4664            </varlistentry>
     4665
     4666            <varlistentry>
     4667              <term>backlog</term>
     4668
     4669              <listitem>
     4670                <para>For a listener socket, specifies the number of
     4671                connections which can be pending but not accepted. The
     4672                default is 5, which is also the maximum on some operating
     4673                systems.</para>
     4674              </listitem>
     4675            </varlistentry>
     4676          </variablelist>
     4677        </refsect1>
     4678
     4679        <refsect1>
     4680          <title>Description</title>
     4681
     4682          <para>Creates and returns a new socket</para>
     4683        </refsect1>
     4684      </refentry>
     4685
     4686      <refentry id="f_accept-connection">
     4687        <indexterm zone="f_accept-connection">
     4688          <primary>accept-connection</primary>
     4689        </indexterm>
     4690        <refnamediv>
     4691          <refname>ACCEPT-CONNECTION</refname>
     4692          <refpurpose></refpurpose>
     4693          <refclass>Function</refclass>
     4694        </refnamediv>
     4695
     4696        <refsynopsisdiv>
     4697          <synopsis><function>accept-connection</function>
     4698          (socket listener-socket) &key; wait</synopsis>
     4699        </refsynopsisdiv>
     4700
     4701        <refsect1>
     4702          <title>Arguments and Values</title>
     4703
     4704          <variablelist>
     4705            <varlistentry>
     4706              <term>socket</term>
     4707
     4708              <listitem>
     4709                <para>The listener-socket to listen on.</para>
     4710              </listitem>
     4711            </varlistentry>
     4712
     4713            <varlistentry>
     4714              <term>wait</term>
     4715
     4716              <listitem>
     4717                <para>If true (the default), and there are no connections
     4718                waiting to be accepted, waits until one arrives. If false,
     4719                returns NIL immediately.</para>
     4720              </listitem>
     4721            </varlistentry>
     4722          </variablelist>
     4723        </refsect1>
     4724
     4725        <refsect1>
     4726          <title>Description</title>
     4727
     4728          <para>Extracts the first connection on the queue of pending
     4729          connections, accepts it (i.e. completes the connection startup
     4730          protocol) and returns a new tcp-stream or file-socket-stream
     4731          representing the newly established connection. The tcp stream
     4732          inherits any properties of the listener socket that are relevant
     4733          (e.g. :keepalive, :nodelay, etc.) The original listener socket
     4734          continues to be open listening for more connections, so you can
     4735          call accept-connection on it again.</para>
     4736        </refsect1>
     4737      </refentry>
     4738
     4739      <refentry id="f_dotted-to-ipaddr">
     4740        <indexterm zone="f_dotted-to-ipaddr">
     4741          <primary>dotted-to-ipaddr</primary>
     4742        </indexterm>
     4743        <refnamediv>
     4744          <refname>DOTTED-TO-IPADDR</refname>
     4745          <refpurpose></refpurpose>
     4746          <refclass>Function</refclass>
     4747        </refnamediv>
     4748
     4749        <refsynopsisdiv>
     4750          <synopsis><function>dotted-to-ipaddr</function>
     4751          dotted &key; errorp</synopsis>
     4752        </refsynopsisdiv>
     4753
     4754        <refsect1>
     4755          <title>Arguments and Values</title>
     4756
     4757          <variablelist>
     4758            <varlistentry>
     4759              <term>dotted</term>
     4760
     4761              <listitem>
     4762                <para>A string representing an IP address in the
     4763                &#34;nn.nn.nn.nn&#34; format</para>
     4764              </listitem>
     4765            </varlistentry>
     4766
     4767            <varlistentry>
     4768              <term>errorp</term>
     4769
     4770              <listitem>
     4771                <para>If true (the default) an error is signaled if dotted
     4772                is invalid. If false, NIL is returned.</para>
     4773              </listitem>
     4774            </varlistentry>
     4775          </variablelist>
     4776        </refsect1>
     4777
     4778        <refsect1>
     4779          <title>Description</title>
     4780
     4781          <para>Converts a dotted-string representation of a host address to
     4782          a 32-bit unsigned IP address.</para>
     4783        </refsect1>
     4784      </refentry>
     4785
     4786      <refentry id="f_ipaddr-to-dotted">
     4787        <indexterm zone="f_ipaddr-to-dotted">
     4788          <primary>ipaddr-to-dotted</primary>
     4789        </indexterm>
     4790        <refnamediv>
     4791          <refname>IPADDR-TO-DOTTED</refname>
     4792          <refpurpose></refpurpose>
     4793          <refclass>Function</refclass>
     4794        </refnamediv>
     4795
     4796        <refsynopsisdiv>
     4797          <synopsis><function>ipaddr-to-dotted</function>
     4798          ipaddr &key; values</synopsis>
     4799        </refsynopsisdiv>
     4800
     4801        <refsect1>
     4802          <title>Arguments and Values</title>
     4803
     4804          <variablelist>
     4805            <varlistentry>
     4806              <term>ipaddr</term>
     4807
     4808              <listitem>
     4809                <para>A 32-bit integer representing an internet host address</para>
     4810              </listitem>
     4811            </varlistentry>
     4812
     4813            <varlistentry>
     4814              <term>values</term>
     4815
     4816              <listitem>
     4817                <para>If false (the default), returns a string in the form
     4818                &#34;nn.nn.nn.nn&#34;. If true, returns four values
     4819                representing the four octets of the address as unsigned
     4820                8-bit integers.</para>
     4821              </listitem>
     4822            </varlistentry>
     4823          </variablelist>
     4824        </refsect1>
     4825
     4826        <refsect1>
     4827          <title>Description</title>
     4828
     4829          <para>Converts a 32-bit unsigned IP address into octets.</para>
     4830        </refsect1>
     4831      </refentry>
     4832
     4833      <refentry id="f_ipaddr-to-hostname">
     4834        <indexterm zone="f_ipaddr-to-hostname">
     4835          <primary>ipaddr-to-hostname</primary>
     4836        </indexterm>
     4837        <refnamediv>
     4838          <refname>IPADDR-TO-HOSTNAME</refname>
     4839          <refpurpose></refpurpose>
     4840          <refclass>Function</refclass>
     4841        </refnamediv>
     4842
     4843        <refsynopsisdiv>
     4844          <synopsis><function>ipaddr-to-hostname</function>
     4845          ipaddr &key; ignore-cache</synopsis>
     4846        </refsynopsisdiv>
     4847
     4848        <refsect1>
     4849          <title>Arguments and Values</title>
     4850
     4851          <variablelist>
     4852            <varlistentry>
     4853              <term>ipaddr</term>
     4854
     4855              <listitem>
     4856                <para>a 32-bit integer representing an internet host address</para>
     4857              </listitem>
     4858            </varlistentry>
     4859
     4860            <varlistentry>
     4861              <term>ignore-cache</term>
     4862
     4863              <listitem>
     4864                <para>This argument is ignored (it is accepted for
     4865                compatibility with Franz Allegro)</para>
     4866              </listitem>
     4867            </varlistentry>
     4868          </variablelist>
     4869        </refsect1>
     4870
     4871        <refsect1>
     4872          <title>Description</title>
     4873
     4874          <para>Converts a 32-bit unsigned IP address into a host name
     4875          string</para>
     4876        </refsect1>
     4877      </refentry>
     4878
     4879      <refentry id="f_lookup-hostname">
     4880        <indexterm zone="f_lookup-hostname">
     4881          <primary>lookup-hostname</primary>
     4882        </indexterm>
     4883        <refnamediv>
     4884          <refname>LOOKUP-HOSTNAME</refname>
     4885          <refpurpose></refpurpose>
     4886          <refclass>Function</refclass>
     4887        </refnamediv>
     4888
     4889        <refsynopsisdiv>
     4890          <synopsis><function>lookup-hostname</function>
     4891          host</synopsis>
     4892        </refsynopsisdiv>
     4893
     4894        <refsect1>
     4895          <title>Arguments and Values</title>
     4896
     4897          <variablelist>
     4898            <varlistentry>
     4899              <term>host</term>
     4900
     4901              <listitem>
     4902                <para>Specifies the host. It can be either a host name
     4903                string such as &#34;clozure.com&#34;, or a dotted address
     4904                string such as &#34;192.168.0.1&#34;, or a 32-bit unsigned
     4905                IP address such as 3232235521.</para>
     4906              </listitem>
     4907            </varlistentry>
     4908          </variablelist>
     4909        </refsect1>
     4910
     4911        <refsect1>
     4912          <title>Description</title>
     4913
     4914          <para>Converts a host spec in any of the acceptable formats into a
     4915          32-bit unsigned IP address</para>
     4916        </refsect1>
     4917      </refentry>
     4918
     4919      <refentry id="f_lookup-port">
     4920        <indexterm zone="f_lookup-port">
     4921          <primary>lookup-port</primary>
     4922        </indexterm>
     4923        <refnamediv>
     4924          <refname>LOOKUP-PORT</refname>
     4925          <refpurpose></refpurpose>
     4926          <refclass>Function</refclass>
     4927        </refnamediv>
     4928
     4929        <refsynopsisdiv>
     4930          <synopsis><function>lookup-port</function>
     4931          port protocol</synopsis>
     4932        </refsynopsisdiv>
     4933
     4934        <refsect1>
     4935          <title>Arguments and Values</title>
     4936
     4937          <variablelist>
     4938            <varlistentry>
     4939              <term>port</term>
     4940
     4941              <listitem>
     4942                <para>Specifies the port. It can be either a string, such as
     4943                &#34;http&#34; or a symbol, such as :http, or an unsigned
     4944                port number. Note that a string is case-sensitive. A symbol
     4945                is lowercased before lookup.</para>
     4946              </listitem>
     4947            </varlistentry>
     4948
     4949            <varlistentry>
     4950              <term>protocol</term>
     4951
     4952              <listitem>
     4953                <para>Must be one of &#34;tcp&#34; or &#34;udp&#34;.</para>
     4954              </listitem>
     4955            </varlistentry>
     4956          </variablelist>
     4957        </refsect1>
     4958
     4959        <refsect1>
     4960          <title>Description</title>
     4961
     4962          <para>Finds the port number for the specified port and protocol</para>
     4963        </refsect1>
     4964      </refentry>
     4965
     4966      <refentry id="f_receive-from">
     4967        <indexterm zone="f_receive-from">
     4968          <primary>receive-from</primary>
     4969        </indexterm>
     4970        <refnamediv>
     4971          <refname>RECEIVE-FROM</refname>
     4972          <refpurpose></refpurpose>
     4973          <refclass>Function</refclass>
     4974        </refnamediv>
     4975
     4976        <refsynopsisdiv>
     4977          <synopsis><function>receive-from</function>
     4978          (socket udp-socket) size &key; buffer
     4979          extract offset</synopsis>
     4980        </refsynopsisdiv>
     4981
     4982        <refsect1>
     4983          <title>Arguments and Values</title>
     4984
     4985          <variablelist>
     4986            <varlistentry>
     4987              <term>socket</term>
     4988
     4989              <listitem>
     4990                <para>The socket to read from</para>
     4991              </listitem>
     4992            </varlistentry>
     4993
     4994            <varlistentry>
     4995              <term>size</term>
     4996
     4997              <listitem>
     4998                <para>Maximum number of bytes to read. If the packet is
     4999                larger than this, any extra bytes are discarded.</para>
     5000              </listitem>
     5001            </varlistentry>
     5002
     5003            <varlistentry>
     5004              <term>buffer</term>
     5005
     5006              <listitem>
     5007                <para>If specified, must be either a string or a byte vector
     5008                which will be used to read in the data. If not specified, a
     5009                new buffer will be created (of type determined by
     5010                socket-format).</para>
     5011              </listitem>
     5012            </varlistentry>
     5013
     5014            <varlistentry>
     5015              <term>extract</term>
     5016
     5017              <listitem>
     5018                <para>If true, the subsequence of the buffer corresponding
     5019                only to the data read in is extracted and returned as the
     5020                first value. If false (the default) the original buffer is
     5021                returned even if it is only partially filled.</para>
     5022              </listitem>
     5023            </varlistentry>
     5024
     5025            <varlistentry>
     5026              <term>offset</term>
     5027
     5028              <listitem>
     5029                <para>Specifies the start offset into the buffer at which
     5030                data is to be stored. The default is 0.</para>
     5031              </listitem>
     5032            </varlistentry>
     5033          </variablelist>
     5034        </refsect1>
     5035
     5036        <refsect1>
     5037          <title>Description</title>
     5038
     5039          <para>Reads a UDP packet from a socket. If no packets are
     5040          available, waits for a packet to arrive. Returns four values:</para>
     5041
     5042          <orderedlist continuation="restarts" inheritnum="ignore">
     5043            <listitem>
     5044              <para>The buffer with the data</para>
     5045            </listitem>
     5046
     5047            <listitem>
     5048              <para>The number of bytes read</para>
     5049            </listitem>
     5050
     5051            <listitem>
     5052              <para>The 32-bit unsigned IP address of the sender of the data</para>
     5053            </listitem>
     5054
     5055            <listitem>
     5056              <para>The port number of the sender of the data</para>
     5057            </listitem>
     5058          </orderedlist>
     5059        </refsect1>
     5060      </refentry>
     5061
     5062      <refentry id="f_send-to">
     5063        <indexterm zone="f_send-to">
     5064          <primary>send-to</primary>
     5065        </indexterm>
     5066        <refnamediv>
     5067          <refname>SEND-TO</refname>
     5068          <refpurpose></refpurpose>
     5069          <refclass>Function</refclass>
     5070        </refnamediv>
     5071
     5072        <refsynopsisdiv>
     5073          <synopsis><function>send-to</function>
     5074          (socket udp-socket) buffer size &key; remote-host
     5075          remote-port offset</synopsis>
     5076        </refsynopsisdiv>
     5077
     5078        <refsect1>
     5079          <title>Arguments and Values</title>
     5080
     5081          <variablelist>
     5082            <varlistentry>
     5083              <term>socket</term>
     5084
     5085              <listitem>
     5086                <para>The socket to write to</para>
     5087              </listitem>
     5088            </varlistentry>
     5089
     5090            <varlistentry>
     5091              <term>buffer</term>
     5092
     5093              <listitem>
     5094                <para>A vector containing the data to send. It must be
     5095                either a string or a byte vector (either one is acceptable
     5096                regardless of the stream format).</para>
     5097              </listitem>
     5098            </varlistentry>
     5099
     5100            <varlistentry>
     5101              <term>size</term>
     5102
     5103              <listitem>
     5104                <para>Number of bytes to send</para>
     5105              </listitem>
     5106            </varlistentry>
     5107
     5108            <varlistentry>
     5109              <term>remote-host</term>
     5110
     5111              <listitem>
     5112                <para>The host to send the packet to, in any format
     5113                acceptable to lookup-hostname. The default is the remote
     5114                host specified in the call to make-socket.</para>
     5115              </listitem>
     5116            </varlistentry>
     5117
     5118            <varlistentry>
     5119              <term>remote-port</term>
     5120
     5121              <listitem>
     5122                <para>The port to send the packet to, in any format
     5123                acceptable to lookup-port. The default is the remote port
     5124                specified in the call to make-socket.</para>
     5125              </listitem>
     5126            </varlistentry>
     5127
     5128            <varlistentry>
     5129              <term>offset</term>
     5130
     5131              <listitem>
     5132                <para>The offset in the buffer where the packet data starts</para>
     5133              </listitem>
     5134            </varlistentry>
     5135          </variablelist>
     5136        </refsect1>
     5137
     5138        <refsect1>
     5139          <title>Description</title>
     5140
     5141          <para>Send a UDP packet over a socket.</para>
     5142        </refsect1>
     5143      </refentry>
     5144
     5145      <refentry id="f_shutdown">
     5146        <indexterm zone="f_shutdown">
     5147          <primary>shutdown</primary>
     5148        </indexterm>
     5149        <refnamediv>
     5150          <refname>SHUTDOWN</refname>
     5151          <refpurpose></refpurpose>
     5152          <refclass>Function</refclass>
     5153        </refnamediv>
     5154
     5155        <refsynopsisdiv>
     5156          <synopsis><function>shutdown</function>
     5157          socket &key; direction</synopsis>
     5158        </refsynopsisdiv>
     5159
     5160        <refsect1>
     5161          <title>Arguments and Values</title>
     5162
     5163          <variablelist>
     5164            <varlistentry>
     5165              <term>socket</term>
     5166
     5167              <listitem>
     5168                <para>The socket to shut down (typically a tcp-stream)</para>
     5169              </listitem>
     5170            </varlistentry>
     5171
     5172            <varlistentry>
     5173              <term>direction</term>
     5174
     5175              <listitem>
     5176                <para>One of :input to disallow further input, or :output to
     5177                disallow further output.</para>
     5178              </listitem>
     5179            </varlistentry>
     5180          </variablelist>
     5181        </refsect1>
     5182
     5183        <refsect1>
     5184          <title>Description</title>
     5185
     5186          <para>Shuts down part of a bidirectional connection. This is
     5187          useful if e.g. you need to read responses after sending an
     5188          end-of-file signal.</para>
     5189        </refsect1>
     5190      </refentry>
     5191
     5192      <refentry id="f_socket-os-fd">
     5193        <indexterm zone="f_socket-os-fd">
     5194          <primary>socket-os-fd</primary>
     5195        </indexterm>
     5196        <refnamediv>
     5197          <refname>SOCKET-OS-FD</refname>
     5198          <refpurpose></refpurpose>
     5199          <refclass>Function</refclass>
     5200        </refnamediv>
     5201
     5202        <refsynopsisdiv>
     5203          <synopsis><function>socket-os-fd</function>
     5204          socket</synopsis>
     5205        </refsynopsisdiv>
     5206
     5207        <refsect1>
     5208          <title>Arguments and Values</title>
     5209
     5210          <variablelist>
     5211            <varlistentry>
     5212              <term>socket</term>
     5213
     5214              <listitem>
     5215                <para>The socket</para>
     5216              </listitem>
     5217            </varlistentry>
     5218          </variablelist>
     5219        </refsect1>
     5220
     5221        <refsect1>
     5222          <title>Description</title>
     5223
     5224          <para>Returns the native OS&#39;s representation of the socket, or
     5225          NIL if the socket is closed. On Unix, this is the Unix &#39;file
     5226          descriptor&#39;, a small non-negative integer. Note that it is
     5227          rather dangerous to mess around with tcp-stream fd&#39;s, as there
     5228          is all sorts of buffering and asynchronous I/O going on above the
     5229          OS level. listener-socket and udp-socket fd&#39;s are safer to
     5230          mess with directly as there is less magic going on.</para>
     5231        </refsect1>
     5232      </refentry>
     5233
     5234      <refentry id="f_remote-host">
     5235        <indexterm zone="f_remote-host">
     5236          <primary>remote-host</primary>
     5237        </indexterm>
     5238        <refnamediv>
     5239          <refname>REMOTE-HOST</refname>
     5240          <refpurpose></refpurpose>
     5241          <refclass>Function</refclass>
     5242        </refnamediv>
     5243
     5244        <refsynopsisdiv>
     5245          <synopsis><function>remote-host</function>
     5246          socket</synopsis>
     5247        </refsynopsisdiv>
     5248
     5249        <refsect1>
     5250          <title>Arguments and Values</title>
     5251
     5252          <variablelist>
     5253            <varlistentry>
     5254              <term>socket</term>
     5255
     5256              <listitem>
     5257                <para>The socket</para>
     5258              </listitem>
     5259            </varlistentry>
     5260          </variablelist>
     5261        </refsect1>
     5262
     5263        <refsect1>
     5264          <title>Description</title>
     5265
     5266          <para>Returns the 32-bit unsigned IP address of the remote host,
     5267          or NIL if the socket is not connected.</para>
     5268        </refsect1>
     5269      </refentry>
     5270
     5271      <refentry id="f_remote-port">
     5272        <indexterm zone="f_remote-port">
     5273          <primary>remote-port</primary>
     5274        </indexterm>
     5275        <refnamediv>
     5276          <refname>REMOTE-PORT</refname>
     5277          <refpurpose></refpurpose>
     5278          <refclass>Function</refclass>
     5279        </refnamediv>
     5280
     5281        <refsynopsisdiv>
     5282          <synopsis><function>remote-port</function>
     5283          socket</synopsis>
     5284        </refsynopsisdiv>
     5285
     5286        <refsect1>
     5287          <title>Arguments and Values</title>
     5288
     5289          <variablelist>
     5290            <varlistentry>
     5291              <term>socket</term>
     5292
     5293              <listitem>
     5294                <para>The socket</para>
     5295              </listitem>
     5296            </varlistentry>
     5297          </variablelist>
     5298        </refsect1>
     5299
     5300        <refsect1>
     5301          <title>Description</title>
     5302
     5303          <para>Returns the remote port number, or NIL if the socket is not
     5304          connected.</para>
     5305        </refsect1>
     5306      </refentry>
     5307
     5308      <refentry id="f_local-host">
     5309        <indexterm zone="f_local-host">
     5310          <primary>local-host</primary>
     5311        </indexterm>
     5312        <refnamediv>
     5313          <refname>LOCAL-HOST</refname>
     5314          <refpurpose></refpurpose>
     5315          <refclass>Function</refclass>
     5316        </refnamediv>
     5317
     5318        <refsynopsisdiv>
     5319          <synopsis><function>local-host</function>
     5320          socket</synopsis>
     5321        </refsynopsisdiv>
     5322
     5323        <refsect1>
     5324          <title>Arguments and Values</title>
     5325
     5326          <variablelist>
     5327            <varlistentry>
     5328              <term>socket</term>
     5329
     5330              <listitem>
     5331                <para>The socket</para>
     5332              </listitem>
     5333            </varlistentry>
     5334          </variablelist>
     5335        </refsect1>
     5336
     5337        <refsect1>
     5338          <title>Description</title>
     5339
     5340          <para>Returns 32-bit unsigned IP address of the local host.</para>
     5341        </refsect1>
     5342      </refentry>
     5343
     5344      <refentry id="f_local-port">
     5345        <indexterm zone="f_local-port">
     5346          <primary>local-port</primary>
     5347        </indexterm>
     5348        <refnamediv>
     5349          <refname>LOCAL-PORT</refname>
     5350          <refpurpose></refpurpose>
     5351          <refclass>Function</refclass>
     5352        </refnamediv>
     5353
     5354        <refsynopsisdiv>
     5355          <synopsis><function>local-port</function>
     5356          socket</synopsis>
     5357        </refsynopsisdiv>
     5358
     5359        <refsect1>
     5360          <title>Arguments and Values</title>
     5361
     5362          <variablelist>
     5363            <varlistentry>
     5364              <term>socket</term>
     5365
     5366              <listitem>
     5367                <para>The socket</para>
     5368              </listitem>
     5369            </varlistentry>
     5370          </variablelist>
     5371        </refsect1>
     5372
     5373        <refsect1>
     5374          <title>Description</title>
     5375
     5376          <para>Returns the local port number</para>
     5377        </refsect1>
     5378      </refentry>
     5379
     5380      <refentry id="f_socket-address-family">
     5381        <indexterm zone="f_socket-address-family">
     5382          <primary>socket-address-family</primary>
     5383        </indexterm>
     5384        <refnamediv>
     5385          <refname>SOCKET-ADDRESS-FAMILY</refname>
     5386          <refpurpose></refpurpose>
     5387          <refclass>Function</refclass>
     5388        </refnamediv>
     5389
     5390        <refsynopsisdiv>
     5391          <synopsis><function>socket-address-family</function>
     5392          socket</synopsis>
     5393        </refsynopsisdiv>
     5394
     5395        <refsect1>
     5396          <title>Arguments and Values</title>
     5397
     5398          <variablelist>
     5399            <varlistentry>
     5400              <term>socket</term>
     5401
     5402              <listitem>
     5403                <para>The socket</para>
     5404              </listitem>
     5405            </varlistentry>
     5406          </variablelist>
     5407        </refsect1>
     5408
     5409        <refsect1>
     5410          <title>Description</title>
     5411
     5412          <para>Returns :internet or :file, as appropriate.</para>
     5413        </refsect1>
     5414      </refentry>
     5415
     5416      <refentry id="f_socket-connect">
     5417        <indexterm zone="f_socket-connect">
     5418          <primary>socket-connect</primary>
     5419        </indexterm>
     5420        <refnamediv>
     5421          <refname>SOCKET-CONNECT</refname>
     5422          <refpurpose></refpurpose>
     5423          <refclass>Function</refclass>
     5424        </refnamediv>
     5425
     5426        <refsynopsisdiv>
     5427          <synopsis><function>socket-connect</function>
     5428          socket</synopsis>
     5429        </refsynopsisdiv>
     5430
     5431        <refsect1>
     5432          <title>Arguments and Values</title>
     5433
     5434          <variablelist>
     5435            <varlistentry>
     5436              <term>socket</term>
     5437
     5438              <listitem>
     5439                <para>The socket</para>
     5440              </listitem>
     5441            </varlistentry>
     5442          </variablelist>
     5443        </refsect1>
     5444
     5445        <refsect1>
     5446          <title>Description</title>
     5447
     5448          <para>Returns :active for tcp-stream, :passive for
     5449          listener-socket, and NIL for udp-socket</para>
     5450        </refsect1>
     5451      </refentry>
     5452
     5453      <refentry id="f_socket-format">
     5454        <indexterm zone="f_socket-format">
     5455          <primary>socket-format</primary>
     5456        </indexterm>
     5457        <refnamediv>
     5458          <refname>SOCKET-FORMAT</refname>
     5459          <refpurpose></refpurpose>
     5460          <refclass>Function</refclass>
     5461        </refnamediv>
     5462
     5463        <refsynopsisdiv>
     5464          <synopsis><function>socket-format</function>
     5465          socket</synopsis>
     5466        </refsynopsisdiv>
     5467
     5468        <refsect1>
     5469          <title>Arguments and Values</title>
     5470
     5471          <variablelist>
     5472            <varlistentry>
     5473              <term>socket</term>
     5474
     5475              <listitem>
     5476                <para>The socket</para>
     5477              </listitem>
     5478            </varlistentry>
     5479          </variablelist>
     5480        </refsect1>
     5481
     5482        <refsect1>
     5483          <title>Description</title>
     5484
     5485          <para>Returns the socket format as specified by the :format
     5486          argument to make-socket.</para>
     5487        </refsect1>
     5488      </refentry>
     5489
     5490      <refentry id="f_socket-type">
     5491        <indexterm zone="f_socket-type">
     5492          <primary>socket-type</primary>
     5493        </indexterm>
     5494        <refnamediv>
     5495          <refname>SOCKET-TYPE</refname>
     5496          <refpurpose></refpurpose>
     5497          <refclass>Function</refclass>
     5498        </refnamediv>
     5499
     5500        <refsynopsisdiv>
     5501          <synopsis><function>socket-type</function>
     5502          socket</synopsis>
     5503        </refsynopsisdiv>
     5504
     5505        <refsect1>
     5506          <title>Arguments and Values</title>
     5507
     5508          <variablelist>
     5509            <varlistentry>
     5510              <term>socket</term>
     5511
     5512              <listitem>
     5513                <para>The socket</para>
     5514              </listitem>
     5515            </varlistentry>
     5516          </variablelist>
     5517        </refsect1>
     5518
     5519        <refsect1>
     5520          <title>Description</title>
     5521
     5522          <para>returns :stream for tcp-stream and listener-socket, and
     5523          :datagram for udp-socket.</para>
     5524        </refsect1>
     5525      </refentry>
     5526
     5527      <refentry id="c_socket-error">
     5528        <indexterm zone="c_socket-error">
     5529          <primary>socket-error</primary>
     5530        </indexterm>
     5531        <refnamediv>
     5532          <refname>SOCKET-ERROR</refname>
     5533          <refpurpose></refpurpose>
     5534          <refclass>Class</refclass>
     5535        </refnamediv>
     5536
     5537        <refsect1>
     5538          <title>Description</title>
     5539
     5540          <para>The class of OS errors signaled by socket functions</para>
     5541        </refsect1>
     5542
     5543        <refsect1>
     5544          <title>Superclasses</title>
     5545
     5546          <para>simple-error</para>
     5547        </refsect1>
     5548      </refentry>
     5549
     5550      <refentry id="f_socket-error-code">
     5551        <indexterm zone="f_socket-error-code">
     5552          <primary>socket-error-code</primary>
     5553        </indexterm>
     5554        <refnamediv>
     5555          <refname>SOCKET-ERROR-CODE</refname>
     5556          <refpurpose></refpurpose>
     5557          <refclass>Function</refclass>
     5558        </refnamediv>
     5559
     5560        <refsynopsisdiv>
     5561          <synopsis><function>socket-error-code</function>
     5562          socket-error</synopsis>
     5563        </refsynopsisdiv>
     5564
     5565        <refsect1>
     5566          <title>Arguments and Values</title>
     5567
     5568          <variablelist>
     5569            <varlistentry>
     5570              <term>socket-error</term>
     5571
     5572              <listitem>
     5573                <para>the condition</para>
     5574              </listitem>
     5575            </varlistentry>
     5576          </variablelist>
     5577        </refsect1>
     5578
     5579        <refsect1>
     5580          <title>Description</title>
     5581
     5582          <para>The OS error code of the error</para>
     5583        </refsect1>
     5584      </refentry>
     5585
     5586      <refentry id="f_socket-error-identifier">
     5587        <indexterm zone="f_socket-error-identifier">
     5588          <primary>socket-error-identifier</primary>
     5589        </indexterm>
     5590        <refnamediv>
     5591          <refname>SOCKET-ERROR-IDENTIFIER</refname>
     5592          <refpurpose></refpurpose>
     5593          <refclass>Function</refclass>
     5594        </refnamediv>
     5595
     5596        <refsynopsisdiv>
     5597          <synopsis><function>socket-error-identifier</function>
     5598          socket-error</synopsis>
     5599        </refsynopsisdiv>
     5600
     5601        <refsect1>
     5602          <title>Arguments and Values</title>
     5603
     5604          <variablelist>
     5605            <varlistentry>
     5606              <term>socket-error</term>
     5607
     5608              <listitem>
     5609                <para>the condition</para>
     5610              </listitem>
     5611            </varlistentry>
     5612          </variablelist>
     5613        </refsect1>
     5614
     5615        <refsect1>
     5616          <title>Description</title>
     5617
     5618          <para>A symbol representing the error code in a more
     5619          OS-independent way.</para>
     5620
     5621          <para>One of: :address-in-use :connection-aborted :no-buffer-space
     5622          :connection-timed-out :connection-refused :host-unreachable
     5623          :host-down :network-down :address-not-available :network-reset
     5624          :connection-reset :shutdown :access-denied or :unknown.</para>
     5625        </refsect1>
     5626      </refentry>
     5627
     5628      <refentry id="f_socket-error-situation">
     5629        <indexterm zone="f_socket-error-situation">
     5630          <primary>socket-error-situation</primary>
     5631        </indexterm>
     5632        <refnamediv>
     5633          <refname>SOCKET-ERROR-SITUATION</refname>
     5634          <refpurpose></refpurpose>
     5635          <refclass>Function</refclass>
     5636        </refnamediv>
     5637
     5638        <refsynopsisdiv>
     5639          <synopsis><function>socket-error-situation</function>
     5640          socket-error</synopsis>
     5641        </refsynopsisdiv>
     5642
     5643        <refsect1>
     5644          <title>Arguments and Values</title>
     5645
     5646          <variablelist>
     5647            <varlistentry>
     5648              <term>socket-error</term>
     5649
     5650              <listitem>
     5651                <para>the condition</para>
     5652              </listitem>
     5653            </varlistentry>
     5654          </variablelist>
     5655        </refsect1>
     5656
     5657        <refsect1>
     5658          <title>Description</title>
     5659
     5660          <para>A string describing the context where the error happened. On
     5661          Linux, this is the name of the system call which returned the
     5662          error.</para>
     5663        </refsect1>
     5664      </refentry>
     5665
     5666      <refentry id="o_close">
     5667        <indexterm zone="o_close">
     5668          <primary>close</primary>
     5669        </indexterm>
     5670        <refnamediv>
     5671          <refname>CLOSE</refname>
     5672          <refpurpose></refpurpose>
     5673          <refclass>Method</refclass>
     5674        </refnamediv>
     5675
     5676        <refsynopsisdiv>
     5677          <synopsis><function>close</function>
     5678          (socket socket) &key; abort</synopsis>
     5679        </refsynopsisdiv>
     5680
     5681        <refsect1>
     5682          <title>Arguments and Values</title>
     5683
     5684          <variablelist>
     5685            <varlistentry>
     5686              <term>socket</term>
     5687
     5688              <listitem>
     5689                <para>The socket to close</para>
     5690              </listitem>
     5691            </varlistentry>
     5692
     5693            <varlistentry>
     5694              <term>abort</term>
     5695
     5696              <listitem>
     5697                <para>If false (the default), closes the socket in an
     5698                orderly fashion, finishing up any buffered pending I/O,
     5699                before closing the connection. If true, aborts/ignores
     5700                pending I/O. (For listener and udp sockets, this argument is
     5701                effectively ignored since there is never any buffered I/O to
     5702                clean up).</para>
     5703              </listitem>
     5704            </varlistentry>
     5705          </variablelist>
     5706        </refsect1>
     5707
     5708        <refsect1>
     5709          <title>Description</title>
     5710
     5711          <para>The close generic function can be applied to sockets. It
     5712          releases the operating system resources associated with the
     5713          socket.</para>
     5714        </refsect1>
     5715      </refentry>
     5716
     5717      <refentry id="m_with-open-socket">
     5718        <indexterm zone="m_with-open-socket">
     5719          <primary>with-open-socket</primary>
     5720        </indexterm>
     5721        <refnamediv>
     5722          <refname>WITH-OPEN-SOCKET</refname>
     5723          <refpurpose></refpurpose>
     5724          <refclass>Macro</refclass>
     5725        </refnamediv>
     5726
     5727        <refsynopsisdiv>
     5728          <synopsis><function>with-open-socket</function>
     5729          (var . make-socket-args) &body; body</synopsis>
     5730        </refsynopsisdiv>
     5731
     5732        <refsect1>
     5733          <title>Arguments and Values</title>
     5734
     5735          <variablelist>
     5736            <varlistentry>
     5737              <term>var</term>
     5738
     5739              <listitem>
     5740                <para>variable to bind</para>
     5741              </listitem>
     5742            </varlistentry>
     5743
     5744            <varlistentry>
     5745              <term>make-socket-args</term>
     5746
     5747              <listitem>
     5748                <para>arguments suitable for passing to make-socket</para>
     5749              </listitem>
     5750            </varlistentry>
     5751
     5752            <varlistentry>
     5753              <term>body</term>
     5754
     5755              <listitem>
     5756                <para>body to execute</para>
     5757              </listitem>
     5758            </varlistentry>
     5759          </variablelist>
     5760        </refsect1>
     5761
     5762        <refsect1>
     5763          <title>Description</title>
     5764
     5765          <para>executes body with var bound to the result of applying
     5766          make-socket to make-socket-args. The socket gets closed on exit.</para>
     5767        </refsect1>
     5768      </refentry>
    37695769    </sect1>
    37705770  </chapter>
     
    38055805
    38065806    <sect1 id="Limitations-and-known-bugs">
    3807       <para>Limitations and known bugs</para>
     5807      <title>Limitations and known bugs</title>
    38085808      <itemizedlist>
    38095809        <listitem><para>OpenMCL and the external processs may get
     
    38215821    <sect1 id="External-Program-Dictionary">
    38225822      <title>External-Program Dictionary</title>
    3823 
    3824       <sect2 id="RUN-PROGRAM">
    3825         <para>RUN-PROGRAM</para>
    3826         <informalfigure>run-program</informalfigure>
    3827         <bridgehead renderas="sect3">Name</bridgehead>
    3828         <para>RUN-PROGRAM &mdash; Invokes an external program as an OS subprocess
    3829 of lisp.</para>
    3830         <para>Function</para>
    3831         <bridgehead renderas="sect3">Synopsis</bridgehead>
    3832         <programlisting>
    3833 run-program
    3834             program args &amp;key (wait t) pty input
     5823        <refentry id="f_run-program">
     5824          <indexterm zone="f_run-program">
     5825            <primary>run-program</primary>
     5826          </indexterm>
     5827
     5828          <refnamediv>
     5829            <refname>RUN-PROGRAM</refname>
     5830            <refpurpose>Invokes an external program as an OS subprocess
     5831            of lisp.</refpurpose>
     5832            <refclass>Function</refclass>
     5833          </refnamediv>
     5834
     5835          <refsynopsisdiv>
     5836            <synopsis><function>run-program</function>
     5837            program args &key; (wait t) pty input
    38355838            if-input-does-not-exist output (if-output-exists :error) (error
    3836             :output) (if-error-exists :error) status-hook
    3837 </programlisting>
    3838         <bridgehead renderas="sect3">Arguments and Values</bridgehead>
    3839         <term><indexterm>program
    3840             <variablelist>A string or pathname which denotes an executable file.The PATH environment variable is used to find programs whosename doesn't contain a directory component.</variablelist>
    3841           </indexterm><indexterm>args
    3842             <variablelist>A list of simple-strings</variablelist>
    3843           </indexterm><indexterm>wait
    3844             <variablelist>Indicates whether or not run-program should wait forthe EXTERNAL-PROCESS to complete or should returnimmediately.</variablelist>
    3845           </indexterm><indexterm>pty
    3846             <variablelist>This option is accepted but currently ignored;it's intended to make it easier to run external programsthat need to interact with a terminal device.</variablelist>
    3847           </indexterm><indexterm>input
    3848             <variablelist>Selects the input source used by the EXTERNAL-PROCESS.May be any of the following:
    3849               <listitem mark="bullet">
    3850                 <variablelist>NIL Specifies that a null input stream (e.g.,/dev/null) should be used.</variablelist>
    3851                 <variablelist>T Specifies that the EXTERNAL-PROCESS should usethe input source with which OpenMCL was invoked.</variablelist>
    3852                 <variablelist>A string or pathname. Specifies that theEXTERNAL-PROCESS should receive its input from the namedexisting file.</variablelist>
    3853                 <variablelist>:STREAM Creates a Lisp stream opened fo