Ignore:
Timestamp:
Apr 1, 2008, 5:07:25 PM (12 years ago)
Author:
mikel
Message:

additions to ObjC and ffi docs; many mechanical edits; some standardization of XML elements and formatting

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/source/doc/src/threads.xml

    r8820 r8981  
    11<?xml version="1.0" encoding="utf-8"?>
    22<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
    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>">
    9 <!ENTITY CCL "Clozure CL">
    10 ]>
    11 
    12   <chapter id="Programming-with-Threads">
    13     <title>Programming with Threads</title>
    14 
    15     <sect1 id="Threads-overview">
    16       <title>Threads Overview</title>
    17 
    18       <para>&CCL; provides facilities which enable multiple threads
     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>">
     9          <!ENTITY CCL "Clozure CL">
     10          ]>
     11
     12<chapter id="Programming-with-Threads">
     13  <title>Programming with Threads</title>
     14
     15  <sect1 id="Threads-overview">
     16    <title>Threads Overview</title>
     17
     18    <para>&CCL; provides facilities which enable multiple threads
    1919      of execution (<emphasis>threads</emphasis>, sometimes called
    2020      <emphasis>lightweight processes</emphasis> or just
     
    2222      be confused with the OS's notion of a process) within a lisp
    2323      session. This document describes those facilities and issues
    24       related to multitheaded programming in &CCL;.</para>
    25 
    26       <para>Wherever possible, I'll try to use the term "thread" to
     24      related to multithreaded programming in &CCL;.</para>
     25
     26    <para>Wherever possible, I'll try to use the term "thread" to
    2727      denote a lisp thread, even though many of the functions in the
    2828      API have the word "process" in their name. A
     
    3232      distinction between these two (quite different) objects can be
    3333      blurred; other times, it's important to maintain.</para>
    34       <para>Lisp threads share the same address space, but maintain
     34    <para>Lisp threads share the same address space, but maintain
    3535      their own execution context (stacks and registers) and their own
    3636      dynamic binding context.</para>
    37      
    38       <para>Traditionally, &CCL;'s threads have been
     37   
     38    <para>Traditionally, &CCL;'s threads have been
    3939      <emphasis>cooperatively scheduled</emphasis>: through a
    40       combination of compiler and runtime suppport, the currently
    41       executing lisp thread arranged to be interrrupted at certain
     40      combination of compiler and runtime support, the currently
     41      executing lisp thread arranged to be interrupted at certain
    4242      discrete points in its execution (typically on entry to a
    4343      function and at the beginning of any looping construct). This
     
    4545      a handler function might observe that the current thread had
    4646      used up its time slice and another function (<emphasis>the lisp
    47       scheduler</emphasis>) would be called to find some other thread
     47        scheduler</emphasis>) would be called to find some other thread
    4848      that was in a runnable state, suspend execution of the current
    4949      thread, and resume execution of the newly executed thread.  The
     
    5353      thread running in the Lisp image and its stack pointer and other
    5454      registers just happened to change from time to time.</para>
    55       <para>Under &CCL;'s cooperative scheduling model, it was
     55    <para>Under &CCL;'s cooperative scheduling model, it was
    5656      possible (via the use of the CCL:WITHOUT-INTERRUPTS construct)
    5757      to defer handling of the periodic interrupt that invoked the
     
    6363      time.</para>
    6464
    65       <para>The timer interrupt that drove the cooperative scheduler
     65    <para>The timer interrupt that drove the cooperative scheduler
    6666      was only able to (pseudo-)preempt lisp code: if any thread
    6767      called a blocking OS I/O function, no other thread could be
     
    7474      was "doing nothing" (waiting for I/O to be possible.)</para>
    7575
    76       <para>For a variety of reasons - better utilization of CPU
     76    <para>For a variety of reasons - better utilization of CPU
    7777      resources on single and multiprocessor systems and better
    7878      integration with the OS in general - threads in &CCL; 0.14 and
     
    8484      change has a number of subtle effects:</para>
    8585
    86       <itemizedlist>
    87         <listitem>
    88           <para>it is possible for two (or more) lisp threads to be
    89           executingsimultaneously, possibly trying to access and/or
    90           modify the same datastructures. Such access really should
    91           have been coordinated throughthe use of synchronization
    92           objects regardless of the scheduling modelin effect;
    93           preemptively scheduled threads increase the chance ofthings
    94           going wrong at the wrong time and do not offer
    95           lightweightalternatives to the use of those synchronization
    96           objects.</para>
    97         </listitem>
    98         <listitem>
    99           <para>even on a single-processor system, a context switch
    100           can happenon any instruction boundary. Since (in general)
    101           other threads mightallocate memory, this means that a GC can
    102           effectively take place atany instruction boundary. That's
    103           mostly an issue for the compilerand runtime system to be
    104           aware of, but it means that certain practices(such as trying
    105           to pass the address of a lisp object to foreign code)that
    106           were always discouraged are now discouraged
    107           ... vehemently.</para>
    108         </listitem>
    109         <listitem>
    110           <para>there is no simple and efficient way to "inhibit the
    111           scheduler"or otherwise gain exclusive access to the entire
    112           CPU.</para>
    113         </listitem>
    114         <listitem>
    115           <para>There are a variety of simple and efficient ways
    116           tosynchronize access to particular data
    117           structures.</para>
    118         </listitem>
    119       </itemizedlist>
    120       <para>As a broad generalization: code that's been aggressively
     86    <itemizedlist>
     87      <listitem>
     88            <para>it is possible for two (or more) lisp threads to be
     89              executing simultaneously, possibly trying to access and/or
     90              modify the same data structures. Such access really should
     91              have been coordinated through the use of synchronization
     92              objects regardless of the scheduling modeling effect;
     93              preemptively scheduled threads increase the chance of things
     94              going wrong at the wrong time and do not offer
     95              lightweight alternatives to the use of those synchronization
     96              objects.</para>
     97          </listitem>
     98      <listitem>
     99            <para>even on a single-processor system, a context switch
     100              can happen on any instruction boundary. Since (in general)
     101              other threads might allocate memory, this means that a GC can
     102              effectively take place at any instruction boundary. That's
     103              mostly an issue for the compiler and runtime system to be
     104              aware of, but it means that certain practices(such as trying
     105              to pass the address of a lisp object to foreign code)that
     106              were always discouraged are now discouraged
     107              ... vehemently.</para>
     108          </listitem>
     109      <listitem>
     110            <para>there is no simple and efficient way to "inhibit the
     111              scheduler"or otherwise gain exclusive access to the entire
     112              CPU.</para>
     113          </listitem>
     114      <listitem>
     115            <para>There are a variety of simple and efficient ways
     116              to synchronize access to particular data
     117              structures.</para>
     118          </listitem>
     119    </itemizedlist>
     120    <para>As a broad generalization: code that's been aggressively
    121121      tuned to the constraints of the cooperative scheduler may need
    122122      to be redesigned to work well with the preemptive scheduler (and
     
    129129      that's largely independent of the underlying scheduling
    130130      details.</para>
    131       <para>The keyword :OPENMCL-NATIVE-THREADS is on *FEATURES* in
     131    <para>The keyword :OPENMCL-NATIVE-THREADS is on *FEATURES* in
    132132      0.14 and later and can be used for conditionalization where
    133133      required.</para>
    134     </sect1>
    135 
    136     <sect1 id="Intentionally--Missing-Functionality">
    137       <title>(Intentionally) Missing Functionality</title>
    138       <para>Much of the functionality described above is similar to
     134  </sect1>
     135
     136  <sect1 id="Intentionally--Missing-Functionality">
     137    <title>(Intentionally) Missing Functionality</title>
     138    <para>Much of the functionality described above is similar to
    139139      that provided by &CCL;'s cooperative scheduler, some other
    140140      parts of which make no sense in a native threads
    141141      implementation.</para>
     142    <itemizedlist>
     143      <listitem>
     144            <para>PROCESS-RUN-REASONS and PROCESS-ARREST-REASONS were
     145              SETFable process attributes; each was just a list of
     146              arbitrary tokens. A thread was eligible for scheduling
     147              (roughly equivalent to being "enabled") if its arrest-reasons
     148              list was empty and its run-reasons list was not. I don't
     149              think that it's appropriate to encourage a programming style
     150              in which otherwise runnable threads are enabled and disabled
     151              on a regular basis (it's preferable for threads to wait for
     152              some sort of synchronization event to occur if they can't
     153              occupy their time productively.)</para>
     154          </listitem>
     155      <listitem>
     156            <para>There were a number of primitives for maintaining
     157              process queues;that's now the OS's job.</para>
     158          </listitem>
     159      <listitem>
     160            <para>Cooperative threads were based on coroutining
     161              primitives associated with objects of type
     162              STACK-GROUP. STACK-GROUPs no longerexist.</para>
     163          </listitem>
     164    </itemizedlist>
     165  </sect1>
     166
     167
     168  <sect1 id="Implementation-Decisions-and-Open-Questions">
     169    <title>Implementation Decisions and Open Questions</title>
     170    <sect2>
     171      <title>Thread Stack Sizes</title>
     172      <para>When you use MAKE-PROCESS to create a thread, you can
     173        specify a stack size. &CCL; does not impose a limit on the stack
     174        size you choose, but there is some evidence that choosing a
     175        stack size larger than the operating system's limit can cause
     176        excessive paging activity, at least on some operating
     177        systems.</para>
     178      <para>The maximum stack size is operating-system-dependent. You
     179        can use shell commands to determine what it is on your
     180        platform. In bash, use "ulimit -s -H" to find the limit; in
     181        tcsh, use "limit -h s".</para>
     182      <para>This issue does not affect programs that create threads
     183        using the default stack size, which you can do either by
     184        specifying no value for the :stack-size argument to
     185        MAKE-PROCESS, or by specifying the value
     186        CCL::*default-control-stack-size*.</para>
     187      <para>If your program creates threads with a specified stack size,
     188        and that size is larger than the OS-specified limit, you may want
     189        to consider reducing the stack size in order to avoid possible
     190        excessive paging activity.</para>
     191    </sect2>
     192    <sect2>
     193      <title> As of August 2003:</title>
    142194      <itemizedlist>
    143195        <listitem>
    144           <para>PROCESS-RUN-REASONS and PROCESS-ARREST-REASONS were
    145           SETFable process attributes; each was just a list of
    146           arbitrary tokens. A thread was eligible for scheduling
    147           (roughly equivalent to being "enabled") if its arrest-reasons
    148           list was empty and its run-reasons list was not. I don't
    149           think that it's appropriate to encourage a programming style
    150           in which otherwise runnable threads are enabled and disabled
    151           on a regular basis (it's preferable for threads to wait for
    152           some sort of synchronization event to occur if they can't
    153           occupy their time productively.)</para>
    154         </listitem>
     196              <para>It's not clear that exposing
     197                PROCESS-SUSPEND/PROCESS-RESUME is a good idea: it's not clear
     198                that they offer ways to win, and it's clear that they offer
     199                ways to lose.</para>
     200            </listitem>
    155201        <listitem>
    156           <para>There were a number of primitives for maintaining
    157           process queues;that's now the OS's job.</para>
    158         </listitem>
     202              <para>It has traditionally been possible to reset and enable
     203                a process that's "exhausted" . (As used here, the
     204                term"exhausted" means that the process's initial function
     205                has run and returned and the underlying native thread has
     206                been deallocated.) One of the principle uses of PROCESS-RESET
     207                is to "recycle" threads; enabling an exhausted process
     208                involves creating a new native thread (and stacks and
     209                synchronization objects and ...),and this is the sort of
     210                overhead that such a recycling scheme is seeking to avoid. It
     211                might be worth trying to tighten things up and declare that
     212                it's an error to apply PROCESS-ENABLE to an exhausted thread
     213                (and to make PROCESS-ENABLE detect this error.)</para>
     214            </listitem>
    159215        <listitem>
    160           <para>Cooperative threads were based on coroutining
    161           primitivesassociated with objects of type
    162           STACK-GROUP. STACK-GROUPs no longerexist.</para>
    163         </listitem>
     216              <para>When native threads that aren't created by &CCL;
     217                first call into lisp, a "foreign process" is created, and
     218                that process is given its own set of initial bindings and set
     219                up to look mostly like a process that had been created by
     220                MAKE-PROCESS. The life cycle of a foreign process is
     221                certainly different from that of a lisp-created one: it
     222                doesn't make sense to reset/preset/enable a foreign process,
     223                and attempts to perform these operations should be
     224                detected and treated as errors.</para>
     225            </listitem>
    164226      </itemizedlist>
    165     </sect1>
    166 
    167 
    168 <sect1 id="Implementation-Decisions-and-Open-Questions">
    169   <title>Implementation Decisions and Open Questions</title>
    170   <sect2>
    171     <title>Thread Stack Sizes</title>
    172     <para>When you use MAKE-PROCESS to create a thread, you can
    173       specify a stack size. &CCL; does not impose a limit on the stack
    174       size you choose, but there is some evidence that choosing a
    175       stack size larger than the operating system's limit can cause
    176       excessive paging activity, at least on some operating
    177       systems.</para>
    178     <para>The maximum stack size is operating-system-dependent. You
    179       can use shell commands to determine what it is on your
    180       platform. In bash, use "ulimit -s -H" to find the limit; in
    181       tcsh, use "limit -h s".</para>
    182     <para>This issue does not affect programs that create threads
    183       using the default stack size, which you can do either by
    184       specifying no value for the :stack-size argument to
    185       MAKE-PROCESS, or by specifying the value
    186       CCL::*default-control-stack-size*.</para>
    187     <para>If your program creates threads with a specified stack size,
    188     and that size is larger than the OS-specified limit, you may want
    189     to consider reducing the stack size in order to avoid possible
    190     excessive paging activity.</para>
    191   </sect2>
    192   <sect2>
    193     <title> As of August 2003:</title>
    194     <itemizedlist>
    195       <listitem>
    196             <para>It's not clear that exposing
    197               PROCESS-SUSPEND/PROCESS-RESUME is a good idea: it's not clear
    198               that they offer ways to win, and it's clear that they offer
    199               ways to lose.</para>
    200           </listitem>
    201       <listitem>
    202             <para>It has traditionally been possible to reset and enable
    203               a process that's "exhausted" . (As used here, the
    204               term"exhausted" means that the process's initial function
    205               hasrun and returned and the underlying native thread has
    206               beendeallocated.) One of the principle uses of PROCESS-RESET
    207               is to "recycle" threads; enabling an exhausted process
    208               involves creating a new native thread (and stacks and
    209               synchronization objects and ...),and this is the sort of
    210               overhead that such a recycling scheme is seeking to avoid. It
    211               might be worth trying to tighten things up and declare that
    212               it's an error to apply PROCESS-ENABLE to an exhausted thread
    213               (and to make PROCESS-ENABLE detect this error.)</para>
    214           </listitem>
    215       <listitem>
    216             <para>When native threads that aren't created by &CCL;
    217               first call into lisp, a "foreign process" is created, and
    218               that process is given its own set of initial bindings and set
    219               up to look mostly like a process that had been created by
    220               MAKE-PROCESS. The life cycle of a foreign process is
    221               certainly different from that of a lisp-created one: it
    222               doesn't make sense to reset/preset/enable a foreign process,
    223               and attempts to perform these operations should be
    224               detectedand treated as errors.</para>
    225           </listitem>
    226     </itemizedlist>
    227   </sect2>
    228 </sect1>
    229 
    230 
    231 
    232     <sect1 id="Porting-Code-from-the-Old-Thread-Model">
    233       <title>Porting Code from the Old Thread Model</title>
    234       <para>Older versions of &CCL; used what are often called
     227    </sect2>
     228  </sect1>
     229
     230
     231
     232  <sect1 id="Porting-Code-from-the-Old-Thread-Model">
     233    <title>Porting Code from the Old Thread Model</title>
     234    <para>Older versions of &CCL; used what are often called
    235235      "user-mode threads", a less versatile threading model which does
    236236      not require specific support from the operating system.  This
    237237      section discusses how to port code which was written for that
    238238      mode.</para>
    239       <para>It's hard to give step-by-step instructions; there are certainly
     239    <para>It's hard to give step-by-step instructions; there are certainly
    240240      a few things that one should look at carefully:</para>
    241       <itemizedlist>
    242         <listitem>
    243           <para>It's wise to be suspicious of most uses
    244           of WITHOUT-INTERRUPTS; there may be exceptions, but
    245           WITHOUT-INTERRUPTS is often used as shorthand for
    246           WITH-APPROPRIATE-LOCKING. Determining what type of locking
    247           is appropriate and writing the code to implement it is
    248           likely to be straightforward and simple most of the
    249           time.</para>
    250         </listitem>
    251         <listitem>
    252           <para>I've only seen one case where a process's "run reasons"
    253           were used to communicate information as well as tocontrol
    254           execution; I don't think that this is a common idiom, but may
    255           be mistaken about that.
    256           </para>
    257         </listitem>
    258         <listitem>
    259           <para>It's certainly possible that programs written
    260           for cooperatively scheduled lisps that have run reliably for
    261           a long timehave done so by accident: resource-contention
    262           issues tend to be timing-sensitive, and decoupling thread
    263           scheduling from lisp program execution affects timing. I know
    264           that there is or was code in both &CCL; and commercial MCL
    265           that was written under the explicit assumption that certain
    266           sequences of open-coded operations were uninterruptable; it's
    267           certainly possible that the same assumptions have been made
    268           (explicitly or otherwise) by application developers.</para>
    269         </listitem>
    270       </itemizedlist>
    271     </sect1>
    272 
    273     <sect1 id="Background-Terminal-Input">
    274       <title>Background Terminal Input</title>
    275 
    276       <sect2 id="backgrount-ti-overview">
    277         <title>Overview</title>
    278         <para>
    279           Unless and until &CCL; provides alternatives (via window
    280           streams, telnet streams, or some other mechanism) all lisp
    281           processes share a common *TERMINAL-IO* stream (and therefore
    282           share *DEBUG-IO*, *QUERY-IO*, and other standard and
    283           internal interactive streams.)</para>
     241    <itemizedlist>
     242      <listitem>
     243            <para>It's wise to be suspicious of most uses
     244              of WITHOUT-INTERRUPTS; there may be exceptions, but
     245              WITHOUT-INTERRUPTS is often used as shorthand for
     246              WITH-APPROPRIATE-LOCKING. Determining what type of locking
     247              is appropriate and writing the code to implement it is
     248              likely to be straightforward and simple most of the
     249              time.</para>
     250          </listitem>
     251      <listitem>
     252            <para>I've only seen one case where a process's "run reasons"
     253              were used to communicate information as well as to control
     254              execution; I don't think that this is a common idiom, but may
     255              be mistaken about that.
     256            </para>
     257          </listitem>
     258      <listitem>
     259            <para>It's certainly possible that programs written
     260              for cooperatively scheduled lisps that have run reliably for
     261              a long time have done so by accident: resource-contention
     262              issues tend to be timing-sensitive, and decoupling thread
     263              scheduling from lisp program execution affects timing. I know
     264              that there is or was code in both &CCL; and commercial MCL
     265              that was written under the explicit assumption that certain
     266              sequences of open-coded operations were uninterruptable; it's
     267              certainly possible that the same assumptions have been made
     268              (explicitly or otherwise) by application developers.</para>
     269          </listitem>
     270    </itemizedlist>
     271  </sect1>
     272
     273  <sect1 id="Background-Terminal-Input">
     274    <title>Background Terminal Input</title>
     275
     276    <sect2 id="backgrount-ti-overview">
     277      <title>Overview</title>
     278          <para>
     279            Unless and until &CCL; provides alternatives (via window
     280            streams, telnet streams, or some other mechanism) all lisp
     281            processes share a common *TERMINAL-IO* stream (and therefore
     282            share *DEBUG-IO*, *QUERY-IO*, and other standard and
     283            internal interactive streams.)</para>
    284284          <para>It's anticipated that most lisp processes other than
    285           the "Initial" process run mostly in the background. If a
    286           background process writes to the output side of
    287           *TERMINAL-IO*, that may be a little messy and a little
    288           confusing to the user, but it shouldn't really be
    289           catastrophic. All I/O to &CCL;'s buffered streams goes
    290           thru a locking mechanism that prevents the worst kinds of
    291           resource-contention problems.</para>
     285            the "Initial" process run mostly in the background. If a
     286            background process writes to the output side of
     287            *TERMINAL-IO*, that may be a little messy and a little
     288            confusing to the user, but it shouldn't really be
     289            catastrophic. All I/O to &CCL;'s buffered streams goes
     290            thru a locking mechanism that prevents the worst kinds of
     291            resource-contention problems.</para>
    292292          <para>Although the problems associated with terminal output
    293           from multiple processes may be mostly cosmetic, the question
    294           of which process receives input from the terminal is likely
    295           to be a great deal more important. The stream locking
    296           mechanisms can make a confusing situation even worse:
    297           competing processes may "steal" terminal input from each
    298           other unless locks are held longer than they otherwise need
    299           to be, and locks can be held longer than they need to be (as
    300           when a process is merely waiting for input to become
    301           available on an underlying file descriptor).</para>
     293            from multiple processes may be mostly cosmetic, the question
     294            of which process receives input from the terminal is likely
     295            to be a great deal more important. The stream locking
     296            mechanisms can make a confusing situation even worse:
     297            competing processes may "steal" terminal input from each
     298            other unless locks are held longer than they otherwise need
     299            to be, and locks can be held longer than they need to be (as
     300            when a process is merely waiting for input to become
     301            available on an underlying file descriptor).</para>
    302302          <para>Even if background processes rarely need to
    303           intentionally read input from the terminal, they may still
    304           need to do so in response to errors or other unanticipated
    305           situations. There are tradeoffs involved in any solution to
    306           this problem. The protocol described below allows background
    307           processes which follow it to reliably prompt for and receive
    308           terminal input. Background processes which attempt to
    309           receive terminal input without following this protocol will
    310           likely hang indefinitely while attempting to do so. That's
    311           certainly a harsh tradeoff, but since attempts to read
    312           terminal input without following this protocol only worked
    313           some of the time anyway, it doesn't seem to be an
    314           unreasonable one.</para>
     303            intentionally read input from the terminal, they may still
     304            need to do so in response to errors or other unanticipated
     305            situations. There are tradeoffs involved in any solution to
     306            this problem. The protocol described below allows background
     307            processes which follow it to reliably prompt for and receive
     308            terminal input. Background processes which attempt to
     309            receive terminal input without following this protocol will
     310            likely hang indefinitely while attempting to do so. That's
     311            certainly a harsh tradeoff, but since attempts to read
     312            terminal input without following this protocol only worked
     313            some of the time anyway, it doesn't seem to be an
     314            unreasonable one.</para>
    315315          <para>In the solution described here (and introduced in
    316           &CCL; 0.9), the internal stream used to provide terminal
    317           input is always locked by some process (the "owning"
    318           process.) The initial process (the process that typically
    319           runs the read-eval-print loop) owns that stream when it's
    320           first created. By using the macro WITH-TERMINAL-INPUT,
    321           background processes can temporarily obtain ownership of the
    322           terminal and relinquish ownership to the previous owner when
    323           they're done with it.</para>
     316            &CCL; 0.9), the internal stream used to provide terminal
     317            input is always locked by some process (the "owning"
     318            process.) The initial process (the process that typically
     319            runs the read-eval-print loop) owns that stream when it's
     320            first created. By using the macro WITH-TERMINAL-INPUT,
     321            background processes can temporarily obtain ownership of the
     322            terminal and relinquish ownership to the previous owner when
     323            they're done with it.</para>
    324324          <para>In &CCL;, BREAK, ERROR, CERROR, Y-OR-N-P,
    325           YES-OR-NO-P, and CCL:GET-STRING- FROM-USER are all defined
    326           in terms of WITH-TERMINAL-INPUT, as are the :TTY
    327           user-interfaces to STEP and INSPECT.</para>
    328       </sect2>
    329 
    330       <sect2 id="background-terminal-example">
    331         <title>An example</title>
    332         <programlisting>
     325            YES-OR-NO-P, and CCL:GET-STRING- FROM-USER are all defined
     326            in terms of WITH-TERMINAL-INPUT, as are the :TTY
     327            user-interfaces to STEP and INSPECT.</para>
     328    </sect2>
     329
     330    <sect2 id="background-terminal-example">
     331      <title>An example</title>
     332
     333      <programlisting>
    333334? Welcome to &CCL; Version (Beta: linux) 0.9!
    334335?
     
    341342;; Process sleeper(1) needs access to terminal input.
    342343;;
    343 </programlisting>
    344         <para>This example was run under ILISP; ILISP often gets confused if one
    345         tries to enter input and "point" doesn't follow a prompt.
    346         Entering a "simple" expression at this point gets it back in
    347         synch; that's otherwise not relevant to this example.</para>
    348         <programlisting>
     344      </programlisting>
     345
     346      <para>This example was run under ILISP; ILISP often gets confused if one
     347            tries to enter input and "point" doesn't follow a prompt.
     348            Entering a "simple" expression at this point gets it back in
     349            synch; that's otherwise not relevant to this example.</para>
     350
     351          <programlisting>
    349352()
    350353NIL
     
    368371;;
    369372?
    370 </programlisting>
    371       </sect2>
    372 
    373       <sect2 id="A-more-elaborate-example-">
    374         <title>A more elaborate example.</title>
    375         <para>If a background process ("A") needs access to the terminal
    376         input stream and that stream is owned by another background process
    377         ("B"), process "A" announces that fact, then waits until
    378         the initial process regains control.</para>
    379         <programlisting>
     373      </programlisting>
     374    </sect2>
     375
     376    <sect2 id="A-more-elaborate-example-">
     377      <title>A more elaborate example.</title>
     378          <para>If a background process ("A") needs access to the terminal
     379            input stream and that stream is owned by another background process
     380            ("B"), process "A" announces that fact, then waits until
     381            the initial process regains control.</para>
     382
     383          <programlisting>
    380384? Welcome to &CCL; Version (Beta: linux) 0.9!
    381385?
     
    387391#&lt;PROCESS sleep-5(2) [Enabled] #x3063D0A6&gt;
    388392
    389 ? ;;
     393?       ;;
    390394;; Process sleep-5(2) needs access to terminal input.
    391395;;
     
    402406> If continued: Return from BREAK.
    403407Type :? for other options.
    404 1 > ;; Process sleep-60(1) will need terminal access when
     4081 >     ;; Process sleep-60(1) will need terminal access when
    405409;; the initial process regains control of it.
    406410;;
     
    430434
    431435?
    432 </programlisting>
    433       </sect2>
    434 
    435       <sect2 id="Summary">
    436         <title>Summary</title>
    437         <para>This scheme is certainly not bulletproof: imaginative
    438         use of PROCESS-INTERRUPT and similar functions might be able
    439         to defeat it and deadlock the lisp, and any scenario where
    440         several background processes are clamoring for access to the
    441         shared terminal input stream at the same time is likely to be
    442         confusing and chaotic. (An alternate scheme, where the input
    443         focus was magically granted to whatever thread the user was
    444         thinking about, was considered and rejected due to technical
    445         limitations.)</para>
    446         <para>The longer-term fix would probably involve using network or
    447         window-system streams to give each process unique instances of
    448         *TERMINAL-IO*.</para>
    449         <para>Existing code that attempts to read from *TERMINAL-IO*
     436      </programlisting>
     437
     438    </sect2>
     439
     440    <sect2 id="Summary">
     441          <title>Summary</title>
     442          <para>This scheme is certainly not bulletproof: imaginative
     443            use of PROCESS-INTERRUPT and similar functions might be able
     444            to defeat it and deadlock the lisp, and any scenario where
     445            several background processes are clamoring for access to the
     446            shared terminal input stream at the same time is likely to be
     447            confusing and chaotic. (An alternate scheme, where the input
     448            focus was magically granted to whatever thread the user was
     449            thinking about, was considered and rejected due to technical
     450            limitations.)</para>
     451          <para>The longer-term fix would probably involve using network or
     452            window-system streams to give each process unique instances of
     453            *TERMINAL-IO*.</para>
     454      <para>Existing code that attempts to read from *TERMINAL-IO*
    450455        from a background process will need to be changed to use
    451456        WITH-TERMINAL-INPUT.  Since that code was probably not working
    452457        reliably in previous versions of &CCL;, this requirement
    453458        doesn't seem to be too onerous.</para>
    454         <para>Note that WITH-TERMINAL-INPUT both requests ownership of
     459      <para>Note that WITH-TERMINAL-INPUT both requests ownership of
    455460        the terminal input stream and promises to restore that
    456461        ownership to the initial process when it's done with it. An ad
    457462        hoc use of READ or READ-CHAR doesn't make this promise; this
    458463        is the rationale for the restriction on the :Y command.</para>
    459       </sect2>
    460     </sect1>
    461 
    462     <sect1 id="The-Threads-which-CCL-Uses-for-Its-Own-Purposes">
    463       <title>The Threads which &CCL; Uses for Its Own Purposes</title>
    464       <para>
    465 In the "tty world", &CCL; starts out with 2 lisp-level threads:</para>
    466       <programlisting>
     464    </sect2>
     465  </sect1>
     466
     467  <sect1 id="The-Threads-which-CCL-Uses-for-Its-Own-Purposes">
     468    <title>The Threads which &CCL; Uses for Its Own Purposes</title>
     469    <para>
     470      In the "tty world", &CCL; starts out with 2 lisp-level threads:</para>
     471
     472    <programlisting>
    467473? :proc
    4684741 : -> listener     [Active]
    4694750 :    Initial      [Active]
    470 </programlisting>
    471       <para>If you look at a running &CCL; with a debugging tool,
     476    </programlisting>
     477
     478    <para>If you look at a running &CCL; with a debugging tool,
    472479      such as GDB, or Apple's Thread Viewer.app, you'll see an
    473480      additional kernel-level thread on Darwin; this is used by the
    474481      Mach exception-handling mechanism.</para>
    475       <para>The initial thread, conveniently named "initial", is the
     482    <para>The initial thread, conveniently named "initial", is the
    476483      one that was created by the operating system when it launched
    477484      &CCL;.  It maps the heap image into memory, does some
     
    480487      loop that reads input, evaluates it, and prints the
    481488      result.</para>
    482       <para>After the listener thread is created, the initial thread
     489    <para>After the listener thread is created, the initial thread
    483490      does "housekeeping": it sits in a loop, sleeping most of the
    484491      time and waking up occasionally to do "periodic tasks".  These
     
    488495      processes and handling some kinds of I/O to and from those
    489496      processes.</para>
    490       <para>In this environment, the initial thread does these
     497    <para>In this environment, the initial thread does these
    491498      "housekeeping" activities as necessary, until
    492499      <literal>ccl:quit</literal> is called;
     
    494501      then ends all other threads in as orderly a fashion as possible
    495502      and calls the C function <literal>#_exit</literal>.</para>
    496       <para>The short-term plan is to handle each external-process in
     503    <para>The short-term plan is to handle each external-process in
    497504      a dedicated thread; the worst-case behavior of the current
    498505      scheme can involve busy-waiting and excessive CPU utilization
    499506      while waiting for an external process to terminate in some
    500507      cases.</para>
    501       <para>The Cocoa features use more threads.  Adding a Cocoa
     508    <para>The Cocoa features use more threads.  Adding a Cocoa
    502509      listener creates two threads:</para>
    503       <programlisting>
    504 ? :proc
    505 3 : -> Listener     [Active]
    506 2 :    housekeeping  [Active]
    507 1 :    listener     [Active]
    508 0 :    Initial      [Active]
    509       </programlisting>
    510       <para>The Cocoa event loop has to run in the initial thread;
     510
     511    <programlisting>
     512      ? :proc
     513      3 : -> Listener     [Active]
     514      2 :    housekeeping  [Active]
     515      1 :    listener     [Active]
     516      0 :    Initial      [Active]
     517    </programlisting>
     518
     519    <para>The Cocoa event loop has to run in the initial thread;
    511520      when the event loop starts up, it creates a new thread to do the
    512521      "housekeeping" tasks which the initial thread would do in the
     
    514523      receive all Cocoa events from the window server; it's the only
    515524      thread which can.</para>
    516       <para>It also creates one "Listener" (capital-L) thread for each
     525    <para>It also creates one "Listener" (capital-L) thread for each
    517526      listener window, with a lifetime that lasts as long as the
    518527      thread does.  So, if you open a second listener, you'll see five
    519528      threads all together:</para>
    520       <programlisting>
    521 ? :proc
    522 4 : -> Listener-2   [Active]
    523 3 :    Listener     [Active]
    524 2 :    housekeeping  [Active]
    525 1 :    listener     [Active]
    526 0 :    Initial      [Active]
    527 </programlisting>
    528       <para>Unix signals, such as SIGINT (control-C), invoke a handler
     529
     530    <programlisting>
     531      ? :proc
     532      4 : -> Listener-2   [Active]
     533      3 :    Listener     [Active]
     534      2 :    housekeeping  [Active]
     535      1 :    listener     [Active]
     536      0 :    Initial      [Active]
     537    </programlisting>
     538
     539    <para>Unix signals, such as SIGINT (control-C), invoke a handler
    529540      installed by the Lisp kernel.  Although the OS doesn't make any
    530541      specific guarantee about which thread will receive the signal,
     
    534545      the flag and take whatever action is appropriate to the
    535546      signal.</para>
    536       <para>In the case of SIGINT, the action is to enter a break
     547    <para>In the case of SIGINT, the action is to enter a break
    537548      loop, by calling on the thread being interrupted.  When there's
    538549      more than one Lisp listener active, it's not always clear what
     
    544555      thread which currently "owns" the default terminal input stream;
    545556      see .</para>
    546       <para>In the bleeding-edge version of the Cocoa support which is
     557    <para>In the bleeding-edge version of the Cocoa support which is
    547558      based on Hemlock, an Emacs-like editor, each editor window has a
    548559      dedicated thread associated with it.  When a keypress event
     
    554565      thread handles all other events, such as mouse clicks and
    555566      drags.</para>
    556       <para>This thread-per-window scheme makes many things simpler,
     567    <para>This thread-per-window scheme makes many things simpler,
    557568      including the process of entering a "recursive command loop" in
    558569      commands like "Incremental Search Forward", etc.  (It might be
     
    561572      maintain a lot of context/state information; threads are a
    562573      straightforward way of maintaining that information.)</para>
    563       <para>Currently (August 2004), when a dedicated thread needs to
     574    <para>Currently (August 2004), when a dedicated thread needs to
    564575      alter the contents of the buffer or the selection, it does so by
    565576      invoking methods in the initial thread, for synchronization
    566577      purposes, but this is probably overkill and will likely be
    567578      replaced by a more efficient scheme in the future.</para>
    568       <para>The per-window thread could probably take more
     579    <para>The per-window thread could probably take more
    569580      responsibility for drawing and handling the screen than it
    570581      currently does; -something- needs to be done to buffer screen
     
    572583      everything that happens during something like indentation; you
    573584      do need to see the results...</para>
    574       <para>When Hemlock is being used, listener windows are editor
     585    <para>When Hemlock is being used, listener windows are editor
    575586      windows, so in addition to each "Listener" thread, you should
    576587      also see a thread which handles Hemlock command
    577588      processing.</para>
    578       <para>The Cocoa runtime may make additional threads in certain
     589    <para>The Cocoa runtime may make additional threads in certain
    579590      special situations; these threads usually don't run lisp code,
    580591      and rarely if ever run much of it.</para>
    581     </sect1>
    582 
    583     <sect1 id="Threads-Dictionary">
    584       <title>Threads Dictionary</title>
    585       <refentry id="f_all-processes">
    586         <indexterm zone="f_all-processes">
    587           <primary>all-processes</primary>
    588         </indexterm>
    589 
    590         <refnamediv>
    591           <refname>ALL-PROCESSES</refname>
    592           <refpurpose>Obtain a fresh list of all known Lisp
    593           threads.</refpurpose>
    594           <refclass>Function</refclass>
    595         </refnamediv>
    596 
    597         <refsynopsisdiv>
    598           <synopsis>
    599             <function>all-processes</function> => result
    600           </synopsis>
    601         </refsynopsisdiv>
    602 
    603         <refsect1>
    604           <title>Values</title>
     592  </sect1>
     593
     594  <sect1 id="Threads-Dictionary">
     595    <title>Threads Dictionary</title>
     596    <refentry id="f_all-processes">
     597          <indexterm zone="f_all-processes">
     598            <primary>all-processes</primary>
     599          </indexterm>
     600
     601          <refnamediv>
     602            <refname>ALL-PROCESSES</refname>
     603            <refpurpose>Obtain a fresh list of all known Lisp
     604              threads.</refpurpose>
     605            <refclass>Function</refclass>
     606          </refnamediv>
     607
     608          <refsynopsisdiv>
     609            <synopsis>
     610              <function>all-processes</function> => result
     611            </synopsis>
     612          </refsynopsisdiv>
     613
     614          <refsect1>
     615            <title>Values</title>
     616           
     617            <variablelist>
     618              <varlistentry>
     619                <term>result</term>
     620                <listitem>
     621                      <para>a list of all lisp processes (threads)
     622                        known to &CCL;.</para>
     623                </listitem>
     624              </varlistentry>
     625            </variablelist>
     626          </refsect1>
     627          <refsect1>
     628            <title>Description</title>
     629
     630            <para>Returns a list of all lisp processes (threads) known
     631              to &CCL; as of
     632              the precise instant it&#39;s called. It&#39;s safe to traverse
     633              this list and to modify the cons cells that comprise that list
     634              (it&#39;s freshly consed.) Since other threads can create and kill
     635              threads at any time, there&#39;s generally no way to get an
     636              &#34;accurate&#34; list of all threads, and (generally) no
     637              sense in which such a list can be accurate.</para>
     638          </refsect1>
     639
     640          <refsect1>
     641            <title>See Also</title>
     642           
     643            <simplelist type="inline">
     644              <member><xref linkend="v_current-process"/></member>
     645            </simplelist>
     646          </refsect1>
     647    </refentry>
     648
     649    <refentry id="f_make-process">
     650          <indexterm zone="f_make-process">
     651            <primary>make-process</primary>
     652          </indexterm>
     653
     654          <refnamediv>
     655            <refname>MAKE-PROCESS</refname>
     656            <refpurpose>Creates and returns a new process.</refpurpose>
     657            <refclass>Function</refclass>
     658          </refnamediv>
     659
     660          <refsynopsisdiv>
     661            <synopsis>
     662              <function>make-process</function>
     663              name &amp;key
     664              persistent priority class stack-size vstack-size
     665              tstack-size initial-bindings use-standard-initial-bindings
     666              => process
     667            </synopsis>
     668          </refsynopsisdiv>
     669
     670          <refsect1>
     671            <title>Arguments and Values</title>
     672           
     673            <variablelist>
     674              <varlistentry>
     675                <term>name</term>
     676               
     677                <listitem>
     678                      <para>a string, used to identify the process.</para>
     679                </listitem>
     680              </varlistentry>
     681             
     682              <varlistentry>
     683                <term>persistent</term>
     684               
     685                <listitem>
     686                      <para>if true, requests that information about the process
     687                        be retained by SAVE-APPLICATION so that an equivalent
     688                        process can be restarted when a saved image is run.  The
     689                        default is nil.</para>
     690                </listitem>
     691              </varlistentry>
     692             
     693              <varlistentry>
     694                <term>priority</term>
     695               
     696                <listitem>
     697                      <para>ignored.  It
     698                        shouldn't be ignored of course, but there are
     699                        complications on some platforms.  The default is 0.</para>
     700                </listitem>
     701              </varlistentry>
     702             
     703              <varlistentry>
     704                <term>class</term>
     705               
     706                <listitem>
     707                      <para>the class of process object to create;
     708                        should be a subclass of CCL:PROCESS.  The default is
     709                        CCL:PROCESS.</para>
     710                </listitem>
     711              </varlistentry>
     712             
     713              <varlistentry>
     714                <term>stack-size</term>
     715               
     716                <listitem>
     717                      <para>the size, in bytes, of the newly-created process's
     718                        control stack; used for foreign function calls and to save
     719                        function return address context.  The default is
     720                        CCL:*DEFAULT-CONTROL-STACK-SIZE*.</para>
     721                </listitem>
     722              </varlistentry>
     723             
     724              <varlistentry>
     725                <term>vstack-size</term>
     726               
     727                <listitem>
     728                      <para>the size, in bytes, of the newly-created process's
     729                        value stack; used for lisp function arguments, local
     730                        variables, and other stack-allocated lisp objects.
     731                        The default is CCL:*DEFAULT-VALUE-STACK-SIZE*.</para>
     732                </listitem>
     733              </varlistentry>
     734             
     735              <varlistentry>
     736                <term>tstack-size</term>
     737               
     738                <listitem>
     739                      <para>the size, in bytes, of the newly-created process's
     740                        temp stack; used for the allocation of dynamic-extent
     741                        objects.  The default is CCL:*DEFAULT-TEMP-STACK-SIZE*.</para>
     742                </listitem>
     743              </varlistentry>
     744             
     745              <varlistentry>
     746                <term>use-standard-initial-bindings</term>
     747               
     748                <listitem>
     749                      <para>when true, the global "standard initial
     750                        bindings" are put into effect in the new thread before. See
     751                        DEF-STANDARD-INITIAL-BINDING.  "standard" initial bindings
     752                        are put into effect before any bindings specified by
     753                        :initial-bindings are.  The default is t.</para>
     754                </listitem>
     755              </varlistentry>
     756             
     757              <varlistentry>
     758                <term>initial-bindings</term>
     759               
     760                <listitem>
     761                      <para>an alist of (<varname>symbol</varname> .
     762                        <varname>valueform</varname>) pairs, which can be
     763                        used to initialize special variable bindings in the new
     764                        thread. Each <varname>valueform</varname> is used to
     765                        compute the value of a new binding of
     766                        <varname>symbol</varname> in the execution environment of
     767                        the newly-created thread.  The default is nil.</para>
     768                </listitem>
     769              </varlistentry>
     770             
     771              <varlistentry>
     772                <term>process</term>
     773               
     774                <listitem>
     775                      <para>the newly-created process.</para>
     776                </listitem>
     777              </varlistentry>
     778            </variablelist>
     779          </refsect1>
     780
     781          <refsect1>
     782            <title>Description</title>
     783
     784            <para>Creates and returns a new lisp process (thread) with the
     785              specified attributes. <varname>process</varname> will not begin
     786              execution immediately; it will need to be
     787              <emphasis>preset</emphasis> (given
     788              an initial function to run, as by
     789              <xref linkend="f_process-preset"/>) and
     790              <emphasis>enabled</emphasis>
     791              (allowed to execute, as by <xref linkend="f_process-enable"/>)
     792              before it&#39;s able to actually do anything.</para>
     793
     794            <para>If <varname>valueform</varname> is a function, it is
     795              called, with no arguments, in the execution environment of the
     796              newly-created thread; the primary value it returns is used for
     797              the binding of the corresponding <varname>symbol</varname>.</para>
     798
     799            <para>Otherwise, <varname>valueform</varname> is evaluated in the
     800              execution
     801              environment of the newly-created thread, and the resulting value
     802              is used.</para>
     803          </refsect1>
     804
     805          <refsect1>
     806            <title>See Also</title>
     807           
     808            <simplelist type="inline">
     809              <member><xref linkend="f_process-preset"/></member>
     810              <member><xref linkend="f_process-enable"/></member>
     811              <member><xref linkend="f_process-run-function"/></member>
     812            </simplelist>
     813          </refsect1>
     814    </refentry>
     815
     816    <refentry id="f_process-suspend">
     817          <indexterm zone="f_process-suspend">
     818            <primary>process-suspend</primary>
     819          </indexterm>
     820
     821          <refnamediv>
     822            <refname>PROCESS-SUSPEND</refname>
     823            <refpurpose>Suspends a specified process.</refpurpose>
     824            <refclass>Function</refclass>
     825          </refnamediv>
    605826         
    606           <variablelist>
    607             <varlistentry>
    608               <term>result</term>
    609               <listitem>
    610                 <para>a list of all lisp processes (threads)
    611                 known to &CCL;.</para>
    612               </listitem>
    613             </varlistentry>
    614           </variablelist>
    615         </refsect1>
    616         <refsect1>
    617           <title>Description</title>
    618 
    619           <para>Returns a list of all lisp processes (threads) known
    620           to &CCL; as of
    621           the precise instant it&#39;s called. It&#39;s safe to traverse
    622           this list and to modify the cons cells that comprise that list
    623           (it&#39;s freshly consed.) Since other threads can create and kill
    624           threads at any time, there&#39;s generally no way to get an
    625           &#34;accurate&#34; list of all threads, and (generally) no
    626           sense in which such a list can be accurate.</para>
    627         </refsect1>
    628 
    629         <refsect1>
    630           <title>See Also</title>
    631          
    632           <simplelist type="inline">
    633             <member><xref linkend="v_current-process"/></member>
    634           </simplelist>
    635         </refsect1>
    636       </refentry>
    637 
    638       <refentry id="f_make-process">
    639         <indexterm zone="f_make-process">
    640           <primary>make-process</primary>
    641         </indexterm>
    642 
    643         <refnamediv>
    644           <refname>MAKE-PROCESS</refname>
    645           <refpurpose>Creates and returns a new process.</refpurpose>
    646           <refclass>Function</refclass>
    647         </refnamediv>
    648 
    649         <refsynopsisdiv>
    650           <synopsis>
    651             <function>make-process</function>
    652             name &amp;key
    653             persistent priority class stack-size vstack-size
    654             tstack-size initial-bindings use-standard-initial-bindings
    655             => process
    656           </synopsis>
    657         </refsynopsisdiv>
    658 
    659         <refsect1>
    660           <title>Arguments and Values</title>
     827          <refsynopsisdiv>
     828            <synopsis><function>process-suspend</function> process
     829              => result</synopsis>
     830          </refsynopsisdiv>
     831
     832          <refsect1>
     833            <title>Arguments and Values</title>
     834           
     835            <variablelist>
     836              <varlistentry>
     837                <term>process</term>
     838                <listitem>
     839                      <para>a lisp process (thread).</para>
     840                </listitem>
     841              </varlistentry>
     842              <varlistentry>
     843                <term>result</term>
     844                <listitem>
     845                      <para>T if <varname>process</varname> had been runnable
     846                        and is now suspended; NIL otherwise.  That is, T if
     847                        <varname>process</varname>'s
     848                        <xref linkend="f_process-suspend-count"/>
     849                        transitioned from 0 to 1.</para>
     850                </listitem>
     851              </varlistentry>
     852            </variablelist>
     853          </refsect1>
     854
     855          <refsect1>
     856            <title>Description</title>
     857
     858            <para>Suspends <varname>process</varname>, preventing it from
     859              running, and stopping it if it was already running. This is a fairly
     860              expensive operation, because it involves a few
     861              calls to the OS.  It also risks creating deadlock if used
     862              improperly, for instance, if the process being suspended owns a
     863              lock or other resource which another process will wait for.</para>
     864
     865            <para>
     866              Each
     867              call to <function>process-suspend</function> must be reversed by
     868              a matching call to <xref linkend="f_process-resume"/>
     869              before <varname>process</varname> is able to run.  What
     870              <function>process-suspend</function> actually does is increment
     871              the <xref linkend="f_process-suspend-count"/> of
     872              <varname>process</varname>.
     873            </para>
     874
     875            <para>A process can suspend itself; it it&#39;s successful in doing
     876              so, then it can obviously only be resumed by some other
     877              process.</para>
     878          </refsect1>
     879
     880          <refsect1>
     881            <title>See Also</title>
     882           
     883            <simplelist type="inline">
     884              <member><xref linkend="f_process-resume"/></member>
     885              <member><xref linkend="f_process-suspend-count"/></member>
     886            </simplelist>
     887          </refsect1>
     888
     889          <refsect1>
     890            <title>Notes</title>
     891            <para><function>process-suspend</function> was previously called
     892              <function>process-disable</function>.
     893              <xref linkend="f_process-enable"/>
     894              now names a function for which there is no
     895              obvious inverse, so <function>process-disable</function>
     896              is no longer
     897              defined.</para>
     898          </refsect1>
     899    </refentry>
     900
     901    <refentry id="f_process-resume">
     902          <indexterm zone="f_process-resume">
     903            <primary>process-resume</primary>
     904          </indexterm>
     905
     906          <refnamediv>
     907            <refname>PROCESS-RESUME</refname>
     908            <refpurpose>Resumes a specified process which had previously
     909              been suspended by process-suspend.</refpurpose>
     910            <refclass>Function</refclass>
     911          </refnamediv>
     912
     913          <refsynopsisdiv>
     914            <synopsis><function>process-resume</function> process
     915              => result</synopsis>
     916          </refsynopsisdiv>
     917
     918          <refsect1>
     919            <title>Arguments and Values</title>
     920           
     921            <variablelist>
     922              <varlistentry>
     923                <term>process</term>
     924                <listitem>
     925                      <para>a lisp process (thread).</para>
     926                </listitem>
     927              </varlistentry>
     928              <varlistentry>
     929                <term>result</term>
     930                <listitem>
     931                      <para>T if <varname>process</varname> had been suspended
     932                        and is now runnable; NIL otherwise.  That is, T if
     933                        <varname>process</varname>'s
     934                        <xref linkend="f_process-suspend-count"/>
     935                        transitioned from  to 0.
     936                      </para>
     937                </listitem>
     938              </varlistentry>
     939            </variablelist>
     940          </refsect1>
     941
     942          <refsect1>
     943            <title>Description</title>
     944
     945            <para>Undoes the effect of a previous call to
     946              <xref linkend="f_process-suspend"/>; if
     947              all such calls are undone, makes the process runnable. Has no
     948              effect if the process is not suspended.  What
     949              <function>process-resume</function> actually does is decrement
     950              the <xref linkend="f_process-suspend-count"/> of
     951              <varname>process</varname>, to a minimum of 0.</para>
     952          </refsect1>
     953
     954          <refsect1>
     955            <title>See Also</title>
     956           
     957            <simplelist type="inline">
     958              <member><xref linkend="f_process-suspend"/></member>
     959              <member><xref linkend="f_process-suspend-count"/></member>
     960            </simplelist>
     961          </refsect1>
     962
     963          <refsect1>
     964            <title>Notes</title>
     965
     966            <para>
     967              This was previously called PROCESS-ENABLE;
     968              <xref linkend="f_process-enable"/> now does something slightly
     969              different.
     970            </para>
     971          </refsect1>
     972    </refentry>
     973
     974    <refentry id="f_process-suspend-count">
     975          <indexterm zone="f_process-suspend-count">
     976            <primary>process-suspend-count</primary>
     977          </indexterm>
     978
     979          <refnamediv>
     980            <refname>PROCESS-SUSPEND-COUNT</refname>
     981            <refpurpose>Returns the number of currently-pending suspensions
     982              applicable to a given process.</refpurpose>
     983            <refclass>Function</refclass>
     984          </refnamediv>
     985
     986          <refsynopsisdiv>
     987            <synopsis>
     988              <function>process-suspend-count</function>
     989              process => result
     990            </synopsis>
     991          </refsynopsisdiv>
     992
     993          <refsect1>
     994            <title>Arguments and Values</title>
     995
     996            <variablelist>
     997              <varlistentry>
     998                <term>process</term>
     999                <listitem>
     1000                      <para>a lisp process (thread).</para>
     1001                </listitem>
     1002              </varlistentry>
     1003              <varlistentry>
     1004                <term>result</term>
     1005                <listitem>
     1006                      <para>The number of "outstanding"
     1007                        <xref linkend="f_process-suspend"/> calls on
     1008                        <varname>process</varname>, or NIL if
     1009                        <varname>process</varname> has expired.
     1010                      </para>
     1011                </listitem>
     1012              </varlistentry>
     1013            </variablelist>
     1014          </refsect1>
     1015
     1016          <refsect1>
     1017            <title>Description</title>
     1018
     1019            <para>An "outstanding" <xref linkend="f_process-suspend"/> call
     1020              is one which has not yet been reversed by a call to
     1021              <xref linkend="f_process-resume"/>.  A process expires when
     1022              its initial function returns, although it may later be
     1023              reset.</para>
     1024
     1025            <para>A process is <emphasis>runnable</emphasis> when it has a
     1026              <function>process-suspend-count</function> of 0, has been
     1027              preset as by <xref linkend="f_process-preset"/>, and has been
     1028              enabled as by <xref linkend="f_process-enable"/>.  Newly-created
     1029              processes have a <function>process-suspend-count</function> of
     1030              0.</para>
     1031          </refsect1>
     1032
     1033          <refsect1>
     1034            <title>See Also</title>
     1035           
     1036            <simplelist type="inline">
     1037              <member><xref linkend="f_process-suspend"/></member>
     1038              <member><xref linkend="f_process-resume"/></member>
     1039            </simplelist>
     1040          </refsect1>
     1041    </refentry>
     1042
     1043    <refentry id="f_process-preset">
     1044          <indexterm zone="f_process-preset">
     1045            <primary>process-preset</primary>
     1046          </indexterm>
     1047
     1048          <refnamediv>
     1049            <refname>PROCESS-PRESET</refname>
     1050            <refpurpose>Sets the initial function and arguments of a specified
     1051              process.</refpurpose>
     1052            <refclass>Function</refclass>
     1053          </refnamediv>
     1054
     1055          <refsynopsisdiv>
     1056            <synopsis><function>process-preset</function>
     1057              process function &rest; args
     1058              => result</synopsis>
     1059          </refsynopsisdiv>
     1060
     1061          <refsect1>
     1062            <title>Arguments and Values</title>
     1063
     1064            <variablelist>
     1065              <varlistentry>
     1066                <term>process</term>
     1067                <listitem>
     1068                      <para>a lisp process (thread).</para>
     1069                </listitem>
     1070              </varlistentry>
     1071              <varlistentry>
     1072                <term>function</term>
     1073                <listitem>
     1074                      <para>a function, designated by itself or by a symbol
     1075                        which names it.
     1076                      </para>
     1077                </listitem>
     1078              </varlistentry>
     1079              <varlistentry>
     1080                <term>args</term>
     1081                <listitem>
     1082                      <para>a list of values, appropriate as arguments to
     1083                        <varname>function</varname>.</para>
     1084                </listitem>
     1085              </varlistentry>
     1086              <varlistentry>
     1087                <term>result</term>
     1088                <listitem>
     1089                      <para>undefined.</para>
     1090                </listitem>
     1091              </varlistentry>
     1092            </variablelist>
     1093          </refsect1>
     1094
     1095          <refsect1>
     1096            <title>Description</title>
     1097
     1098            <para>Typically used to initialize a newly-created or newly-reset
     1099              process, setting things up so that when <varname>process</varname>
     1100              becomes enabled, it will begin execution by
     1101              applying <varname>function</varname> to <varname>args</varname>.
     1102              <function>process-preset</function> does not enable
     1103              <varname>process</varname>,
     1104              although a process must be <function>process-preset</function>
     1105              before it can be enabled.  Processes are normally enabled by
     1106              <xref linkend="f_process-enable"/>.
     1107            </para>
     1108          </refsect1>
     1109
     1110          <refsect1>
     1111            <title>See Also</title>
     1112           
     1113            <simplelist type="inline">
     1114              <member><xref linkend="f_make-process"/></member>
     1115              <member><xref linkend="f_process-enable"/></member>
     1116              <member><xref linkend="f_process-run-function"/></member>
     1117            </simplelist>
     1118          </refsect1>
     1119    </refentry>
     1120
     1121    <refentry id="f_process-enable">
     1122          <indexterm zone="f_process-enable">
     1123            <primary>process-enable</primary>
     1124          </indexterm>
     1125
     1126          <refnamediv>
     1127            <refname>PROCESS-ENABLE</refname>
     1128            <refpurpose>Begins executing the initial function of a specified
     1129              process.</refpurpose>
     1130            <refclass>Function</refclass>
     1131          </refnamediv>
     1132
     1133          <refsynopsisdiv>
     1134            <synopsis><function>process-enable</function>
     1135              process &optional; timeout
     1136            </synopsis>
     1137          </refsynopsisdiv>
     1138
     1139          <refsect1>
     1140            <title>Arguments and Values</title>
     1141
     1142            <variablelist>
     1143              <varlistentry>
     1144                <term>process</term>
     1145                <listitem>
     1146                      <para>a lisp process (thread).</para>
     1147                </listitem>
     1148              </varlistentry>
     1149              <varlistentry>
     1150                <term>timeout</term>
     1151                <listitem>
     1152                      <para>a time interval in seconds.  May be any
     1153                        non-negative real number the <function>floor</function> of
     1154                        which fits in 32 bits.  The default is 1.</para>
     1155                </listitem>
     1156              </varlistentry>
     1157              <varlistentry>
     1158                <term>result</term>
     1159                <listitem>
     1160                      <para>undefined.</para>
     1161                </listitem>
     1162              </varlistentry>
     1163            </variablelist>
     1164          </refsect1>
     1165
     1166          <refsect1>
     1167            <title>Description</title>
     1168
     1169            <para>Tries to begin the execution of <varname>process</varname>.
     1170              An error is signaled if <varname>process</varname> has never
     1171              been <xref linkend="f_process-preset"/>.  Otherwise,
     1172              <varname>process</varname> invokes its initial function.
     1173            </para>
     1174           
     1175            <para><function>process-enable</function> attempts to
     1176              synchronize with <varname>process</varname>, which is presumed
     1177              to be reset or in the act of resetting itself.  If this attempt
     1178              is not successful within the time interval specified by
     1179              <varname>timeout</varname>, a continuable error is signaled,
     1180              which offers the opportunity to continue waiting.
     1181            </para>
     1182
     1183            <para>A process cannot meaningfully attempt to enable itself.</para>
     1184          </refsect1>
     1185
     1186          <refsect1>
     1187            <title>See Also</title>
     1188           
     1189            <simplelist type="inline">
     1190              <member><xref linkend="f_make-process"/></member>
     1191              <member><xref linkend="f_process-preset"/></member>
     1192              <member><xref linkend="f_process-run-function"/></member>
     1193            </simplelist>
     1194          </refsect1>
     1195
     1196          <refsect1>
     1197            <title>Notes</title>
     1198
     1199            <para>It would be nice to have more discussion of what it means
     1200              to synchronize with the process.</para>
     1201          </refsect1>
     1202    </refentry>
     1203
     1204    <refentry id="f_process-run-function">
     1205          <indexterm zone="f_process-run-function">
     1206            <primary>process-run-function</primary>
     1207          </indexterm>
     1208
     1209          <refnamediv>
     1210            <refname>PROCESS-RUN-FUNCTION</refname>
     1211            <refpurpose>Creates a process, presets it, and enables it.
     1212            </refpurpose>
     1213            <refclass>Function</refclass>
     1214          </refnamediv>
     1215
     1216          <refsynopsisdiv>
     1217            <synopsis><function>process-run-function</function>
     1218              process-specifier function &rest; args => process</synopsis>
     1219
     1220            <variablelist>
     1221              <varlistentry>
     1222                <term>process-specifier</term>
     1223                <listitem>
     1224                      <para>
     1225                        <varname>name</varname> |
     1226                        (&key; <varname>name</varname>
     1227                        <varname>persistent</varname>
     1228                        <varname>priority</varname>
     1229                        <varname>class</varname>
     1230                        <varname>stack-size</varname>
     1231                        <varname>vstack-size</varname>
     1232                        <varname>tstack-size</varname>)
     1233                      </para>
     1234                </listitem>
     1235              </varlistentry>
     1236            </variablelist>
     1237          </refsynopsisdiv>
     1238
     1239          <refsect1>
     1240            <title>Arguments and Values</title>
     1241
     1242            <variablelist>
     1243              <varlistentry>
     1244                <term>name</term>
     1245                <listitem>
     1246                      <para>a string, used to identify the process.
     1247                        Passed to <function>make-process</function>.</para>
     1248                </listitem>
     1249              </varlistentry>
     1250              <varlistentry>
     1251                <term>function</term>
     1252                <listitem>
     1253                      <para>a function, designated by itself or by a symbol
     1254                        which names it.  Passed to
     1255                        <function>preset-process</function>.
     1256                      </para>
     1257                </listitem>
     1258              </varlistentry>
     1259              <varlistentry>
     1260                <term>persistent</term>
     1261               
     1262                <listitem>
     1263                      <para>a boolean, passed to <function>make-process</function>.
     1264                      </para>
     1265                </listitem>
     1266              </varlistentry>
     1267             
     1268              <varlistentry>
     1269                <term>priority</term>
     1270               
     1271                <listitem>
     1272                      <para>ignored.</para>
     1273                </listitem>
     1274              </varlistentry>
     1275             
     1276              <varlistentry>
     1277                <term>class</term>
     1278               
     1279                <listitem>
     1280                      <para>a subclass of CCL:PROCESS.  Passed to
     1281                        <function>make-process</function>.</para>
     1282                </listitem>
     1283              </varlistentry>
     1284             
     1285              <varlistentry>
     1286                <term>stack-size</term>
     1287               
     1288                <listitem>
     1289                      <para>a size, in bytes.  Passed to
     1290                        <function>make-process</function>.</para>
     1291                </listitem>
     1292              </varlistentry>
     1293             
     1294              <varlistentry>
     1295                <term>vstack-size</term>
     1296               
     1297                <listitem>
     1298                      <para>a size, in bytes.  Passed to
     1299                        <function>make-process</function>.</para>
     1300                </listitem>
     1301              </varlistentry>
     1302             
     1303              <varlistentry>
     1304                <term>tstack-size</term>
     1305               
     1306                <listitem>
     1307                      <para>a size, in bytes.  Passed to
     1308                        <function>make-process</function>.</para>
     1309                </listitem>
     1310              </varlistentry>
     1311              <varlistentry>
     1312                <term>process</term>
     1313                <listitem>
     1314                      <para>the newly-created process.</para>
     1315                </listitem>
     1316              </varlistentry>
     1317            </variablelist>
     1318          </refsect1>
     1319
     1320          <refsect1>
     1321            <title>Description</title>
     1322
     1323            <para>Creates a lisp process (thread) via
     1324              <xref linkend="f_make-process"/>,
     1325              presets it via <xref linkend="f_process-preset"/>, and
     1326              enables it via <xref linkend="f_process-enable"/>.  This means
     1327              that <varname>process</varname> will immediately begin to
     1328              execute.
     1329              <function>process-run-function</function> is
     1330              the simplest way to create and run a process.
     1331            </para>
     1332          </refsect1>
     1333
     1334          <refsect1>
     1335            <title>See Also</title>
     1336           
     1337            <simplelist type="inline">
     1338              <member><xref linkend="f_make-process"/></member>
     1339              <member><xref linkend="f_process-preset"/></member>
     1340              <member><xref linkend="f_process-enable"/></member>
     1341            </simplelist>
     1342          </refsect1>
     1343    </refentry>
     1344
     1345    <refentry id="f_process-interrupt">
     1346          <indexterm zone="f_process-interrupt">
     1347            <primary>process-interrupt</primary>
     1348          </indexterm>
     1349
     1350          <refnamediv>
     1351            <refname>PROCESS-INTERRUPT</refname>
     1352            <refpurpose>Arranges for the target process to invoke a
     1353              specified function at some point in the near future, and then
     1354              return to what it was doing.</refpurpose>
     1355            <refclass>Function</refclass>
     1356          </refnamediv>
     1357
     1358          <refsynopsisdiv>
     1359            <synopsis><function>process-interrupt</function>
     1360              process function &rest; args => result</synopsis>
     1361          </refsynopsisdiv>
     1362
     1363          <refsect1>
     1364            <title>Arguments and Values</title>
     1365
     1366            <variablelist>
     1367              <varlistentry>
     1368                <term>process</term>
     1369                <listitem>
     1370                      <para>a lisp process (thread).</para>
     1371                </listitem>
     1372              </varlistentry>
     1373              <varlistentry>
     1374                <term>function</term>
     1375                <listitem>
     1376                      <para>a function.
     1377                      </para>
     1378                </listitem>
     1379              </varlistentry>
     1380              <varlistentry>
     1381                <term>args</term>
     1382                <listitem>
     1383                      <para>a list of values, appropriate as arguments to
     1384                        <varname>function</varname>.</para>
     1385                </listitem>
     1386              </varlistentry>
     1387              <varlistentry>
     1388                <term>result</term>
     1389                <listitem>
     1390                      <para>the result of applying <varname>function</varname>
     1391                        to <varname>args</varname> if <varname>process</varname>
     1392                        is the <function>current-process</function>, otherwise
     1393                        NIL.</para>
     1394                </listitem>
     1395              </varlistentry>
     1396            </variablelist>
     1397          </refsect1>
     1398
     1399          <refsect1>
     1400            <title>Description</title>
     1401
     1402            <para>Arranges for <varname>process</varname>
     1403              to apply <varname>function</varname> to <varname>args</varname> at
     1404              some point in the near future (interrupting whatever
     1405              <varname>process</varname>
     1406              was doing.) If <varname>function</varname> returns normally,
     1407              <varname>process</varname> resumes
     1408              execution at the point at which it was interrupted.</para>
     1409
     1410            <para><varname>process</varname> must be in an enabled state in
     1411              order to respond
     1412              to a <function>process-interrupt</function> request.  It's
     1413              perfectly legal for a process to call
     1414              <function>process-interrupt</function> on itself.</para>
     1415
     1416            <para><function>process-interrupt</function>
     1417              uses asynchronous POSIX signals to interrupt threads. If the
     1418              thread being interrupted is executing lisp code, it can
     1419              respond to the interrupt almost immediately (as soon as it
     1420              has finished pseudo-atomic operations like consing and
     1421              stack-frame initialization.)</para>
     1422
     1423            <para>If the interrupted thread is
     1424              blocking in a system call, that system call is aborted by
     1425              the signal and the interrupt is handled on return.
     1426            </para>
     1427
     1428            <para>It is
     1429              still difficult to reliably interrupt arbitrary foreign code
     1430              (that may be stateful or otherwise non-reentrant); the
     1431              interrupt request is handled when such foreign code returns
     1432              to or enters lisp.</para>
     1433          </refsect1>
     1434
     1435          <refsect1>
     1436            <title>See Also</title>
     1437           
     1438            <simplelist type="inline">
     1439              <member><xref linkend="m_without-interrupts"/></member>
     1440            </simplelist>
     1441          </refsect1>
     1442
     1443          <refsect1>
     1444            <title>Notes</title>
     1445
     1446            <para>It would probably be better for <varname>result</varname>
     1447              to always be NIL, since the present behavior is inconsistent.
     1448            </para>
     1449
     1450            <para>
     1451              <function>Process-interrupt</function> works by sending signals
     1452              between threads, via the C function
     1453              <function>#_pthread_signal</function>.  It could be argued
     1454              that it should be done in one of several possible other ways
     1455              under
     1456              Darwin, to make it practical to asynchronously interrupt
     1457              things which make heavy use of the Mach nanokernel.
     1458            </para>
     1459          </refsect1>
     1460    </refentry>
     1461
     1462    <refentry id="v_current-process">
     1463          <indexterm zone="v_current-process">
     1464            <primary>*current-process*</primary>
     1465          </indexterm>
     1466
     1467          <refnamediv>
     1468            <refname>*CURRENT-PROCESS*</refname>
     1469            <refpurpose>Bound in each process, to that process
     1470              itself.</refpurpose>
     1471            <refclass>Variable</refclass>
     1472          </refnamediv>
     1473
     1474          <refsect1>
     1475            <title>Value Type</title>
     1476
     1477            <para>A lisp process (thread).</para>
     1478          </refsect1>
     1479
     1480          <refsect1>
     1481            <title>Initial Value</title>
     1482           
     1483            <para>Bound separately in each process, to that process itself.
     1484            </para>
     1485          </refsect1>
     1486
     1487          <refsect1>
     1488            <title>Description</title>
     1489
     1490            <para>Used when lisp code needs to find out what process it is
     1491              executing in.  Shouldn't be set by user code.</para>
     1492          </refsect1>
     1493
     1494          <refsect1>
     1495            <title>See Also</title>
     1496           
     1497            <simplelist type="inline">
     1498              <member><xref linkend="f_all-processes"/></member>
     1499            </simplelist>
     1500          </refsect1>
     1501    </refentry>
     1502
     1503    <refentry id="f_process-reset">
     1504          <indexterm zone="f_process-reset">
     1505            <primary>process-reset</primary>
     1506          </indexterm>
     1507
     1508          <refnamediv>
     1509            <refname>PROCESS-RESET</refname>
     1510            <refpurpose>Causes a specified process to cleanly exit from
     1511              any ongoing computation.</refpurpose>
     1512            <refclass>Function</refclass>
     1513          </refnamediv>
     1514
     1515          <refsynopsisdiv>
     1516            <synopsis><function>process-reset</function>
     1517              process &optional; kill-option => result</synopsis>
     1518          </refsynopsisdiv>
     1519
     1520          <refsect1>
     1521            <title>Arguments and Values</title>
     1522
     1523            <variablelist>
     1524              <varlistentry>
     1525                <term>process</term>
     1526                <listitem>
     1527                      <para>a lisp process (thread).</para>
     1528                </listitem>
     1529              </varlistentry>
     1530              <varlistentry>
     1531                <term>kill-option</term>
     1532                <listitem>
     1533                      <para>a generalized boolean.  The default is T.</para>
     1534                </listitem>
     1535              </varlistentry>
     1536              <varlistentry>
     1537                <term>result</term>
     1538                <listitem>
     1539                      <para>undefined.</para>
     1540                </listitem>
     1541              </varlistentry>
     1542            </variablelist>
     1543          </refsect1>
     1544
     1545          <refsect1>
     1546            <title>Description</title>
     1547
     1548            <para>Causes <varname>process</varname> to cleanly exit
     1549              from any ongoing computation.  If <varname>kill-option</varname>
     1550              is true, <varname>process</varname> then exits.  Otherwise, it
     1551              enters a state where it can be
     1552              <xref linkend="f_process-preset"/>. This
     1553              is implemented by signaling a condition of type PROCESS-RESET;
     1554              user-defined condition handlers should generally refrain from
     1555              attempting to handle conditions of this type.</para>
     1556
     1557            <para>A process can meaningfully reset itself.</para>
     1558
     1559            <para>There is in general no way to know precisely when
     1560              <varname>process</varname>
     1561              has completed the act of resetting or killing itself; a process
     1562              which has either entered the limbo of the reset state or exited
     1563              has few ways of communicating either fact.
     1564              <xref linkend="f_process-enable"/>
     1565              can reliably determine when a process has entered
     1566              the "limbo of the reset state", but can't predict how long the
     1567              clean exit from ongoing computation might take: that depends on
     1568              the behavior of <function>unwind-protect</function> cleanup
     1569              forms, and of the OS scheduler.</para>
     1570
     1571            <para>Resetting a process other than
     1572              <xref linkend="v_current-process"/> involves the
     1573              use of <xref linkend="f_process-interrupt"/>.</para>
     1574          </refsect1>
     1575
     1576          <refsect1>
     1577            <title>See Also</title>
     1578           
     1579            <simplelist type="inline">
     1580              <member><xref linkend="f_process-kill"/></member>
     1581              <member><xref linkend="f_process-abort"/></member>
     1582            </simplelist>
     1583          </refsect1>
     1584    </refentry>
     1585
     1586    <refentry id="f_process-kill">
     1587          <indexterm zone="f_process-kill">
     1588            <primary>process-kill</primary>
     1589          </indexterm>
     1590
     1591          <refnamediv>
     1592            <refname>PROCESS-KILL</refname>
     1593            <refpurpose>Causes a specified process to cleanly exit from any
     1594              ongoing computation, and then exit.</refpurpose>
     1595            <refclass>Function</refclass>
     1596          </refnamediv>
     1597
     1598          <refsynopsisdiv>
     1599            <synopsis><function>process-kill</function> process
     1600              => result</synopsis>
     1601          </refsynopsisdiv>
     1602
     1603          <refsect1>
     1604            <title>Arguments and Values</title>
     1605
     1606            <variablelist>
     1607              <varlistentry>
     1608                <term>process</term>
     1609                <listitem>
     1610                      <para>a lisp process (thread).</para>
     1611                </listitem>
     1612              </varlistentry>
     1613              <varlistentry>
     1614                <term>result</term>
     1615                <listitem>
     1616                      <para>undefined.</para>
     1617                </listitem>
     1618              </varlistentry>
     1619            </variablelist>
     1620          </refsect1>
     1621
     1622          <refsect1>
     1623            <title>Description</title>
     1624
     1625            <para>Entirely equivalent to calling
     1626              (PROCESS-RESET PROCESS T).  Causes <varname>process</varname>
     1627              to cleanly exit from any ongoing computation, and then exit.</para>
     1628          </refsect1>
     1629
     1630          <refsect1>
     1631            <title>See Also</title>
     1632           
     1633            <simplelist type="inline">
     1634              <member><xref linkend="f_process-reset"/></member>
     1635              <member><xref linkend="f_process-abort"/></member>
     1636            </simplelist>
     1637          </refsect1>
     1638    </refentry>
     1639
     1640    <refentry id="f_process-abort">
     1641          <indexterm zone="f_process-abort">
     1642            <primary>process-abort</primary>
     1643          </indexterm>
     1644
     1645          <refnamediv>
     1646            <refname>PROCESS-ABORT</refname>
     1647            <refpurpose>Causes a specified process to process an abort
     1648              condition, as if it had invoked
     1649              <function>abort</function>.</refpurpose>
     1650            <refclass>Function</refclass>
     1651          </refnamediv>
     1652
     1653          <refsynopsisdiv>
     1654            <synopsis><function>process-abort</function> process
     1655              &optional; condition
     1656              => NIL</synopsis>
     1657          </refsynopsisdiv>
     1658
     1659          <refsect1>
     1660            <title>Arguments and Values</title>
     1661
     1662            <variablelist>
     1663              <varlistentry>
     1664                <term>process</term>
     1665                <listitem>
     1666                      <para>a lisp process (thread).</para>
     1667                </listitem>
     1668              </varlistentry>
     1669              <varlistentry>
     1670                <term>condition</term>
     1671                <listitem>
     1672                      <para>a lisp condition.  The default is NIL.</para>
     1673                </listitem>
     1674              </varlistentry>
     1675            </variablelist>
     1676          </refsect1>
     1677
     1678          <refsect1>
     1679            <title>Description</title>
     1680
     1681            <para>Entirely equivalent to calling
     1682              (<xref linkend="f_process-interrupt"/> <varname>process</varname>
     1683              (<function>lambda</function> ()
     1684              (<function>abort</function> <varname>condition</varname>))).
     1685              Causes <varname>process</varname> to transfer control to the
     1686              applicable handler or restart for <function>abort</function>.</para>
     1687
     1688            <para>If <varname>condition</varname> is non-NIL,
     1689              <function>process-abort</function> does not consider any
     1690              handlers which are explicitly bound to conditions other than
     1691              <varname>condition</varname>.</para>
     1692          </refsect1>
     1693
     1694          <refsect1>
     1695            <title>See Also</title>
     1696           
     1697            <simplelist type="inline">
     1698              <member><xref linkend="f_process-reset"/></member>
     1699              <member><xref linkend="f_process-kill"/></member>
     1700            </simplelist>
     1701          </refsect1>
     1702    </refentry>
     1703
     1704    <refentry id="v_ticks-per-second">
     1705          <indexterm zone="v_ticks-per-second">
     1706            <primary>*ticks-per-second*</primary>
     1707          </indexterm>
     1708
     1709          <refnamediv>
     1710            <refname>*TICKS-PER-SECOND*</refname>
     1711            <refpurpose>Bound to the clock resolution of the OS
     1712              scheduler.</refpurpose>
     1713            <refclass>Variable</refclass>
     1714          </refnamediv>
     1715
     1716          <refsect1>
     1717            <title>Value Type</title>
     1718
     1719            <para>A positive integer.</para>
     1720          </refsect1>
     1721
     1722          <refsect1>
     1723            <title>Initial Value</title>
     1724           
     1725            <para>The clock resolution of the OS scheduler.  Currently,
     1726              both LinuxPPC and DarwinPPC yield an initial value of 100.
     1727            </para>
     1728          </refsect1>
     1729
     1730          <refsect1>
     1731            <title>Description</title>
     1732
     1733            <para>This value is ordinarily of marginal interest at best,
     1734              but, for backward compatibility, some functions accept timeout
     1735              values expressed in "ticks".  This value gives the number of
     1736              ticks per second.</para>
     1737          </refsect1>
     1738
     1739          <refsect1>
     1740            <title>See Also</title>
     1741           
     1742            <simplelist type="inline">
     1743              <member><xref linkend="f_process-wait-with-timeout"/></member>
     1744            </simplelist>
     1745          </refsect1>
     1746    </refentry>
     1747
     1748    <refentry id="f_process-whostate">
     1749          <indexterm zone="f_process-whostate">
     1750            <primary>process-whostate</primary>
     1751          </indexterm>
     1752
     1753          <refnamediv>
     1754            <refname>PROCESS-WHOSTATE</refname>
     1755            <refpurpose>Returns a string which describes the status of
     1756              a specified process.</refpurpose>
     1757            <refclass>Function</refclass>
     1758          </refnamediv>
     1759
     1760          <refsynopsisdiv>
     1761            <synopsis><function>process-whostate</function> process
     1762              => whostate</synopsis>
     1763            <variablelist>
     1764              <varlistentry>
     1765                <term>process</term>
     1766                <listitem>
     1767                      <para>a lisp process (thread).</para>
     1768                </listitem>
     1769              </varlistentry>
     1770              <varlistentry>
     1771                <term>whostate</term>
     1772                <listitem>
     1773                      <para>a string which describes the "state" of
     1774                        <varname>process</varname>.</para>
     1775                </listitem>
     1776              </varlistentry>
     1777            </variablelist>
     1778          </refsynopsisdiv>
     1779
     1780          <refsect1>
     1781            <title>Description</title>
     1782
     1783            <para>This information is primarily for the benefit of
     1784              debugging tools.  <varname>whostate</varname> is a terse report
     1785              on what <varname>process</varname> is doing, or not doing,
     1786              and why.</para>
     1787
     1788            <para>If the process is currently waiting in a call to
     1789              <xref linkend="f_process-wait"/> or
     1790              <xref linkend="f_process-wait-with-timeout"/>, its
     1791              <function>process-whostate</function> will be the value
     1792              which was passed to that function as <varname>whostate</varname>.
     1793            </para>
     1794          </refsect1>
     1795
     1796          <refsect1>
     1797            <title>See Also</title>
     1798           
     1799            <simplelist type="inline">
     1800              <member><xref linkend="f_process-wait"/></member>
     1801              <member><xref linkend="f_process-wait-with-timeout"/></member>
     1802              <member><xref linkend="m_with-terminal-input"/></member>
     1803            </simplelist>
     1804          </refsect1>
     1805
     1806          <refsect1>
     1807            <title>Notes</title>
     1808
     1809            <para>This should arguably be SETFable, but doesn't seem to
     1810              ever have been.</para>
     1811          </refsect1>
     1812    </refentry>
     1813
     1814    <refentry id="f_process-allow-schedule">
     1815          <indexterm zone="f_process-allow-schedule">
     1816            <primary>process-allow-schedule</primary>
     1817          </indexterm>
     1818
     1819          <refnamediv>
     1820            <refname>PROCESS-ALLOW-SCHEDULE</refname>
     1821            <refpurpose>Used for cooperative multitasking; probably never
     1822              necessary.</refpurpose>
     1823            <refclass>Function</refclass>
     1824          </refnamediv>
     1825
     1826          <refsynopsisdiv>
     1827            <synopsis><function>process-allow-schedule</function></synopsis>
     1828          </refsynopsisdiv>
     1829
     1830          <refsect1>
     1831            <title>Description</title>
     1832
     1833            <para>Advises the OS scheduler that the current thread has nothing
     1834              useful to do and that it should try to find some other thread to
     1835              schedule in its place. There's almost always a better
     1836              alternative, such as waiting for some specific event to
     1837              occur.  For example, you could use a lock or semaphore.</para>
     1838          </refsect1>
     1839
     1840          <refsect1>
     1841            <title>See Also</title>
     1842           
     1843            <simplelist type="inline">
     1844              <member><xref linkend="f_make-lock"/></member>
     1845              <member><xref linkend="f_make-read-write-lock"/></member>
     1846              <member><xref linkend="f_make-semaphore"/></member>
     1847              <member><xref linkend="f_process-input-wait"/></member>
     1848              <member><xref linkend="f_process-output-wait"/></member>
     1849              <member><xref linkend="m_with-terminal-input"/></member>
     1850            </simplelist>
     1851          </refsect1>
     1852
     1853          <refsect1>
     1854            <title>Notes</title>
     1855
     1856            <para>This is a holdover from the days of cooperative
     1857              multitasking.  All modern general-purpose operating systems use
     1858              preemptive multitasking.</para>
     1859          </refsect1>
     1860    </refentry>
     1861
     1862    <refentry id="f_process-wait">
     1863          <indexterm zone="f_process-wait">
     1864            <primary>process-wait</primary>
     1865          </indexterm>
     1866
     1867          <refnamediv>
     1868            <refname>PROCESS-WAIT</refname>
     1869            <refpurpose>Causes the current lisp process (thread) to wait for
     1870              a given
     1871              predicate to return true.</refpurpose>
     1872            <refclass>Function</refclass>
     1873          </refnamediv>
     1874
     1875          <refsynopsisdiv>
     1876            <synopsis><function>process-wait</function>
     1877              whostate function &rest; args => result</synopsis>
     1878          </refsynopsisdiv>
     1879
     1880          <refsect1>
     1881            <title>Arguments and Values</title>
     1882
     1883            <variablelist>
     1884              <varlistentry>
     1885                <term>whostate</term>
     1886
     1887                <listitem>
     1888                      <para>a string, which will be the value of
     1889                        <xref linkend="f_process-whostate"/>
     1890                        while the process is waiting.</para>
     1891                </listitem>
     1892              </varlistentry>
     1893              <varlistentry>
     1894                <term>function</term>
     1895                <listitem>
     1896                      <para>a function, designated by itself or by a symbol
     1897                        which names it.
     1898                      </para>
     1899                </listitem>
     1900              </varlistentry>
     1901              <varlistentry>
     1902                <term>args</term>
     1903                <listitem>
     1904                      <para>a list of values, appropriate as arguments to
     1905                        <varname>function</varname>.</para>
     1906                </listitem>
     1907              </varlistentry>
     1908              <varlistentry>
     1909                <term>result</term>
     1910                <listitem>
     1911                      <para>NIL.</para>
     1912                </listitem>
     1913              </varlistentry>
     1914            </variablelist>
     1915          </refsect1>
     1916
     1917          <refsect1>
     1918            <title>Description</title>
     1919
     1920            <para>Causes the current lisp process (thread) to repeatedly
     1921              apply <varname>function</varname> to
     1922              <varname>args</varname> until the call returns a true result, then
     1923              returns NIL. After
     1924              each failed call, yields the CPU as if by
     1925              <xref linkend="f_process-allow-schedule"/>.</para>
     1926           
     1927            <para>
     1928              As with <xref linkend="f_process-allow-schedule"/>, it's almost
     1929              always more efficient to wait for some
     1930              specific event to occur; this isn't exactly busy-waiting, but
     1931              the OS scheduler can do a better job of scheduling if it's given
     1932              the relevant information.  For example, you could use a lock
     1933              or semaphore.</para>
     1934          </refsect1>
     1935
     1936          <refsect1>
     1937            <title>See Also</title>
     1938           
     1939            <simplelist type="inline">
     1940              <member><xref linkend="f_process-whostate"/></member>
     1941              <member><xref linkend="f_process-wait-with-timeout"/></member>
     1942              <member><xref linkend="f_make-lock"/></member>
     1943              <member><xref linkend="f_make-read-write-lock"/></member>
     1944              <member><xref linkend="f_make-semaphore"/></member>
     1945              <member><xref linkend="f_process-input-wait"/></member>
     1946              <member><xref linkend="f_process-output-wait"/></member>
     1947              <member><xref linkend="m_with-terminal-input"/></member>
     1948            </simplelist>
     1949          </refsect1>
     1950    </refentry>
     1951
     1952    <refentry id="f_process-wait-with-timeout">
     1953          <indexterm zone="f_process-wait-with-timeout">
     1954            <primary>process-wait-with-timeout</primary>
     1955          </indexterm>
     1956
     1957          <refnamediv>
     1958            <refname>PROCESS-WAIT-WITH-TIMEOUT</refname>
     1959            <refpurpose>Causes the current thread to wait for a given
     1960              predicate to return true, or for a timeout to expire.</refpurpose>
     1961            <refclass>Function</refclass>
     1962          </refnamediv>
     1963
     1964          <refsynopsisdiv>
     1965            <synopsis><function>process-wait-with-timeout</function>
     1966              whostate ticks function args => result</synopsis>
     1967          </refsynopsisdiv>
     1968
     1969          <refsect1>
     1970            <title>Arguments and Values</title>
     1971
     1972            <variablelist>
     1973              <varlistentry>
     1974                <term>whostate</term>
     1975                <listitem>
     1976                      <para>a string, which will be the value of
     1977                        <xref linkend="f_process-whostate"/>
     1978                        while the process is waiting.</para>
     1979                </listitem>
     1980              </varlistentry>
     1981              <varlistentry>
     1982                <term>ticks</term>
     1983                <listitem>
     1984                      <para>either a positive integer expressing a duration
     1985                        in "ticks" (see <xref linkend="v_ticks-per-second"/>),
     1986                        or NIL.</para>
     1987                </listitem>
     1988              </varlistentry>
     1989              <varlistentry>
     1990                <term>function</term>
     1991                <listitem>
     1992                      <para>a function, designated by itself or by a symbol
     1993                        which names it.</para>
     1994                </listitem>
     1995              </varlistentry>
     1996              <varlistentry>
     1997                <term>args</term>
     1998                <listitem>
     1999                      <para>a list of values, appropriate as arguments to
     2000                        <varname>function</varname>.</para>
     2001                </listitem>
     2002              </varlistentry>
     2003              <varlistentry>
     2004                <term>result</term>
     2005                <listitem>
     2006                      <para>T if <function>process-wait-with-timeout</function>
     2007                        returned because its <varname>function</varname> returned
     2008                        true, or NIL if it returned because the duration
     2009                        <varname>ticks</varname> has been exceeded.</para>
     2010                </listitem>
     2011              </varlistentry>
     2012            </variablelist>
     2013          </refsect1>
     2014
     2015          <refsect1>
     2016            <title>Description</title>
     2017
     2018            <para>If <varname>ticks</varname> is NIL, behaves exactly like
     2019              <xref linkend="f_process-wait"/>, except for returning T.
     2020              Otherwise, <varname>function</varname> will be tested repeatedly,
     2021              in the same
     2022              kind of test/yield loop as in <xref linkend="f_process-wait"/>>
     2023              until either <varname>function</varname> returns true,
     2024              or the duration <varname>ticks</varname> has been exceeded.
     2025            </para>
     2026
     2027            <para> Having already read the descriptions of
     2028              <xref linkend="f_process-allow-schedule"/> and
     2029              <xref linkend="f_process-wait"/>, the
     2030              astute reader has no doubt anticipated the observation that
     2031              better alternatives should be used whenever possible.</para>
     2032          </refsect1>
     2033
     2034          <refsect1>
     2035            <title>See Also</title>
     2036           
     2037            <simplelist type="inline">
     2038              <member><xref linkend="v_ticks-per-second"/></member>
     2039              <member><xref linkend="f_process-whostate"/></member>
     2040              <member><xref linkend="f_process-wait"/></member>
     2041              <member><xref linkend="f_make-lock"/></member>
     2042              <member><xref linkend="f_make-read-write-lock"/></member>
     2043              <member><xref linkend="f_make-semaphore"/></member>
     2044              <member><xref linkend="f_process-input-wait"/></member>
     2045              <member><xref linkend="f_process-output-wait"/></member>
     2046              <member><xref linkend="m_with-terminal-input"/></member>
     2047            </simplelist>
     2048          </refsect1>
     2049    </refentry>
     2050
     2051    <refentry id="m_without-interrupts">
     2052          <indexterm zone="m_without-interrupts">
     2053            <primary>without-interrupts</primary>
     2054          </indexterm>
     2055
     2056          <refnamediv>
     2057            <refname>WITHOUT-INTERRUPTS</refname>
     2058            <refpurpose>Evaluates its body in an environment in which
     2059              process-interrupt requests are deferred.</refpurpose>
     2060            <refclass>Macro</refclass>
     2061          </refnamediv>
     2062
     2063          <refsynopsisdiv>
     2064            <synopsis><function>without-interrupts</function>
     2065              &body; body => result</synopsis>
     2066          </refsynopsisdiv>
     2067
     2068          <refsect1>
     2069            <title>Arguments and Values</title>
     2070
     2071            <variablelist>
     2072              <varlistentry>
     2073                <term>body</term>
     2074                <listitem>
     2075                      <para>an implicit progn.</para>
     2076                </listitem>
     2077              </varlistentry>
     2078              <varlistentry>
     2079                <term>result</term>
     2080                <listitem>
     2081                      <para>the primary value returned by
     2082                        <varname>body</varname>.</para>
     2083                </listitem>
     2084              </varlistentry>
     2085            </variablelist>
     2086          </refsect1>
     2087
     2088          <refsect1>
     2089            <title>Description</title>
     2090
     2091            <para>Executes <varname>body</varname>
     2092              in an environment in which <xref linkend="f_process-interrupt"/>
     2093              requests are
     2094              deferred. As noted in the description of
     2095              <xref linkend="f_process-interrupt"/>, this has nothing to do
     2096              with the
     2097              scheduling of other threads; it may be necessary to inhibit
     2098              <xref linkend="f_process-interrupt"/> handling when
     2099              (for instance) modifying some data
     2100              structure (for which the current thread holds an appropriate lock)
     2101              in some manner that&#39;s not reentrant.</para>
     2102          </refsect1>
     2103
     2104          <refsect1>
     2105            <title>See Also</title>
     2106           
     2107            <simplelist type="inline">
     2108              <member><xref linkend="f_process-interrupt"/></member>
     2109            </simplelist>
     2110          </refsect1>
     2111    </refentry>
     2112
     2113    <refentry id="f_make-lock">
     2114          <indexterm zone="f_make-lock">
     2115            <primary>make-lock</primary>
     2116          </indexterm>
     2117
     2118          <refnamediv>
     2119            <refname>MAKE-LOCK</refname>
     2120            <refpurpose>Creates and returns a lock object, which can
     2121              be used for synchronization between threads.</refpurpose>
     2122            <refclass>Function</refclass>
     2123          </refnamediv>
     2124
     2125          <refsynopsisdiv>
     2126            <synopsis><function>make-lock</function> &optional;
     2127              name => lock</synopsis>
     2128          </refsynopsisdiv>
     2129
     2130          <refsect1>
     2131            <title>Arguments and Values</title>
     2132
     2133            <variablelist>
     2134              <varlistentry>
     2135                <term>name</term>
     2136                <listitem>
     2137                      <para>any lisp object; saved as part of
     2138                        <varname>lock</varname>.  Typically a string or symbol
     2139                        which may appear in the <xref linkend="f_process-whostate"/>s
     2140                        of threads which are waiting for <varname>lock</varname>.
     2141                      </para>
     2142                </listitem>
     2143              </varlistentry>
     2144              <varlistentry>
     2145                <term>lock</term>
     2146                <listitem>
     2147                      <para>a newly-allocated object of type CCL:LOCK.</para>
     2148                </listitem>
     2149              </varlistentry>
     2150            </variablelist>
     2151          </refsect1>
     2152
     2153          <refsect1>
     2154            <title>Description</title>
     2155
     2156            <para>Creates and returns a lock object, which can
     2157              be used to synchronize access to some shared resource.
     2158              <varname>lock</varname> is
     2159              initially in a &#34;free&#34; state; a lock can also be
     2160              &#34;owned&#34; by a
     2161              thread.</para>
     2162          </refsect1>
     2163
     2164          <refsect1>
     2165            <title>See Also</title>
     2166           
     2167            <simplelist type="inline">
     2168              <member><xref linkend="m_with-lock-grabbed"/></member>
     2169              <member><xref linkend="f_grab-lock"/></member>
     2170              <member><xref linkend="f_release-lock"/></member>
     2171              <member><xref linkend="f_try-lock"/></member>
     2172              <member><xref linkend="f_make-read-write-lock"/></member>
     2173              <member><xref linkend="f_make-semaphore"/></member>
     2174              <member><xref linkend="f_process-input-wait"/></member>
     2175              <member><xref linkend="f_process-output-wait"/></member>
     2176              <member><xref linkend="m_with-terminal-input"/></member>
     2177            </simplelist>
     2178          </refsect1>
     2179    </refentry>
     2180
     2181    <refentry id="m_with-lock-grabbed">
     2182          <indexterm zone="m_with-lock-grabbed">
     2183            <primary>with-lock-grabbed</primary>
     2184          </indexterm>
     2185
     2186          <refnamediv>
     2187            <refname>WITH-LOCK-GRABBED</refname>
     2188            <refpurpose>Waits until a given lock can be obtained, then
     2189              evaluates its body with the lock held.</refpurpose>
     2190            <refclass>Macro</refclass>
     2191          </refnamediv>
     2192
     2193          <refsynopsisdiv>
     2194            <synopsis><function>with-lock-grabbed</function>
     2195              (lock) &body; body</synopsis>
     2196          </refsynopsisdiv>
     2197
     2198          <refsect1>
     2199            <title>Arguments and Values</title>
     2200
     2201            <variablelist>
     2202              <varlistentry>
     2203                <term>lock</term>
     2204                <listitem>
     2205                      <para>an object of type CCL:LOCK.</para>
     2206                </listitem>
     2207              </varlistentry>
     2208              <varlistentry>
     2209                <term>body</term>
     2210                <listitem>
     2211                      <para>an implicit progn.</para>
     2212                </listitem>
     2213              </varlistentry>
     2214              <varlistentry>
     2215                <term>result</term>
     2216                <listitem>
     2217                      <para>the primary value returned by
     2218                        <varname>body</varname>.</para>
     2219                </listitem>
     2220              </varlistentry>
     2221            </variablelist>
     2222          </refsect1>
     2223
     2224          <refsect1>
     2225            <title>Description</title>
     2226
     2227            <para>Waits until <varname>lock</varname> is either free or
     2228              owned by the calling
     2229              thread, then executes <varname>body</varname> with the
     2230              lock owned by the calling thread. If <varname>lock</varname>
     2231              was free when <function>with-lock-grabbed</function> was called,
     2232              it is restored to a free state after <varname>body</varname>
     2233              is executed.</para>
     2234          </refsect1>
     2235
     2236          <refsect1>
     2237            <title>See Also</title>
     2238           
     2239            <simplelist type="inline">
     2240              <member><xref linkend="f_make-lock"/></member>
     2241              <member><xref linkend="f_grab-lock"/></member>
     2242              <member><xref linkend="f_release-lock"/></member>
     2243              <member><xref linkend="f_try-lock"/></member>
     2244              <member><xref linkend="f_make-read-write-lock"/></member>
     2245              <member><xref linkend="f_make-semaphore"/></member>
     2246              <member><xref linkend="f_process-input-wait"/></member>
     2247              <member><xref linkend="f_process-output-wait"/></member>
     2248              <member><xref linkend="m_with-terminal-input"/></member>
     2249            </simplelist>
     2250          </refsect1>
     2251    </refentry>
     2252
     2253    <refentry id="f_grab-lock">
     2254          <indexterm zone="f_grab-lock">
     2255            <primary>grab-lock</primary>
     2256          </indexterm>
     2257
     2258          <refnamediv>
     2259            <refname>GRAB-LOCK</refname>
     2260            <refpurpose>Waits until a given lock can be obtained, then
     2261              obtains it.</refpurpose>
     2262            <refclass>Function</refclass>
     2263          </refnamediv>
     2264
     2265          <refsynopsisdiv>
     2266            <synopsis><function>grab-lock</function> lock</synopsis>
     2267          </refsynopsisdiv>
     2268
     2269          <refsect1>
     2270            <title>Arguments and Values</title>
     2271
     2272            <variablelist>
     2273              <varlistentry>
     2274                <term>lock</term>
     2275                <listitem>
     2276                      <para>an object of type CCL:LOCK.</para>
     2277                </listitem>
     2278              </varlistentry>
     2279            </variablelist>
     2280          </refsect1>
     2281
     2282          <refsect1>
     2283            <title>Description</title>
     2284
     2285            <para>Blocks until <varname>lock</varname> is owned by the
     2286              calling thread.</para>
     2287
     2288            <para>The macro <xref linkend="m_with-lock-grabbed"/>
     2289              <emphasis>could</emphasis> be defined in
     2290              terms of <function>grab-lock</function> and
     2291              <xref linkend="f_release-lock"/>, but it is actually
     2292              implemented at a slightly lower level.</para>
     2293          </refsect1>
     2294
     2295          <refsect1>
     2296            <title>See Also</title>
     2297           
     2298            <simplelist type="inline">
     2299              <member><xref linkend="f_make-lock"/></member>
     2300              <member><xref linkend="m_with-lock-grabbed"/></member>
     2301              <member><xref linkend="f_release-lock"/></member>
     2302              <member><xref linkend="f_try-lock"/></member>
     2303              <member><xref linkend="f_make-read-write-lock"/></member>
     2304              <member><xref linkend="f_make-semaphore"/></member>
     2305              <member><xref linkend="f_process-input-wait"/></member>
     2306              <member><xref linkend="f_process-output-wait"/></member>
     2307              <member><xref linkend="m_with-terminal-input"/></member>
     2308            </simplelist>
     2309          </refsect1>
     2310    </refentry>
     2311
     2312    <refentry id="f_release-lock">
     2313          <indexterm zone="f_release-lock">
     2314            <primary>release-lock</primary>
     2315          </indexterm>
     2316
     2317          <refnamediv>
     2318            <refname>RELEASE-LOCK</refname>
     2319            <refpurpose>Relinquishes ownership of a given lock.</refpurpose>
     2320            <refclass>Function</refclass>
     2321          </refnamediv>
     2322
     2323          <refsynopsisdiv>
     2324            <synopsis><function>release-lock</function> lock</synopsis>
     2325          </refsynopsisdiv>
     2326
     2327          <refsect1>
     2328            <title>Arguments and Values</title>
     2329
     2330            <variablelist>
     2331              <varlistentry>
     2332                <term>lock</term>
     2333                <listitem>
     2334                      <para>an object of type CCL:LOCK.</para>
     2335                </listitem>
     2336              </varlistentry>
     2337            </variablelist>
     2338          </refsect1>
     2339
     2340          <refsect1>
     2341            <title>Description</title>
     2342
     2343            <para>Signals an error of type CCL:LOCK-NOT-OWNER if
     2344              <varname>lock</varname>
     2345              is not already owned by the calling thread; otherwise, undoes the
     2346              effect of one previous
     2347              <xref linkend="f_grab-lock"/>.  If this means that
     2348              <function>release-lock</function> has now been called on
     2349              <varname>lock</varname> the same number of times as
     2350              <xref linkend="f_grab-lock"/> has, <varname>lock</varname>
     2351              becomes free.</para>
     2352          </refsect1>
     2353
     2354          <refsect1>
     2355            <title>See Also</title>
     2356           
     2357            <simplelist type="inline">
     2358              <member><xref linkend="f_make-lock"/></member>
     2359              <member><xref linkend="m_with-lock-grabbed"/></member>
     2360              <member><xref linkend="f_grab-lock"/></member>
     2361              <member><xref linkend="f_try-lock"/></member>
     2362              <member><xref linkend="f_make-read-write-lock"/></member>
     2363              <member><xref linkend="f_make-semaphore"/></member>
     2364              <member><xref linkend="f_process-input-wait"/></member>
     2365              <member><xref linkend="f_process-output-wait"/></member>
     2366              <member><xref linkend="m_with-terminal-input"/></member>
     2367            </simplelist>
     2368          </refsect1>
     2369    </refentry>
     2370
     2371    <refentry id="f_try-lock">
     2372          <indexterm zone="f_try-lock">
     2373            <primary>try-lock</primary>
     2374          </indexterm>
     2375
     2376          <refnamediv>
     2377            <refname>TRY-LOCK</refname>
     2378            <refpurpose>Obtains the given lock, but only if it is not
     2379              necessary to wait for it.</refpurpose>
     2380            <refclass>Function</refclass>
     2381          </refnamediv>
     2382
     2383          <refsynopsisdiv>
     2384            <synopsis><function>try-lock</function> lock => result</synopsis>
     2385          </refsynopsisdiv>
     2386
     2387          <refsect1>
     2388            <title>Arguments and Values</title>
     2389
     2390            <variablelist>
     2391              <varlistentry>
     2392                <term>lock</term>
     2393                <listitem>
     2394                      <para>an object of type CCL:LOCK.</para>
     2395                </listitem>
     2396              </varlistentry>
     2397              <varlistentry>
     2398                <term>result</term>
     2399                <listitem>
     2400                      <para>T if <varname>lock</varname> has been obtained,
     2401                        or NIL if it has not.</para>
     2402                </listitem>
     2403              </varlistentry>
     2404            </variablelist>
     2405          </refsect1>
     2406
     2407          <refsect1>
     2408            <title>Description</title>
     2409
     2410            <para>Tests whether <varname>lock</varname>
     2411              can be obtained without blocking - that is, either
     2412              <varname>lock</varname> is already free, or it is already owned
     2413              by <xref linkend="v_current-process"/>.  If it can,
     2414              causes it to
     2415              be owned by the calling lisp process (thread) and returns T.
     2416              Otherwise, the lock
     2417              is already owned by another thread and cannot be obtained without
     2418              blocking; NIL is returned in this case.</para>
     2419          </refsect1>
     2420
     2421          <refsect1>
     2422            <title>See Also</title>
     2423           
     2424            <simplelist type="inline">
     2425              <member><xref linkend="f_make-lock"/></member>
     2426              <member><xref linkend="m_with-lock-grabbed"/></member>
     2427              <member><xref linkend="f_grab-lock"/></member>
     2428              <member><xref linkend="f_release-lock"/></member>
     2429              <member><xref linkend="f_make-read-write-lock"/></member>
     2430              <member><xref linkend="f_make-semaphore"/></member>
     2431              <member><xref linkend="f_process-input-wait"/></member>
     2432              <member><xref linkend="f_process-output-wait"/></member>
     2433              <member><xref linkend="m_with-terminal-input"/></member>
     2434            </simplelist>
     2435          </refsect1>
     2436    </refentry>
     2437
     2438    <refentry id="f_make-read-write-lock">
     2439          <indexterm zone="f_make-read-write-lock">
     2440            <primary>make-read-write-lock</primary>
     2441          </indexterm>
     2442
     2443          <refnamediv>
     2444            <refname>MAKE-READ-WRITE-LOCK</refname>
     2445            <refpurpose>Creates and returns a read-write lock, which can
     2446              be used for synchronization between threads.</refpurpose>
     2447            <refclass>Function</refclass>
     2448          </refnamediv>
     2449
     2450          <refsynopsisdiv>
     2451            <synopsis><function>make-read-write-lock</function>
     2452              => read-write-lock</synopsis>
     2453          </refsynopsisdiv>
     2454
     2455          <refsect1>
     2456            <title>Arguments and Values</title>
     2457
     2458            <variablelist>
     2459              <varlistentry>
     2460                <term>read-write-lock</term>
     2461                <listitem>
     2462                      <para>a newly-allocated object of type
     2463                        CCL:READ-WRITE-LOCK.</para>
     2464                </listitem>
     2465              </varlistentry>
     2466            </variablelist>
     2467          </refsect1>
     2468
     2469          <refsect1>
     2470            <title>Description</title>
     2471
     2472            <para>Creates and returns an object of type CCL::READ-WRITE-LOCK.
     2473              A read-write lock may, at any given time, belong to any number
     2474              of lisp processes (threads) which act as "readers"; or, it may
     2475              belong to at most one process which acts as a "writer".  A
     2476              read-write lock may never be held by a reader at the same time as
     2477              a writer.  Initially, <varname>read-write-lock</varname> has
     2478              no readers and no writers.</para>
     2479          </refsect1>
     2480
     2481          <refsect1>
     2482            <title>See Also</title>
     2483           
     2484            <simplelist type="inline">
     2485              <member><xref linkend="m_with-read-lock"/></member>
     2486              <member><xref linkend="m_with-write-lock"/></member>
     2487              <member><xref linkend="f_make-lock"/></member>
     2488              <member><xref linkend="f_make-semaphore"/></member>
     2489              <member><xref linkend="f_process-input-wait"/></member>
     2490              <member><xref linkend="f_process-output-wait"/></member>
     2491              <member><xref linkend="m_with-terminal-input"/></member>
     2492            </simplelist>
     2493          </refsect1>
     2494
     2495          <refsect1>
     2496            <title>Notes</title>
     2497
     2498            <para>There probably should be some way to
     2499              atomically &#34;promote&#34; a reader, making it a writer without
     2500              releasing the lock, which could otherwise cause delay.</para>
     2501          </refsect1>
     2502    </refentry>
     2503
     2504    <refentry id="m_with-read-lock">
     2505          <indexterm zone="m_with-read-lock">
     2506            <primary>with-read-lock</primary>
     2507          </indexterm>
     2508
     2509          <refnamediv>
     2510            <refname>WITH-READ-LOCK</refname>
     2511            <refpurpose>Waits until a given lock is available for
     2512              read-only access, then evaluates its body with the lock
     2513              held.</refpurpose>
     2514            <refclass>Macro</refclass>
     2515          </refnamediv>
     2516
     2517          <refsynopsisdiv>
     2518            <synopsis><function>with-read-lock</function>
     2519              (read-write-lock) &body; body => result</synopsis>
     2520          </refsynopsisdiv>
     2521
     2522          <refsect1>
     2523            <title>Arguments and Values</title>
     2524
     2525            <variablelist>
     2526              <varlistentry>
     2527                <term>read-write-lock</term>
     2528                <listitem>
     2529                      <para>an object of type
     2530                        CCL:READ-WRITE-LOCK.</para>
     2531                </listitem>
     2532              </varlistentry>
     2533              <varlistentry>
     2534                <term>body</term>
     2535                <listitem>
     2536                      <para>an implicit progn.</para>
     2537                </listitem>
     2538              </varlistentry>
     2539              <varlistentry>
     2540                <term>result</term>
     2541                <listitem>
     2542                      <para>the primary value returned by
     2543                        <varname>body</varname>.</para>
     2544                </listitem>
     2545              </varlistentry>
     2546            </variablelist>
     2547          </refsect1>
     2548
     2549          <refsect1>
     2550            <title>Description</title>
     2551
     2552            <para>Waits until <varname>read-write-lock</varname> has no
     2553              writer,
     2554              ensures that <xref linkend="v_current-process"/> is a
     2555              reader of it, then executes <varname>body</varname>.
     2556            </para>
     2557
     2558            <para>After executing <varname>body</varname>, if
     2559              <xref linkend="v_current-process"/> was not a reader of
     2560              <varname>read-write-lock</varname> before
     2561              <function>with-read-lock</function> was called, the lock is
     2562              released.  If it was already a reader, it remains one.</para>
     2563          </refsect1>
     2564
     2565          <refsect1>
     2566            <title>See Also</title>
     2567           
     2568            <simplelist type="inline">
     2569              <member><xref linkend="f_make-read-write-lock"/></member>
     2570              <member><xref linkend="m_with-write-lock"/></member>
     2571              <member><xref linkend="f_make-lock"/></member>
     2572              <member><xref linkend="f_make-semaphore"/></member>
     2573              <member><xref linkend="f_process-input-wait"/></member>
     2574              <member><xref linkend="f_process-output-wait"/></member>
     2575              <member><xref linkend="m_with-terminal-input"/></member>
     2576            </simplelist>
     2577          </refsect1>
     2578    </refentry>
     2579
     2580    <refentry id="m_with-write-lock">
     2581          <indexterm zone="m_with-write-lock">
     2582            <primary>with-write-lock</primary>
     2583          </indexterm>
     2584
     2585          <refnamediv>
     2586            <refname>WITH-WRITE-LOCK</refname>
     2587            <refpurpose>Waits until the given lock is available for write
     2588              access, then executes its body with the lock held.</refpurpose>
     2589            <refclass>Macro</refclass>
     2590          </refnamediv>
     2591
     2592          <refsynopsisdiv>
     2593            <synopsis><function>with-write-lock</function>
     2594              (read-write-lock) &body; body</synopsis>
     2595          </refsynopsisdiv>
     2596
     2597          <refsect1>
     2598            <title>Arguments and Values</title>
     2599
     2600            <variablelist>
     2601              <varlistentry>
     2602                <term>read-write-lock</term>
     2603                <listitem>
     2604                      <para>an object of type
     2605                        CCL:READ-WRITE-LOCK.</para>
     2606                </listitem>
     2607              </varlistentry>
     2608              <varlistentry>
     2609                <term>body</term>
     2610                <listitem>
     2611                      <para>an implicit progn.</para>
     2612                </listitem>
     2613              </varlistentry>
     2614              <varlistentry>
     2615                <term>result</term>
     2616                <listitem>
     2617                      <para>the primary value returned by
     2618                        <varname>body</varname>.</para>
     2619                </listitem>
     2620              </varlistentry>
     2621            </variablelist>
     2622          </refsect1>
     2623
     2624          <refsect1>
     2625            <title>Description</title>
     2626
     2627            <para>Waits until <varname>read-write-lock</varname> has no
     2628              readers and no writer other than <xref linkend="v_current-process"/>,
     2629              then ensures that <xref linkend="v_current-process"/> is the
     2630              writer of it.  With the lock held, executes <varname>body</varname>.
     2631            </para>
     2632
     2633            <para>After executing <varname>body</varname>, if
     2634              <xref linkend="v_current-process"/> was not the writer of
     2635              <varname>read-write-lock</varname> before
     2636              <function>with-write-lock</function> was called, the lock is
     2637              released.  If it was already the writer, it remains the
     2638              writer.</para>
     2639          </refsect1>
     2640
     2641          <refsect1>
     2642            <title>See Also</title>
     2643           
     2644            <simplelist type="inline">
     2645              <member><xref linkend="f_make-read-write-lock"/></member>
     2646              <member><xref linkend="m_with-read-lock"/></member>
     2647              <member><xref linkend="f_make-lock"/></member>
     2648              <member><xref linkend="f_make-semaphore"/></member>
     2649              <member><xref linkend="f_process-input-wait"/></member>
     2650              <member><xref linkend="f_process-output-wait"/></member>
     2651              <member><xref linkend="m_with-terminal-input"/></member>
     2652            </simplelist>
     2653          </refsect1>
     2654    </refentry>
     2655
     2656    <refentry id="f_make-semaphore">
     2657          <indexterm zone="f_make-semaphore">
     2658            <primary>make-semaphore</primary>
     2659          </indexterm>
     2660
     2661          <refnamediv>
     2662            <refname>MAKE-SEMAPHORE</refname>
     2663            <refpurpose>Creates and returns a semaphore, which can be used
     2664              for synchronization between threads.</refpurpose>
     2665            <refclass>Function</refclass>
     2666          </refnamediv>
     2667
     2668          <refsynopsisdiv>
     2669            <synopsis><function>make-semaphore</function>
     2670              => semaphore</synopsis>
     2671          </refsynopsisdiv>
     2672
     2673          <refsect1>
     2674            <title>Arguments and Values</title>
     2675           
     2676            <variablelist>
     2677              <varlistentry>
     2678                <term>semaphore</term>
     2679                <listitem>
     2680                      <para>a newly-allocated object of type CCL:SEMAPHORE.</para>
     2681                </listitem>
     2682              </varlistentry>
     2683            </variablelist>
     2684          </refsect1>
     2685
     2686          <refsect1>
     2687            <title>Description</title>
     2688
     2689            <para>Creates and returns an object of type CCL:SEMAPHORE.
     2690              A semaphore has an associated "count" which may be incremented
     2691              and decremented atomically; incrementing it represents sending
     2692              a signal, and decrementing it represents handling that signal.
     2693              <varname>semaphore</varname> has an initial count of 0.</para>
     2694          </refsect1>
     2695
     2696          <refsect1>
     2697            <title>See Also</title>
     2698           
     2699            <simplelist type="inline">
     2700              <member><xref linkend="f_signal-semaphore"/></member>
     2701              <member><xref linkend="f_wait-on-semaphore"/></member>
     2702              <member><xref linkend="f_timed-wait-on-semaphore"/></member>
     2703              <member><xref linkend="f_make-lock"/></member>
     2704              <member><xref linkend="f_make-read-write-lock"/></member>
     2705              <member><xref linkend="f_process-input-wait"/></member>
     2706              <member><xref linkend="f_process-output-wait"/></member>
     2707              <member><xref linkend="m_with-terminal-input"/></member>
     2708            </simplelist>
     2709          </refsect1>
     2710    </refentry>
     2711
     2712    <refentry id="f_signal-semaphore">
     2713          <indexterm zone="f_signal-semaphore">
     2714            <primary>signal-semaphore</primary>
     2715          </indexterm>
     2716
     2717          <refnamediv>
     2718            <refname>SIGNAL-SEMAPHORE</refname>
     2719            <refpurpose>Atomically increments the count of a given
     2720              semaphore.</refpurpose>
     2721            <refclass>Function</refclass>
     2722          </refnamediv>
     2723
     2724          <refsynopsisdiv>
     2725            <synopsis><function>signal-semaphore</function>
     2726              semaphore => result</synopsis>
     2727          </refsynopsisdiv>
     2728
     2729          <refsect1>
     2730            <title>Arguments and Values</title>
     2731           
     2732            <variablelist>
     2733              <varlistentry>
     2734                <term>semaphore</term>
     2735                <listitem>
     2736                      <para>an object of type CCL:SEMAPHORE.</para>
     2737                </listitem>
     2738              </varlistentry>
     2739              <varlistentry>
     2740                <term>result</term>
     2741                <listitem>
     2742                      <para>an integer representing an error identifier
     2743                        which was returned by the underlying OS call.</para>
     2744                </listitem>
     2745              </varlistentry>
     2746            </variablelist>
     2747          </refsect1>
     2748
     2749          <refsect1>
     2750            <title>Description</title>
     2751
     2752            <para>Atomically increments <varname>semaphore</varname>'s
     2753              "count" by 1; this
     2754              may enable a waiting thread to resume execution.</para>
     2755          </refsect1>
     2756
     2757          <refsect1>
     2758            <title>See Also</title>
     2759           
     2760            <simplelist type="inline">
     2761              <member><xref linkend="f_make-semaphore"/></member>
     2762              <member><xref linkend="f_wait-on-semaphore"/></member>
     2763              <member><xref linkend="f_timed-wait-on-semaphore"/></member>
     2764              <member><xref linkend="f_make-lock"/></member>
     2765              <member><xref linkend="f_make-read-write-lock"/></member>
     2766              <member><xref linkend="f_process-input-wait"/></member>
     2767              <member><xref linkend="f_process-output-wait"/></member>
     2768              <member><xref linkend="m_with-terminal-input"/></member>
     2769            </simplelist>
     2770          </refsect1>
     2771
     2772          <refsect1>
     2773            <title>Notes</title>
     2774
     2775            <para><varname>result</varname> should probably be interpreted
     2776              and acted on by <function>signal-semaphore</function>, because
     2777              it is not likely to be meaningful to a lisp program, and the
     2778              most common cause of failure is a type error.</para>
     2779          </refsect1>
     2780    </refentry>
     2781
     2782    <refentry id="f_wait-on-semaphore">
     2783          <indexterm zone="f_wait-on-semaphore">
     2784            <primary>wait-on-semaphore</primary>
     2785          </indexterm>
     2786
     2787          <refnamediv>
     2788            <refname>WAIT-ON-SEMAPHORE</refname>
     2789            <refpurpose>Waits until the given semaphore has a positive
     2790              count which can be atomically decremented.</refpurpose>
     2791            <refclass>Function</refclass>
     2792          </refnamediv>
     2793
     2794          <refsynopsisdiv>
     2795            <synopsis><function>wait-on-semaphore</function>
     2796              semaphore => result</synopsis>
     2797          </refsynopsisdiv>
     2798
     2799          <refsect1>
     2800            <title>Arguments and Values</title>
     2801           
     2802            <variablelist>
     2803              <varlistentry>
     2804                <term>semaphore</term>
     2805                <listitem>
     2806                      <para>an object of type CCL:SEMAPHORE.</para>
     2807                </listitem>
     2808              </varlistentry>
     2809              <varlistentry>
     2810                <term>result</term>
     2811                <listitem>
     2812                      <para>an integer representing an error identifier
     2813                        which was returned by the underlying OS call.</para>
     2814                </listitem>
     2815              </varlistentry>
     2816            </variablelist>
     2817          </refsect1>
     2818
     2819          <refsect1>
     2820            <title>Description</title>
     2821
     2822            <para>Waits until <varname>semaphore</varname>
     2823              has a positive count that can be
     2824              atomically decremented; this will succeed exactly once for each
     2825              corresponding call to SIGNAL-SEMAPHORE.</para>
     2826          </refsect1>
     2827
     2828          <refsect1>
     2829            <title>See Also</title>
     2830           
     2831            <simplelist type="inline">
     2832              <member><xref linkend="f_make-semaphore"/></member>
     2833              <member><xref linkend="f_signal-semaphore"/></member>
     2834              <member><xref linkend="f_timed-wait-on-semaphore"/></member>
     2835              <member><xref linkend="f_make-lock"/></member>
     2836              <member><xref linkend="f_make-read-write-lock"/></member>
     2837              <member><xref linkend="f_process-input-wait"/></member>
     2838              <member><xref linkend="f_process-output-wait"/></member>
     2839              <member><xref linkend="m_with-terminal-input"/></member>
     2840            </simplelist>
     2841          </refsect1>
     2842
     2843          <refsect1>
     2844            <title>Notes</title>
     2845
     2846            <para><varname>result</varname> should probably be interpreted
     2847              and acted on by <function>wait-on-semaphore</function>, because
     2848              it is not likely to be meaningful to a lisp program, and the
     2849              most common cause of failure is a type error.</para>
     2850          </refsect1>
     2851    </refentry>
     2852
     2853    <refentry id="f_timed-wait-on-semaphore">
     2854          <indexterm zone="f_timed-wait-on-semaphore">
     2855            <primary>timed-wait-on-semaphore</primary>
     2856          </indexterm>
     2857
     2858          <refnamediv>
     2859            <refname>TIMED-WAIT-ON-SEMAPHORE</refname>
     2860            <refpurpose>Waits until the given semaphore has a positive
     2861              count which can be atomically decremented, or until a timeout
     2862              expires.</refpurpose>
     2863            <refclass>Function</refclass>
     2864          </refnamediv>
     2865
     2866          <refsynopsisdiv>
     2867            <synopsis><function>timed-wait-on-semaphore</function>
     2868              semaphore timeout => result</synopsis>
     2869          </refsynopsisdiv>
     2870
     2871          <refsect1>
     2872            <title>Arguments and Values</title>
     2873           
     2874            <variablelist>
     2875              <varlistentry>
     2876                <term>semaphore</term>
     2877                <listitem>
     2878                      <para>An object of type CCL:SEMAPHORE.</para>
     2879                </listitem>
     2880              </varlistentry>
     2881              <varlistentry>
     2882                <term>timeout</term>
     2883                <listitem>
     2884                      <para>a time interval in seconds.  May be any
     2885                        non-negative real number the <function>floor</function> of
     2886                        which fits in 32 bits.  The default is 1.</para>
     2887                </listitem>
     2888              </varlistentry>
     2889              <varlistentry>
     2890                <term>result</term>
     2891                <listitem>
     2892                      <para>T if <function>timed-wait-on-semaphore</function>
     2893                        returned because it was able to decrement the count of
     2894                        <varname>semaphore</varname>; NIL if it returned because
     2895                        the duration <varname>timeout</varname> has been
     2896                        exceeded.</para>
     2897                </listitem>
     2898              </varlistentry>
     2899            </variablelist>
     2900          </refsect1>
     2901
     2902          <refsect1>
     2903            <title>Description</title>
     2904
     2905            <para>Waits until <varname>semaphore</varname>
     2906              has a positive count that can be
     2907              atomically decremented, or until the duration
     2908              <varname>timeout</varname> has
     2909              elapsed.</para>
     2910          </refsect1>
     2911
     2912          <refsect1>
     2913            <title>See Also</title>
     2914           
     2915            <simplelist type="inline">
     2916              <member><xref linkend="f_make-semaphore"/></member>
     2917              <member><xref linkend="f_wait-on-semaphore"/></member>
     2918              <member><xref linkend="f_make-lock"/></member>
     2919              <member><xref linkend="f_make-read-write-lock"/></member>
     2920              <member><xref linkend="f_process-input-wait"/></member>
     2921              <member><xref linkend="f_process-output-wait"/></member>
     2922              <member><xref linkend="m_with-terminal-input"/></member>
     2923            </simplelist>
     2924          </refsect1>
     2925    </refentry>
     2926
     2927    <refentry id="f_process-input-wait">
     2928          <indexterm zone="f_process-input-wait">
     2929            <primary>process-input-wait</primary>
     2930          </indexterm>
     2931
     2932          <refnamediv>
     2933            <refname>PROCESS-INPUT-WAIT</refname>
     2934            <refpurpose>Waits until input is available on a given
     2935              file-descriptor.</refpurpose>
     2936            <refclass>Function</refclass>
     2937          </refnamediv>
     2938
     2939          <refsynopsisdiv>
     2940            <synopsis><function>process-input-wait</function>
     2941              fd &optional; timeout</synopsis>
     2942          </refsynopsisdiv>
     2943
     2944          <refsect1>
     2945            <title>Arguments and Values</title>
     2946           
     2947            <variablelist>
     2948              <varlistentry>
     2949                <term>fd</term>
     2950                <listitem>
     2951                      <para>a file descriptor, which is a non-negative integer
     2952                        used by the OS to refer to an open file, socket, or similar
     2953                        I/O connection.  See <xref linkend="f_stream-device"/>.</para>
     2954                </listitem>
     2955              </varlistentry>
     2956              <varlistentry>
     2957                <term>timeout</term>
     2958                <listitem>
     2959                      <para>either NIL or a time interval in milliseconds.  Must be a non-negative integer.  The default is NIL.</para>
     2960                </listitem>
     2961              </varlistentry>
     2962            </variablelist>
     2963          </refsect1>
     2964
     2965          <refsect1>
     2966            <title>Description</title>
     2967
     2968            <para>Wait until input is available on <varname>fd</varname>.
     2969              This uses the <function>select()</function> system call, and is
     2970              generally a fairly
     2971              efficient way of blocking while waiting for input. More
     2972              accurately, <function>process-input-wait</function>
     2973              waits until it&#39;s possible to read
     2974              from fd without blocking, or until <varname>timeout</varname>, if
     2975              it is not NIL, has been exceeded.</para>
     2976
     2977            <para>
     2978              Note that it&#39;s possible to read without blocking if
     2979              the file is at its end - although, of course, the read will
     2980              return zero bytes.</para>
     2981          </refsect1>
    6612982         
    662           <variablelist>
    663             <varlistentry>
    664               <term>name</term>
    665              
    666               <listitem>
    667                 <para>a string, used to identify the process.</para>
    668               </listitem>
    669             </varlistentry>
    670            
    671             <varlistentry>
    672               <term>persistent</term>
    673              
    674               <listitem>
    675                 <para>if true, requests that information about the process
    676                 be retained by SAVE-APPLICATION so that an equivalent
    677                 process can be restarted when a saved image is run.  The
    678                 default is nil.</para>
    679               </listitem>
    680             </varlistentry>
    681            
    682             <varlistentry>
    683               <term>priority</term>
    684              
    685               <listitem>
    686                 <para>ignored.  It
    687                 shouldn't be ignored of course, but there are
    688                 complications on some platforms.  The default is 0.</para>
    689               </listitem>
    690             </varlistentry>
    691            
    692             <varlistentry>
    693               <term>class</term>
    694              
    695               <listitem>
    696                 <para>the class of process object to create;
    697                 should be a subclass of CCL:PROCESS.  The default is
    698                 CCL:PROCESS.</para>
    699               </listitem>
    700             </varlistentry>
    701            
    702             <varlistentry>
    703               <term>stack-size</term>
    704              
    705               <listitem>
    706                 <para>the size, in bytes, of the newly-created process's
    707                 control stack; used for foreign function calls and to save
    708                 function return address context.  The default is
    709                 CCL:*DEFAULT-CONTROL-STACK-SIZE*.</para>
    710               </listitem>
    711             </varlistentry>
    712            
    713             <varlistentry>
    714               <term>vstack-size</term>
    715              
    716               <listitem>
    717                 <para>the size, in bytes, of the newly-created process's
    718                 value stack; used for lisp function arguments, local
    719                 variables, and other stack-allocated lisp objects.
    720                 The default is CCL:*DEFAULT-VALUE-STACK-SIZE*.</para>
    721               </listitem>
    722             </varlistentry>
    723            
    724             <varlistentry>
    725               <term>tstack-size</term>
    726              
    727               <listitem>
    728                 <para>the size, in bytes, of the newly-created process's
    729                 temp stack; used for the allocation of dynamic-extent
    730                 objects.  The default is CCL:*DEFAULT-TEMP-STACK-SIZE*.</para>
    731               </listitem>
    732             </varlistentry>
    733            
    734             <varlistentry>
    735               <term>use-standard-initial-bindings</term>
    736              
    737               <listitem>
    738                 <para>when true, the global "standard initial
    739                 bindings" are put into effect in the new thread before. See
    740                 DEF-STANDARD-INITIAL-BINDING.  "standard" initial bindings
    741                 are put into effect before any bindings specified by
    742                 :initial-bindings are.  The default is t.</para>
    743               </listitem>
    744             </varlistentry>
    745            
    746             <varlistentry>
    747               <term>initial-bindings</term>
    748              
    749               <listitem>
    750                 <para>an alist of (<varname>symbol</varname> .
    751                 <varname>valueform</varname>) pairs, which can be
    752                 used to initialize special variable bindings in the new
    753                 thread. Each <varname>valueform</varname> is used to
    754                 compute the value of a new binding of
    755                 <varname>symbol</varname> in the execution environment of
    756                 the newly-created thread.  The default is nil.</para>
    757               </listitem>
    758             </varlistentry>
    759            
    760             <varlistentry>
    761               <term>process</term>
    762              
    763               <listitem>
    764                 <para>the newly-created process.</para>
    765               </listitem>
    766             </varlistentry>
    767           </variablelist>
    768         </refsect1>
    769 
    770         <refsect1>
    771           <title>Description</title>
    772 
    773           <para>Creates and returns a new lisp process (thread) with the
    774           specified attributes. <varname>process</varname> will not begin
    775           execution immediately; it will need to be
    776           <emphasis>preset</emphasis> (given
    777           an initial function to run, as by
    778           <xref linkend="f_process-preset"/>) and
    779           <emphasis>enabled</emphasis>
    780           (allowed to execute, as by <xref linkend="f_process-enable"/>)
    781           before it&#39;s able to actually do anything.</para>
    782 
    783           <para>If <varname>valueform</varname> is a function, it is
    784           called, with no arguments, in the execution environment of the
    785           newly-created thread; the primary value it returns is used for
    786           the binding of the corresponding <varname>symbol</varname>.</para>
    787 
    788           <para>Otherwise, <varname>valueform</varname> is evaluated in the
    789           execution
    790           environment of the newly-created thread, and the resulting value
    791           is used.</para>
    792         </refsect1>
    793 
    794         <refsect1>
    795           <title>See Also</title>
    796          
    797           <simplelist type="inline">
    798             <member><xref linkend="f_process-preset"/></member>
    799             <member><xref linkend="f_process-enable"/></member>
    800             <member><xref linkend="f_process-run-function"/></member>
    801           </simplelist>
    802         </refsect1>
    803       </refentry>
    804 
    805       <refentry id="f_process-suspend">
    806         <indexterm zone="f_process-suspend">
    807           <primary>process-suspend</primary>
    808         </indexterm>
    809 
    810         <refnamediv>
    811           <refname>PROCESS-SUSPEND</refname>
    812           <refpurpose>Suspends a specified process.</refpurpose>
    813           <refclass>Function</refclass>
    814         </refnamediv>
    815        
    816         <refsynopsisdiv>
    817           <synopsis><function>process-suspend</function> process
    818           => result</synopsis>
    819         </refsynopsisdiv>
    820 
    821         <refsect1>
    822           <title>Arguments and Values</title>
    823          
    824           <variablelist>
    825             <varlistentry>
    826               <term>process</term>
    827               <listitem>
    828                 <para>a lisp process (thread).</para>
    829               </listitem>
    830             </varlistentry>
    831             <varlistentry>
    832               <term>result</term>
    833               <listitem>
    834                 <para>T if <varname>process</varname> had been runnable
    835                 and is now suspended; NIL otherwise.  That is, T if
    836                 <varname>process</varname>'s
    837                 <xref linkend="f_process-suspend-count"/>
    838                 transitioned from 0 to 1.</para>
    839               </listitem>
    840             </varlistentry>
    841           </variablelist>
    842         </refsect1>
    843 
    844         <refsect1>
    845           <title>Description</title>
    846 
    847           <para>Suspends <varname>process</varname>, preventing it from
    848           running, and stopping it if it was already running. This is a fairly
    849           expensive operation, because it involves a few
    850           calls to the OS.  It also risks creating deadlock if used
    851           improperly, for instance, if the process being suspended owns a
    852           lock or other resource which another process will wait for.</para>
    853 
    854           <para>
    855           Each
    856           call to <function>process-suspend</function> must be reversed by
    857           a matching call to <xref linkend="f_process-resume"/>
    858           before <varname>process</varname> is able to run.  What
    859           <function>process-suspend</function> actually does is increment
    860           the <xref linkend="f_process-suspend-count"/> of
    861           <varname>process</varname>.
    862           </para>
    863 
    864           <para>A process can suspend itself; it it&#39;s successful in doing
    865           so, then it can obviously only be resumed by some other
    866           process.</para>
    867         </refsect1>
    868 
    869         <refsect1>
    870           <title>See Also</title>
    871          
    872           <simplelist type="inline">
    873             <member><xref linkend="f_process-resume"/></member>
    874             <member><xref linkend="f_process-suspend-count"/></member>
    875           </simplelist>
    876         </refsect1>
    877 
    878         <refsect1>
    879           <title>Notes</title>
    880           <para><function>process-suspend</function> was previously called
    881           <function>process-disable</function>.
    882           <xref linkend="f_process-enable"/>
    883           now names a function for which there is no
    884           obvious inverse, so <function>process-disable</function>
    885           is no longer
    886           defined.</para>
    887         </refsect1>
    888       </refentry>
    889 
    890       <refentry id="f_process-resume">
    891         <indexterm zone="f_process-resume">
    892           <primary>process-resume</primary>
    893         </indexterm>
    894 
    895         <refnamediv>
    896           <refname>PROCESS-RESUME</refname>
    897           <refpurpose>Resumes a specified process which had previously
    898           been suspended by process-suspend.</refpurpose>
    899           <refclass>Function</refclass>
    900         </refnamediv>
    901 
    902         <refsynopsisdiv>
    903           <synopsis><function>process-resume</function> process
    904           => result</synopsis>
    905         </refsynopsisdiv>
    906 
    907         <refsect1>
    908           <title>Arguments and Values</title>
    909          
    910           <variablelist>
    911             <varlistentry>
    912               <term>process</term>
    913               <listitem>
    914                 <para>a lisp process (thread).</para>
    915               </listitem>
    916             </varlistentry>
    917             <varlistentry>
    918               <term>result</term>
    919               <listitem>
    920                 <para>T if <varname>process</varname> had been suspended
    921                 and is now runnable; NIL otherwise.  That is, T if
    922                 <varname>process</varname>'s
    923                 <xref linkend="f_process-suspend-count"/>
    924                 transitioned from  to 0.
    925                 </para>
    926               </listitem>
    927             </varlistentry>
    928           </variablelist>
    929         </refsect1>
    930 
    931         <refsect1>
    932           <title>Description</title>
    933 
    934           <para>Undoes the effect of a previous call to
    935           <xref linkend="f_process-suspend"/>; if
    936           all such calls are undone, makes the process runnable. Has no
    937           effect if the process is not suspended.  What
    938           <function>process-resume</function> actually does is decrement
    939           the <xref linkend="f_process-suspend-count"/> of
    940           <varname>process</varname>, to a minimum of 0.</para>
    941         </refsect1>
    942 
    943         <refsect1>
    944           <title>See Also</title>
    945          
    946           <simplelist type="inline">
    947             <member><xref linkend="f_process-suspend"/></member>
    948             <member><xref linkend="f_process-suspend-count"/></member>
    949           </simplelist>
    950         </refsect1>
    951 
    952         <refsect1>
    953           <title>Notes</title>
    954 
    955           <para>
    956             This was previously called PROCESS-ENABLE;
    957             <xref linkend="f_process-enable"/> now does something slightly
    958             different.
    959           </para>
    960         </refsect1>
    961       </refentry>
    962 
    963       <refentry id="f_process-suspend-count">
    964         <indexterm zone="f_process-suspend-count">
    965           <primary>process-suspend-count</primary>
    966         </indexterm>
    967 
    968         <refnamediv>
    969           <refname>PROCESS-SUSPEND-COUNT</refname>
    970           <refpurpose>Returns the number of currently-pending suspensions
    971           applicable to a given process.</refpurpose>
    972           <refclass>Function</refclass>
    973         </refnamediv>
    974 
    975         <refsynopsisdiv>
    976           <synopsis>
    977             <function>process-suspend-count</function>
    978             process => result
    979           </synopsis>
    980         </refsynopsisdiv>
    981 
    982         <refsect1>
    983           <title>Arguments and Values</title>
    984 
    985           <variablelist>
    986             <varlistentry>
    987               <term>process</term>
    988               <listitem>
    989                 <para>a lisp process (thread).</para>
    990               </listitem>
    991             </varlistentry>
    992             <varlistentry>
    993               <term>result</term>
    994               <listitem>
    995                 <para>The number of "outstanding"
    996                 <xref linkend="f_process-suspend"/> calls on
    997                 <varname>process</varname>, or NIL if
    998                 <varname>process</varname> has expired.
    999                 </para>
    1000               </listitem>
    1001             </varlistentry>
    1002           </variablelist>
    1003         </refsect1>
    1004 
    1005         <refsect1>
    1006           <title>Description</title>
    1007 
    1008           <para>An "outstanding" <xref linkend="f_process-suspend"/> call
    1009           is one which has not yet been reversed by a call to
    1010           <xref linkend="f_process-resume"/>.  A process expires when
    1011           its initial function returns, although it may later be
    1012           reset.</para>
    1013 
    1014           <para>A process is <emphasis>runnable</emphasis> when it has a
    1015           <function>process-suspend-count</function> of 0, has been
    1016           preset as by <xref linkend="f_process-preset"/>, and has been
    1017           enabled as by <xref linkend="f_process-enable"/>.  Newly-created
    1018           processes have a <function>process-suspend-count</function> of
    1019           0.</para>
    1020         </refsect1>
    1021 
    1022         <refsect1>
    1023           <title>See Also</title>
    1024          
    1025           <simplelist type="inline">
    1026             <member><xref linkend="f_process-suspend"/></member>
    1027             <member><xref linkend="f_process-resume"/></member>
    1028           </simplelist>
    1029         </refsect1>
    1030       </refentry>
    1031 
    1032       <refentry id="f_process-preset">
    1033         <indexterm zone="f_process-preset">
    1034           <primary>process-preset</primary>
    1035         </indexterm>
    1036 
    1037         <refnamediv>
    1038           <refname>PROCESS-PRESET</refname>
    1039           <refpurpose>Sets the initial function and arguments of a specified
    1040           process.</refpurpose>
    1041           <refclass>Function</refclass>
    1042         </refnamediv>
    1043 
    1044         <refsynopsisdiv>
    1045           <synopsis><function>process-preset</function>
    1046           process function &rest; args
    1047           => result</synopsis>
    1048         </refsynopsisdiv>
    1049 
    1050         <refsect1>
    1051           <title>Arguments and Values</title>
    1052 
    1053           <variablelist>
    1054             <varlistentry>
    1055               <term>process</term>
    1056               <listitem>
    1057                 <para>a lisp process (thread).</para>
    1058               </listitem>
    1059             </varlistentry>
    1060             <varlistentry>
    1061               <term>function</term>
    1062               <listitem>
    1063                 <para>a function, designated by itself or by a symbol
    1064                 which names it.
    1065                 </para>
    1066               </listitem>
    1067             </varlistentry>
    1068             <varlistentry>
    1069               <term>args</term>
    1070               <listitem>
    1071                 <para>a list of values, appropriate as arguments to
    1072                 <varname>function</varname>.</para>
    1073               </listitem>
    1074             </varlistentry>
    1075             <varlistentry>
    1076               <term>result</term>
    1077               <listitem>
    1078                 <para>undefined.</para>
    1079               </listitem>
    1080             </varlistentry>
    1081           </variablelist>
    1082         </refsect1>
    1083 
    1084         <refsect1>
    1085           <title>Description</title>
    1086 
    1087           <para>Typically used to initialize a newly-created or newly-reset
    1088           process, setting things up so that when <varname>process</varname>
    1089           becomes enabled, it will begin execution by
    1090           applying <varname>function</varname> to <varname>args</varname>.
    1091           <function>process-preset</function> does not enable
    1092           <varname>process</varname>,
    1093           although a process must be <function>process-preset</function>
    1094           before it can be enabled.  Processes are normally enabled by
    1095           <xref linkend="f_process-enable"/>.
    1096           </para>
    1097         </refsect1>
    1098 
    1099         <refsect1>
    1100           <title>See Also</title>
    1101          
    1102           <simplelist type="inline">
    1103             <member><xref linkend="f_make-process"/></member>
    1104             <member><xref linkend="f_process-enable"/></member>
    1105             <member><xref linkend="f_process-run-function"/></member>
    1106           </simplelist>
    1107         </refsect1>
    1108       </refentry>
    1109 
    1110       <refentry id="f_process-enable">
    1111         <indexterm zone="f_process-enable">
    1112           <primary>process-enable</primary>
    1113         </indexterm>
    1114 
    1115         <refnamediv>
    1116           <refname>PROCESS-ENABLE</refname>
    1117           <refpurpose>Begins executing the initial function of a specified
    1118           process.</refpurpose>
    1119           <refclass>Function</refclass>
    1120         </refnamediv>
    1121 
    1122         <refsynopsisdiv>
    1123           <synopsis><function>process-enable</function>
    1124           process &optional; timeout
    1125           </synopsis>
    1126         </refsynopsisdiv>
    1127 
    1128         <refsect1>
    1129           <title>Arguments and Values</title>
    1130 
    1131           <variablelist>
    1132             <varlistentry>
    1133               <term>process</term>
    1134               <listitem>
    1135                 <para>a lisp process (thread).</para>
    1136               </listitem>
    1137             </varlistentry>
    1138             <varlistentry>
    1139               <term>timeout</term>
    1140               <listitem>
    1141                 <para>a time interval in seconds.  May be any
    1142                 non-negative real number the <function>floor</function> of
    1143                 which fits in 32 bits.  The default is 1.</para>
    1144               </listitem>
    1145             </varlistentry>
    1146             <varlistentry>
    1147               <term>result</term>
    1148               <listitem>
    1149                 <para>undefined.</para>
    1150               </listitem>
    1151             </varlistentry>
    1152           </variablelist>
    1153         </refsect1>
    1154 
    1155         <refsect1>
    1156           <title>Description</title>
    1157 
    1158           <para>Tries to begin the execution of <varname>process</varname>.
    1159           An error is signaled if <varname>process</varname> has never
    1160           been <xref linkend="f_process-preset"/>.  Otherwise,
    1161           <varname>process</varname> invokes its initial function.
    1162           </para>
    1163          
    1164           <para><function>process-enable</function> attempts to
    1165           synchronize with <varname>process</varname>, which is presumed
    1166           to be reset or in the act of resetting itself.  If this attempt
    1167           is not successful within the time interval specified by
    1168           <varname>timeout</varname>, a continuable error is signaled,
    1169           which offers the opportunity to continue waiting.
    1170           </para>
    1171 
    1172           <para>A process cannot meaningfully attempt to enable itself.</para>
    1173         </refsect1>
    1174 
    1175         <refsect1>
    1176           <title>See Also</title>
    1177          
    1178           <simplelist type="inline">
    1179             <member><xref linkend="f_make-process"/></member>
    1180             <member><xref linkend="f_process-preset"/></member>
    1181             <member><xref linkend="f_process-run-function"/></member>
    1182           </simplelist>
    1183         </refsect1>
    1184 
    1185         <refsect1>
    1186           <title>Notes</title>
    1187 
    1188           <para>It would be nice to have more discussion of what it means
    1189           to synchronize with the process.</para>
    1190         </refsect1>
    1191       </refentry>
    1192 
    1193       <refentry id="f_process-run-function">
    1194         <indexterm zone="f_process-run-function">
    1195           <primary>process-run-function</primary>
    1196         </indexterm>
    1197 
    1198         <refnamediv>
    1199           <refname>PROCESS-RUN-FUNCTION</refname>
    1200           <refpurpose>Creates a process, presets it, and enables it.
    1201           </refpurpose>
    1202           <refclass>Function</refclass>
    1203         </refnamediv>
    1204 
    1205         <refsynopsisdiv>
    1206           <synopsis><function>process-run-function</function>
    1207           process-specifier function &rest; args => process</synopsis>
    1208 
    1209           <variablelist>
    1210             <varlistentry>
    1211               <term>process-specifier</term>
    1212               <listitem>
    1213                 <para>
    1214                   <varname>name</varname> |
    1215                   (&key; <varname>name</varname>
    1216                   <varname>persistent</varname>
    1217                   <varname>priority</varname>
    1218                   <varname>class</varname>
    1219                   <varname>stack-size</varname>
    1220                   <varname>vstack-size</varname>
    1221                   <varname>tstack-size</varname>)
    1222                 </para>
    1223               </listitem>
    1224             </varlistentry>
    1225           </variablelist>
    1226         </refsynopsisdiv>
    1227 
    1228         <refsect1>
    1229           <title>Arguments and Values</title>
    1230 
    1231           <variablelist>
    1232             <varlistentry>
    1233               <term>name</term>
    1234               <listitem>
    1235                 <para>a string, used to identify the process.
    1236                 Passed to <function>make-process</function>.</para>
    1237               </listitem>
    1238             </varlistentry>
    1239             <varlistentry>
    1240               <term>function</term>
    1241               <listitem>
    1242                 <para>a function, designated by itself or by a symbol
    1243                 which names it.  Passed to
    1244                 <function>preset-process</function>.
    1245                 </para>
    1246               </listitem>
    1247             </varlistentry>
    1248             <varlistentry>
    1249               <term>persistent</term>
    1250              
    1251               <listitem>
    1252                 <para>a boolean, passed to <function>make-process</function>.
    1253                 </para>
    1254               </listitem>
    1255             </varlistentry>
    1256            
    1257             <varlistentry>
    1258               <term>priority</term>
    1259              
    1260               <listitem>
    1261                 <para>ignored.</para>
    1262               </listitem>
    1263             </varlistentry>
    1264            
    1265             <varlistentry>
    1266               <term>class</term>
    1267              
    1268               <listitem>
    1269                 <para>a subclass of CCL:PROCESS.  Passed to
    1270                 <function>make-process</function>.</para>
    1271               </listitem>
    1272             </varlistentry>
    1273            
    1274             <varlistentry>
    1275               <term>stack-size</term>
    1276              
    1277               <listitem>
    1278                 <para>a size, in bytes.  Passed to
    1279                 <function>make-process</function>.</para>
    1280               </listitem>
    1281             </varlistentry>
    1282            
    1283             <varlistentry>
    1284               <term>vstack-size</term>
    1285              
    1286               <listitem>
    1287                 <para>a size, in bytes.  Passed to
    1288                 <function>make-process</function>.</para>
    1289               </listitem>
    1290             </varlistentry>
    1291            
    1292             <varlistentry>
    1293               <term>tstack-size</term>
    1294              
    1295               <listitem>
    1296                 <para>a size, in bytes.  Passed to
    1297                 <function>make-process</function>.</para>
    1298               </listitem>
    1299             </varlistentry>
    1300             <varlistentry>
    1301               <term>process</term>
    1302               <listitem>
    1303                 <para>the newly-created process.</para>
    1304               </listitem>
    1305             </varlistentry>
    1306           </variablelist>
    1307         </refsect1>
    1308 
    1309         <refsect1>
    1310           <title>Description</title>
    1311 
    1312           <para>Creates a lisp process (thread) via
    1313           <xref linkend="f_make-process"/>,
    1314           presets it via <xref linkend="f_process-preset"/>, and
    1315           enables it via <xref linkend="f_process-enable"/>.  This means
    1316           that <varname>process</varname> will immediately begin to
    1317           execute.
    1318           <function>process-run-function</function> is
    1319           the simplest way to create and run a process.
    1320           </para>
    1321         </refsect1>
    1322 
    1323         <refsect1>
    1324           <title>See Also</title>
    1325          
    1326           <simplelist type="inline">
    1327             <member><xref linkend="f_make-process"/></member>
    1328             <member><xref linkend="f_process-preset"/></member>
    1329             <member><xref linkend="f_process-enable"/></member>
    1330           </simplelist>
    1331         </refsect1>
    1332       </refentry>
    1333 
    1334       <refentry id="f_process-interrupt">
    1335         <indexterm zone="f_process-interrupt">
    1336           <primary>process-interrupt</primary>
    1337         </indexterm>
    1338 
    1339         <refnamediv>
    1340           <refname>PROCESS-INTERRUPT</refname>
    1341           <refpurpose>Arranges for the target process to invoke a
    1342           specified function at some point in the near future, and then
    1343           return to what it was doing.</refpurpose>
    1344           <refclass>Function</refclass>
    1345         </refnamediv>
    1346 
    1347         <refsynopsisdiv>
    1348           <synopsis><function>process-interrupt</function>
    1349           process function &rest; args => result</synopsis>
    1350         </refsynopsisdiv>
    1351 
    1352         <refsect1>
    1353           <title>Arguments and Values</title>
    1354 
    1355           <variablelist>
    1356             <varlistentry>
    1357               <term>process</term>
    1358               <listitem>
    1359                 <para>a lisp process (thread).</para>
    1360               </listitem>
    1361             </varlistentry>
    1362             <varlistentry>
    1363               <term>function</term>
    1364               <listitem>
    1365                 <para>a function.
    1366                 </para>
    1367               </listitem>
    1368             </varlistentry>
    1369             <varlistentry>
    1370               <term>args</term>
    1371               <listitem>
    1372                 <para>a list of values, appropriate as arguments to
    1373                 <varname>function</varname>.</para>
    1374               </listitem>
    1375             </varlistentry>
    1376             <varlistentry>
    1377               <term>result</term>
    1378               <listitem>
    1379                 <para>the result of applying <varname>function</varname>
    1380                 to <varname>args</varname> if <varname>proceess</varname>
    1381                 is the <function>current-process</function>, otherwise
    1382                 NIL.</para>
    1383               </listitem>
    1384             </varlistentry>
    1385           </variablelist>
    1386         </refsect1>
    1387 
    1388         <refsect1>
    1389           <title>Description</title>
    1390 
    1391           <para>Arranges for <varname>process</varname>
    1392           to apply <varname>function</varname> to <varname>args</varname> at
    1393           some point in the near future (interrupting whatever
    1394           <varname>process</varname>
    1395           was doing.) If <varname>function</varname> returns normally,
    1396           <varname>process</varname> resumes
    1397           execution at the point at which it was interrupted.</para>
    1398 
    1399           <para><varname>process</varname> must be in an enabled state in
    1400           order to respond
    1401           to a <function>process-interrupt</function> request.  It's
    1402           perfectly legal for a process to call
    1403           <function>process-interrupt</function> on itself.</para>
    1404 
    1405           <para><function>process-interrupt</function>
    1406           uses asynchronous POSIX signals to interrupt threads. If the
    1407           thread being interrupted is executing lisp code, it can
    1408           respond to the interrupt almost immediately (as soon as it
    1409           has finished pseudo-atomic operations like consing and
    1410           stack-frame initialization.)</para>
    1411 
    1412           <para>If the interrupted thread is
    1413           blocking in a system call, that system call is aborted by
    1414           the signal and the interrupt is handled on return.
    1415           </para>
    1416 
    1417           <para>It is
    1418           still difficult to reliably interrupt arbitrary foreign code
    1419           (that may be stateful or otherwise non-reentrant); the
    1420           interrupt request is handled when such foreign code returns
    1421           to or enters lisp.</para>
    1422         </refsect1>
    1423 
    1424         <refsect1>
    1425           <title>See Also</title>
    1426          
    1427           <simplelist type="inline">
    1428             <member><xref linkend="m_without-interrupts"/></member>
    1429           </simplelist>
    1430         </refsect1>
    1431 
    1432         <refsect1>
    1433           <title>Notes</title>
    1434 
    1435           <para>It would probably be better for <varname>result</varname>
    1436           to always be NIL, since the present behaviour is inconsistent.
    1437           </para>
    1438 
    1439           <para>
    1440             <function>Process-interrupt</function> works by sending signals
    1441             between threads, via the C function
    1442             <function>#_pthread_signal</function>.  It could be argued
    1443             that it should be done in one of several possible other ways
    1444             under
    1445             Darwin, to make it practical to asynchronously interrupt
    1446             things which make heavy use of the Mach nanokernel.
    1447           </para>
    1448         </refsect1>
    1449       </refentry>
    1450 
    1451       <refentry id="v_current-process">
    1452         <indexterm zone="v_current-process">
    1453           <primary>*current-process*</primary>
    1454         </indexterm>
    1455 
    1456         <refnamediv>
    1457           <refname>*CURRENT-PROCESS*</refname>
    1458           <refpurpose>Bound in each process, to that process
    1459           itself.</refpurpose>
    1460           <refclass>Variable</refclass>
    1461         </refnamediv>
    1462 
    1463         <refsect1>
    1464           <title>Value Type</title>
    1465 
    1466           <para>A lisp process (thread).</para>
    1467         </refsect1>
    1468 
    1469         <refsect1>
    1470           <title>Initial Value</title>
    1471          
    1472           <para>Bound separately in each process, to that process itself.
    1473           </para>
    1474         </refsect1>
    1475 
    1476         <refsect1>
    1477           <title>Description</title>
    1478 
    1479           <para>Used when lisp code needs to find out what process it is
    1480           executing in.  Shouldn't be set by user code.</para>
    1481         </refsect1>
    1482 
    1483         <refsect1>
    1484           <title>See Also</title>
    1485          
    1486           <simplelist type="inline">
    1487             <member><xref linkend="f_all-processes"/></member>
    1488           </simplelist>
    1489         </refsect1>
    1490       </refentry>
    1491 
    1492       <refentry id="f_process-reset">
    1493         <indexterm zone="f_process-reset">
    1494           <primary>process-reset</primary>
    1495         </indexterm>
    1496 
    1497         <refnamediv>
    1498           <refname>PROCESS-RESET</refname>
    1499           <refpurpose>Causes a specified process to cleanly exit from
    1500           any ongoing computation.</refpurpose>
    1501           <refclass>Function</refclass>
    1502         </refnamediv>
    1503 
    1504         <refsynopsisdiv>
    1505           <synopsis><function>process-reset</function>
    1506           process &optional; kill-option => result</synopsis>
    1507         </refsynopsisdiv>
    1508 
    1509         <refsect1>
    1510           <title>Arguments and Values</title>
    1511 
    1512           <variablelist>
    1513             <varlistentry>
    1514               <term>process</term>
    1515               <listitem>
    1516                 <para>a lisp process (thread).</para>
    1517               </listitem>
    1518             </varlistentry>
    1519             <varlistentry>
    1520               <term>kill-option</term>
    1521               <listitem>
    1522                 <para>a generalized boolean.  The default is T.</para>
    1523               </listitem>
    1524             </varlistentry>
    1525             <varlistentry>
    1526               <term>result</term>
    1527               <listitem>
    1528                 <para>undefined.</para>
    1529               </listitem>
    1530             </varlistentry>
    1531           </variablelist>
    1532         </refsect1>
    1533 
    1534         <refsect1>
    1535           <title>Description</title>
    1536 
    1537           <para>Causes <varname>process</varname> to cleanly exit
    1538           from any ongoing computation.  If <varname>kill-option</varname>
    1539           is true, <varname>process</varname> then exits.  Otherwise, it
    1540           enters a state where it can be
    1541           <xref linkend="f_process-preset"/>. This
    1542           is implemented by signaling a condition of type PROCESS-RESET;
    1543           user-defined condition handlers should generally refrain from
    1544           attempting to handle conditions of this type.</para>
    1545 
    1546           <para>A process can meaningfully reset itself.</para>
    1547 
    1548           <para>There is in general no way to know precisely when
    1549           <varname>process</varname>
    1550           has completed the act of resetting or killing itself; a process
    1551           which has either entered the limbo of the reset state or exited
    1552           has few ways of communicating either fact.
    1553           <xref linkend="f_process-enable"/>
    1554           can reliably determine when a process has entered
    1555           the "limbo of the reset state", but can't predict how long the
    1556           clean exit from ongoing computation might take: that depends on
    1557           the behavior of <function>unwind-protect</function> cleanup
    1558           forms, and of the OS scheduler.</para>
    1559 
    1560           <para>Resetting a process other than
    1561           <xref linkend="v_current-process"/> involves the
    1562           use of <xref linkend="f_process-interrupt"/>.</para>
    1563         </refsect1>
    1564 
    1565         <refsect1>
    1566           <title>See Also</title>
    1567          
    1568           <simplelist type="inline">
    1569             <member><xref linkend="f_process-kill"/></member>
    1570             <member><xref linkend="f_process-abort"/></member>
    1571           </simplelist>
    1572         </refsect1>
    1573       </refentry>
    1574 
    1575       <refentry id="f_process-kill">
    1576         <indexterm zone="f_process-kill">
    1577           <primary>process-kill</primary>
    1578         </indexterm>
    1579 
    1580         <refnamediv>
    1581           <refname>PROCESS-KILL</refname>
    1582           <refpurpose>Causes a specified process to cleanly exit from any
    1583           ongoing computation, and then exit.</refpurpose>
    1584           <refclass>Function</refclass>
    1585         </refnamediv>
    1586 
    1587         <refsynopsisdiv>
    1588           <synopsis><function>process-kill</function> process
    1589           => result</synopsis>
    1590         </refsynopsisdiv>
    1591 
    1592         <refsect1>
    1593           <title>Arguments and Values</title>
    1594 
    1595           <variablelist>
    1596             <varlistentry>
    1597               <term>process</term>
    1598               <listitem>
    1599                 <para>a lisp process (thread).</para>
    1600               </listitem>
    1601             </varlistentry>
    1602             <varlistentry>
    1603               <term>result</term>
    1604               <listitem>
    1605                 <para>undefined.</para>
    1606               </listitem>
    1607             </varlistentry>
    1608           </variablelist>
    1609         </refsect1>
    1610 
    1611         <refsect1>
    1612           <title>Description</title>
    1613 
    1614           <para>Entirely equivalent to calling
    1615           (PROCESS-RESET PROCESS T).  Causes <varname>process</varname>
    1616           to cleanly exit from any ongoing computation, and then exit.</para>
    1617         </refsect1>
    1618 
    1619         <refsect1>
    1620           <title>See Also</title>
    1621          
    1622           <simplelist type="inline">
    1623             <member><xref linkend="f_process-reset"/></member>
    1624             <member><xref linkend="f_process-abort"/></member>
    1625           </simplelist>
    1626         </refsect1>
    1627       </refentry>
    1628 
    1629       <refentry id="f_process-abort">
    1630         <indexterm zone="f_process-abort">
    1631           <primary>process-abort</primary>
    1632         </indexterm>
    1633 
    1634         <refnamediv>
    1635           <refname>PROCESS-ABORT</refname>
    1636           <refpurpose>Causes a specified process to process an abort
    1637           condition, as if it had invoked
    1638           <function>abort</function>.</refpurpose>
    1639           <refclass>Function</refclass>
    1640         </refnamediv>
    1641 
    1642         <refsynopsisdiv>
    1643           <synopsis><function>process-abort</function> process
    1644           &optional; condition
    1645           => NIL</synopsis>
    1646         </refsynopsisdiv>
    1647 
    1648         <refsect1>
    1649           <title>Arguments and Values</title>
    1650 
    1651           <variablelist>
    1652             <varlistentry>
    1653               <term>process</term>
    1654               <listitem>
    1655                 <para>a lisp process (thread).</para>
    1656               </listitem>
    1657             </varlistentry>
    1658             <varlistentry>
    1659               <term>condition</term>
    1660               <listitem>
    1661                 <para>a lisp condition.  The default is NIL.</para>
    1662               </listitem>
    1663             </varlistentry>
    1664           </variablelist>
    1665         </refsect1>
    1666 
    1667         <refsect1>
    1668           <title>Description</title>
    1669 
    1670           <para>Entirely equivalent to calling
    1671           (<xref linkend="f_process-interrupt"/> <varname>process</varname>
    1672           (<function>lambda</function> ()
    1673           (<function>abort</function> <varname>condition</varname>))).
    1674           Causes <varname>process</varname> to transfer control to the
    1675           applicable handler or restart for <function>abort</function>.</para>
    1676 
    1677           <para>If <varname>condition</varname> is non-NIL,
    1678           <function>process-abort</function> does not consider any
    1679           handlers which are explicitly bound to conditions other than
    1680           <varname>condition</varname>.</para>
    1681         </refsect1>
    1682 
    1683         <refsect1>
    1684           <title>See Also</title>
    1685          
    1686           <simplelist type="inline">
    1687             <member><xref linkend="f_process-reset"/></member>
    1688             <member><xref linkend="f_process-kill"/></member>
    1689           </simplelist>
    1690         </refsect1>
    1691       </refentry>
    1692 
    1693       <refentry id="v_ticks-per-second">
    1694         <indexterm zone="v_ticks-per-second">
    1695           <primary>*ticks-per-second*</primary>
    1696         </indexterm>
    1697 
    1698         <refnamediv>
    1699           <refname>*TICKS-PER-SECOND*</refname>
    1700           <refpurpose>Bound to the clock resolution of the OS
    1701           scheduler.</refpurpose>
    1702           <refclass>Variable</refclass>
    1703         </refnamediv>
     2983          <refsect1>
     2984            <title>See Also</title>
     2985           
     2986            <simplelist type="inline">
     2987              <member><xref linkend="f_make-lock"/></member>
     2988              <member><xref linkend="f_make-read-write-lock"/></member>
     2989              <member><xref linkend="f_make-semaphore"/></member>
     2990              <member><xref linkend="f_process-output-wait"/></member>
     2991              <member><xref linkend="m_with-terminal-input"/></member>
     2992            </simplelist>
     2993          </refsect1>
     2994
     2995          <refsect1>
     2996            <title>Notes</title>
     2997
     2998            <para>
     2999              <function>process-input-wait</function> has a timeout parameter,
     3000              and
     3001              <xref linkend="f_process-output-wait"/> does not.  This
     3002              inconsistency should probably be corrected.
     3003            </para>
     3004          </refsect1>
     3005    </refentry>
     3006
     3007    <refentry id="f_process-output-wait">
     3008          <indexterm zone="f_process-output-wait">
     3009            <primary>process-output-wait</primary>
     3010          </indexterm>
     3011
     3012          <refnamediv>
     3013            <refname>PROCESS-OUTPUT-WAIT</refname>
     3014            <refpurpose>Waits until output is possible on a given file
     3015              descriptor.</refpurpose>
     3016            <refclass>Function</refclass>
     3017          </refnamediv>
     3018
     3019          <refsynopsisdiv>
     3020            <synopsis><function>process-output-wait</function>
     3021              fd  &optional; timeout</synopsis>
     3022          </refsynopsisdiv>
     3023
     3024          <refsect1>
     3025            <title>Arguments and Values</title>
     3026           
     3027            <variablelist>
     3028              <varlistentry>
     3029                <term>fd</term>
     3030                <listitem>
     3031                      <para>a file descriptor, which is a non-negative integer
     3032                        used by the OS to refer to an open file, socket, or similar
     3033                        I/O connection.  See <xref linkend="f_stream-device"/>.</para>
     3034                </listitem>
     3035              </varlistentry>
     3036              <varlistentry>
     3037                <term>timeout</term>
     3038                <listitem>
     3039                      <para>either NIL or a time interval in milliseconds.  Must be a non-negative integer.  The default is NIL.</para>
     3040                </listitem>
     3041              </varlistentry>
     3042            </variablelist>
     3043          </refsect1>
     3044
     3045          <refsect1>
     3046            <title>Description</title>
     3047
     3048            <para>Wait until output is possible on <varname>fd</varname> or until <varname>timeout</varname>, if
     3049              it is not NIL, has been exceeded.
     3050              This uses the <function>select()</function> system call, and is
     3051              generally a fairly
     3052              efficient way of blocking while waiting to output.</para>
     3053
     3054            <para>If <function>process-output-wait</function> is called on
     3055              a network socket which has not yet established a connection, it
     3056              will wait until the connection is established.  This is an
     3057              important use, often overlooked.</para>
     3058          </refsect1>
     3059
     3060          <refsect1>
     3061            <title>See Also</title>
     3062           
     3063            <simplelist type="inline">
     3064              <member><xref linkend="f_make-lock"/></member>
     3065              <member><xref linkend="f_make-read-write-lock"/></member>
     3066              <member><xref linkend="f_make-semaphore"/></member>
     3067              <member><xref linkend="f_process-input-wait"/></member>
     3068              <member><xref linkend="m_with-terminal-input"/></member>
     3069            </simplelist>
     3070          </refsect1>
     3071
     3072          <refsect1>
     3073            <title>Notes</title>
     3074
     3075            <para>
     3076              <xref linkend="f_process-input-wait"/> has a timeout parameter,
     3077              and
     3078              <function>process-output-wait</function> does not.  This
     3079              inconsistency should probably be corrected.
     3080            </para>
     3081          </refsect1>
     3082    </refentry>
     3083
     3084    <refentry id="m_with-terminal-input">
     3085          <indexterm zone="m_with-terminal-input">
     3086            <primary>with-terminal-input</primary>
     3087          </indexterm>
     3088
     3089          <refnamediv>
     3090            <refname>WITH-TERMINAL-INPUT</refname>
     3091            <refpurpose>Executes its body in an environment with exclusive
     3092              read access to the terminal.</refpurpose>
     3093            <refclass>Macro</refclass>
     3094          </refnamediv>
     3095
     3096          <refsynopsisdiv>
     3097            <synopsis><function>with-terminal-input</function>
     3098              &body; body => result</synopsis>
     3099          </refsynopsisdiv>
     3100
     3101          <refsect1>
     3102            <title>Arguments and Values</title>
     3103           
     3104            <variablelist>
     3105              <varlistentry>
     3106                <term>body</term>
     3107                <listitem>
     3108                      <para>an implicit progn.</para>
     3109                </listitem>
     3110              </varlistentry>
     3111              <varlistentry>
     3112                <term>result</term>
     3113                <listitem>
     3114                      <para>the primary value returned by
     3115                        <varname>body</varname>.</para>
     3116                </listitem>
     3117              </varlistentry>
     3118            </variablelist>
     3119          </refsect1>
     3120
     3121          <refsect1>
     3122            <title>Description</title>
     3123
     3124            <para>Requests exclusive read access to the standard terminal
     3125              stream, <varname>*terminal-io*</varname>.  Executes
     3126              <varname>body</varname> in an environment with that access.
     3127            </para>
     3128          </refsect1>
     3129
     3130          <refsect1>
     3131            <title>See Also</title>
     3132           
     3133            <simplelist type="inline">
     3134              <member><xref
     3135                         linkend="v_request-terminal-input-via-break"/></member>
     3136              <member><xref linkend="cmd_y"/></member>
     3137              <member><xref linkend="f_make-lock"/></member>
     3138              <member><xref linkend="f_make-read-write-lock"/></member>
     3139              <member><xref linkend="f_make-semaphore"/></member>
     3140              <member><xref linkend="f_process-input-wait"/></member>
     3141              <member><xref linkend="f_process-output-wait"/></member>
     3142            </simplelist>
     3143          </refsect1>
     3144    </refentry>
     3145
     3146    <refentry id="v_request-terminal-input-via-break">
     3147          <indexterm zone="v_request-terminal-input-via-break">
     3148            <primary>request-terminal-input-via-break</primary>
     3149          </indexterm>
     3150
     3151          <refnamediv>
     3152            <refname>*REQUEST-TERMINAL-INPUT-VIA-BREAK*</refname>
     3153            <refpurpose>Controls how attempts to obtain ownership of
     3154              terminal input are made.</refpurpose>
     3155            <refclass>Variable</refclass>
     3156          </refnamediv>
    17043157
    17053158          <refsect1>
    17063159            <title>Value Type</title>
    17073160
    1708             <para>A positive integer.</para>
     3161            <para>A boolean.</para>
    17093162          </refsect1>
    17103163
     
    17123165            <title>Initial Value</title>
    17133166           
    1714             <para>The clock resoluton of the OS scheduler.  Currently,
    1715             both LinuxPPC and DarwinPPC yeild an initial value of 100.
    1716             </para>
    1717           </refsect1>
    1718 
    1719         <refsect1>
    1720           <title>Description</title>
    1721 
    1722           <para>This value is ordinarily of marginal interest at best,
    1723           but, for backward compatibility, some functions accept timeout
    1724           values expressed in "ticks".  This value gives the number of
    1725           ticks per second.</para>
    1726         </refsect1>
    1727 
    1728         <refsect1>
    1729           <title>See Also</title>
    1730          
    1731           <simplelist type="inline">
    1732             <member><xref linkend="f_process-wait-with-timeout"/></member>
    1733           </simplelist>
    1734         </refsect1>
    1735       </refentry>
    1736 
    1737       <refentry id="f_process-whostate">
    1738         <indexterm zone="f_process-whostate">
    1739           <primary>process-whostate</primary>
    1740         </indexterm>
    1741 
    1742         <refnamediv>
    1743           <refname>PROCESS-WHOSTATE</refname>
    1744           <refpurpose>Returns a string which describes the status of
    1745           a specified process.</refpurpose>
    1746           <refclass>Function</refclass>
    1747         </refnamediv>
    1748 
    1749         <refsynopsisdiv>
    1750           <synopsis><function>process-whostate</function> process
    1751           => whostate</synopsis>
    1752           <variablelist>
    1753             <varlistentry>
    1754               <term>process</term>
    1755               <listitem>
    1756                 <para>a lisp process (thread).</para>
    1757               </listitem>
    1758             </varlistentry>
    1759             <varlistentry>
    1760               <term>whostate</term>
    1761               <listitem>
    1762                 <para>a string which describes the "state" of
    1763                 <varname>process</varname>.</para>
    1764               </listitem>
    1765             </varlistentry>
    1766           </variablelist>
    1767         </refsynopsisdiv>
    1768 
    1769         <refsect1>
    1770           <title>Description</title>
    1771 
    1772           <para>This information is primarily for the benefit of
    1773           debugging tools.  <varname>whostate</varname> is a terse report
    1774           on what <varname>process</varname> is doing, or not doing,
    1775           and why.</para>
    1776 
    1777           <para>If the process is currently waiting in a call to
    1778           <xref linkend="f_process-wait"/> or
    1779           <xref linkend="f_process-wait-with-timeout"/>, its
    1780           <function>process-whostate</function> will be the value
    1781           which was passed to that function as <varname>whostate</varname>.
    1782           </para>
    1783         </refsect1>
    1784 
    1785         <refsect1>
    1786           <title>See Also</title>
    1787          
    1788           <simplelist type="inline">
    1789             <member><xref linkend="f_process-wait"/></member>
    1790             <member><xref linkend="f_process-wait-with-timeout"/></member>
    1791             <member><xref linkend="m_with-terminal-input"/></member>
    1792           </simplelist>
    1793         </refsect1>
    1794 
    1795         <refsect1>
    1796           <title>Notes</title>
    1797 
    1798           <para>This should arguably be SETFable, but doesn't seem to
    1799           ever have been.</para>
    1800         </refsect1>
    1801       </refentry>
    1802 
    1803       <refentry id="f_process-allow-schedule">
    1804         <indexterm zone="f_process-allow-schedule">
    1805           <primary>process-allow-schedule</primary>
    1806         </indexterm>
    1807 
    1808         <refnamediv>
    1809           <refname>PROCESS-ALLOW-SCHEDULE</refname>
    1810           <refpurpose>Used for cooperative multitasking; probably never
    1811           necessary.</refpurpose>
    1812           <refclass>Function</refclass>
    1813         </refnamediv>
    1814 
    1815         <refsynopsisdiv>
    1816           <synopsis><function>process-allow-schedule</function></synopsis>
    1817         </refsynopsisdiv>
    1818 
    1819         <refsect1>
    1820           <title>Description</title>
    1821 
    1822           <para>Advises the OS scheduler that the current thread has nothing
    1823           useful to do and that it should try to find some other thread to
    1824           schedule in its place. There's almost always a better
    1825           alternative, such as waiting for some specific event to
    1826           occur.  For example, you could use a lock or semaphore.</para>
    1827         </refsect1>
    1828 
    1829         <refsect1>
    1830           <title>See Also</title>
    1831          
    1832           <simplelist type="inline">
    1833             <member><xref linkend="f_make-lock"/></member>
    1834             <member><xref linkend="f_make-read-write-lock"/></member>
    1835             <member><xref linkend="f_make-semaphore"/></member>
    1836             <member><xref linkend="f_process-input-wait"/></member>
    1837             <member><xref linkend="f_process-output-wait"/></member>
    1838             <member><xref linkend="m_with-terminal-input"/></member>
    1839           </simplelist>
    1840         </refsect1>
    1841 
    1842         <refsect1>
    1843           <title>Notes</title>
    1844 
    1845           <para>This is a holdover from the days of cooperative
    1846           multitasking.  All modern general-purpose operating systems use
    1847           preemptive multitasking.</para>
    1848         </refsect1>
    1849       </refentry>
    1850 
    1851       <refentry id="f_process-wait">
    1852         <indexterm zone="f_process-wait">
    1853           <primary>process-wait</primary>
    1854         </indexterm>
    1855 
    1856         <refnamediv>
    1857           <refname>PROCESS-WAIT</refname>
    1858           <refpurpose>Causes the current lisp process (thread) to wait for
    1859           a given
    1860           predicate to return true.</refpurpose>
    1861           <refclass>Function</refclass>
    1862         </refnamediv>
    1863 
    1864         <refsynopsisdiv>
    1865           <synopsis><function>process-wait</function>
    1866           whostate function &rest; args => result</synopsis>
    1867         </refsynopsisdiv>
    1868 
    1869         <refsect1>
    1870           <title>Arguments and Values</title>
    1871 
    1872           <variablelist>
    1873             <varlistentry>
    1874               <term>whostate</term>
    1875 
    1876               <listitem>
    1877                 <para>a string, which will be the value of
    1878                 <xref linkend="f_process-whostate"/>
    1879                 while the process is waiting.</para>
    1880               </listitem>
    1881             </varlistentry>
    1882             <varlistentry>
    1883               <term>function</term>
    1884               <listitem>
    1885                 <para>a function, designated by itself or by a symbol
    1886                 which names it.
    1887                 </para>
    1888               </listitem>
    1889             </varlistentry>
    1890             <varlistentry>
    1891               <term>args</term>
    1892               <listitem>
    1893                 <para>a list of values, appropriate as arguments to
    1894                 <varname>function</varname>.</para>
    1895               </listitem>
    1896             </varlistentry>
    1897             <varlistentry>
    1898               <term>result</term>
    1899               <listitem>
    1900                 <para>NIL.</para>
    1901               </listitem>
    1902             </varlistentry>
    1903           </variablelist>
    1904         </refsect1>
    1905 
    1906         <refsect1>
    1907           <title>Description</title>
    1908 
    1909           <para>Causes the current lisp process (thread) to repeatedly
    1910           apply <varname>function</varname> to
    1911           <varname>args</varname> until the call returns a true result, then
    1912           returns NIL. After
    1913           each failed call, yields the CPU as if by
    1914           <xref linkend="f_process-allow-schedule"/>.</para>
    1915          
    1916           <para>
    1917           As with <xref linkend="f_process-allow-schedule"/>, it's almost
    1918           always more efficient to wait for some
    1919           specific event to occur; this isn't exactly busy-waiting, but
    1920           the OS scheduler can do a better job of scheduling if it's given
    1921           the relevant information.  For example, you could use a lock
    1922           or semaphore.</para>
    1923         </refsect1>
    1924 
    1925         <refsect1>
    1926           <title>See Also</title>
    1927          
    1928           <simplelist type="inline">
    1929             <member><xref linkend="f_process-whostate"/></member>
    1930             <member><xref linkend="f_process-wait-with-timeout"/></member>
    1931             <member><xref linkend="f_make-lock"/></member>
    1932             <member><xref linkend="f_make-read-write-lock"/></member>
    1933             <member><xref linkend="f_make-semaphore"/></member>
    1934             <member><xref linkend="f_process-input-wait"/></member>
    1935             <member><xref linkend="f_process-output-wait"/></member>
    1936             <member><xref linkend="m_with-terminal-input"/></member>
    1937           </simplelist>
    1938         </refsect1>
    1939       </refentry>
    1940 
    1941       <refentry id="f_process-wait-with-timeout">
    1942         <indexterm zone="f_process-wait-with-timeout">
    1943           <primary>process-wait-with-timeout</primary>
    1944         </indexterm>
    1945 
    1946         <refnamediv>
    1947           <refname>PROCESS-WAIT-WITH-TIMEOUT</refname>
    1948           <refpurpose>Causes the current thread to wait for a given
    1949           predicate to return true, or for a timeout to expire.</refpurpose>
    1950           <refclass>Function</refclass>
    1951         </refnamediv>
    1952 
    1953         <refsynopsisdiv>
    1954           <synopsis><function>process-wait-with-timeout</function>
    1955           whostate ticks function args => result</synopsis>
    1956         </refsynopsisdiv>
    1957 
    1958         <refsect1>
    1959           <title>Arguments and Values</title>
    1960 
    1961           <variablelist>
    1962             <varlistentry>
    1963               <term>whostate</term>
    1964               <listitem>
    1965                 <para>a string, which will be the value of
    1966                 <xref linkend="f_process-whostate"/>
    1967                 while the process is waiting.</para>
    1968               </listitem>
    1969             </varlistentry>
    1970             <varlistentry>
    1971               <term>ticks</term>
    1972               <listitem>
    1973                 <para>either a positive integer expressing a duration
    1974                 in "ticks" (see <xref linkend="v_ticks-per-second"/>),
    1975                 or NIL.</para>
    1976               </listitem>
    1977             </varlistentry>
    1978             <varlistentry>
    1979               <term>function</term>
    1980               <listitem>
    1981                 <para>a function, designated by itself or by a symbol
    1982                 which names it.</para>
    1983               </listitem>
    1984             </varlistentry>
    1985             <varlistentry>
    1986               <term>args</term>
    1987               <listitem>
    1988                 <para>a list of values, appropriate as arguments to
    1989                 <varname>function</varname>.</para>
    1990               </listitem>
    1991             </varlistentry>
    1992             <varlistentry>
    1993               <term>result</term>
    1994               <listitem>
    1995                 <para>T if <function>process-wait-with-timeout</function>
    1996                 returned because its <varname>function</varname> returned
    1997                 true, or NIL if it returned because the duration
    1998                 <varname>ticks</varname> has been exceeded.</para>
    1999               </listitem>
    2000             </varlistentry>
    2001           </variablelist>
    2002         </refsect1>
    2003 
    2004         <refsect1>
    2005           <title>Description</title>
    2006 
    2007           <para>If <varname>ticks</varname> is NIL, behaves exactly like
    2008           <xref linkend="f_process-wait"/>, except for returning T.
    2009           Otherwise, <varname>function</varname> will be tested repeatedly,
    2010           in the same
    2011           kind of test/yield loop as in <xref linkend="f_process-wait"/>>
    2012           until either <varname>function</varname> returns true,
    2013           or the duration <varname>ticks</varname> has been exceeded.
    2014           </para>
    2015 
    2016           <para> Having already read the descriptions of
    2017           <xref linkend="f_process-allow-schedule"/> and
    2018           <xref linkend="f_process-wait"/>, the
    2019           astute reader has no doubt anticipated the observation that
    2020           better alternatives should be used whenever possible.</para>
    2021         </refsect1>
    2022 
    2023         <refsect1>
    2024           <title>See Also</title>
    2025          
    2026           <simplelist type="inline">
    2027             <member><xref linkend="v_ticks-per-second"/></member>
    2028             <member><xref linkend="f_process-whostate"/></member>
    2029             <member><xref linkend="f_process-wait"/></member>
    2030             <member><xref linkend="f_make-lock"/></member>
    2031             <member><xref linkend="f_make-read-write-lock"/></member>
    2032             <member><xref linkend="f_make-semaphore"/></member>
    2033             <member><xref linkend="f_process-input-wait"/></member>
    2034             <member><xref linkend="f_process-output-wait"/></member>
    2035             <member><xref linkend="m_with-terminal-input"/></member>
    2036           </simplelist>
    2037         </refsect1>
    2038       </refentry>
    2039 
    2040       <refentry id="m_without-interrupts">
    2041         <indexterm zone="m_without-interrupts">
    2042           <primary>without-interrupts</primary>
    2043         </indexterm>
    2044 
    2045         <refnamediv>
    2046           <refname>WITHOUT-INTERRUPTS</refname>
    2047           <refpurpose>Evaluates its body in an environment in which
    2048           process-interrupt requests are deferred.</refpurpose>
    2049           <refclass>Macro</refclass>
    2050         </refnamediv>
    2051 
    2052         <refsynopsisdiv>
    2053           <synopsis><function>without-interrupts</function>
    2054           &body; body => result</synopsis>
    2055         </refsynopsisdiv>
    2056 
    2057         <refsect1>
    2058           <title>Arguments and Values</title>
    2059 
    2060           <variablelist>
    2061             <varlistentry>
    2062               <term>body</term>
    2063               <listitem>
    2064                 <para>an implicit progn.</para>
    2065               </listitem>
    2066             </varlistentry>
    2067             <varlistentry>
    2068               <term>result</term>
    2069               <listitem>
    2070                 <para>the primary value returned by
    2071                 <varname>body</varname>.</para>
    2072               </listitem>
    2073             </varlistentry>
    2074           </variablelist>
    2075         </refsect1>
    2076 
    2077         <refsect1>
    2078           <title>Description</title>
    2079 
    2080           <para>Executes <varname>body</varname>
    2081           in an environment in which <xref linkend="f_process-interrupt"/>
    2082           requests are
    2083           deferred. As noted in the description of
    2084           <xref linkend="f_process-interrupt"/>, this has nothing to do
    2085           with the
    2086           scheduling of other threads; it may be necessary to inhibit
    2087           <xref linkend="f_process-interrupt"/> handling when
    2088           (for instance) modifying some data
    2089           structure (for which the current thread holds an appropriate lock)
    2090           in some manner that&#39;s not reentrant.</para>
    2091         </refsect1>
    2092 
    2093         <refsect1>
    2094           <title>See Also</title>
    2095          
    2096           <simplelist type="inline">
    2097             <member><xref linkend="f_process-interrupt"/></member>
    2098           </simplelist>
    2099         </refsect1>
    2100       </refentry>
    2101 
    2102       <refentry id="f_make-lock">
    2103         <indexterm zone="f_make-lock">
    2104           <primary>make-lock</primary>
    2105         </indexterm>
    2106 
    2107         <refnamediv>
    2108           <refname>MAKE-LOCK</refname>
    2109           <refpurpose>Creates and returns a lock object, which can
    2110           be used for synchronization between threads.</refpurpose>
    2111           <refclass>Function</refclass>
    2112         </refnamediv>
    2113 
    2114         <refsynopsisdiv>
    2115           <synopsis><function>make-lock</function> &optional;
    2116           name => lock</synopsis>
    2117         </refsynopsisdiv>
    2118 
    2119         <refsect1>
    2120           <title>Arguments and Values</title>
    2121 
    2122           <variablelist>
    2123             <varlistentry>
    2124               <term>name</term>
    2125               <listitem>
    2126                 <para>any lisp object; saved as part of
    2127                 <varname>lock</varname>.  Typically a string or symbol
    2128                 which may appear in the <xref linkend="f_process-whostate"/>s
    2129                 of threads which are waiting for <varname>lock</varname>.
    2130                 </para>
    2131               </listitem>
    2132             </varlistentry>
    2133             <varlistentry>
    2134               <term>lock</term>
    2135               <listitem>
    2136                 <para>a newly-allocated object of type CCL:LOCK.</para>
    2137               </listitem>
    2138             </varlistentry>
    2139           </variablelist>
    2140         </refsect1>
    2141 
    2142         <refsect1>
    2143           <title>Description</title>
    2144 
    2145           <para>Creates and returns a lock object, which can
    2146           be used to synchronize access to some shared resource.
    2147           <varname>lock</varname> is
    2148           initially in a &#34;free&#34; state; a lock can also be
    2149           &#34;owned&#34; by a
    2150           thread.</para>
    2151         </refsect1>
    2152 
    2153         <refsect1>
    2154           <title>See Also</title>
    2155          
    2156           <simplelist type="inline">
    2157             <member><xref linkend="m_with-lock-grabbed"/></member>
    2158             <member><xref linkend="f_grab-lock"/></member>
    2159             <member><xref linkend="f_release-lock"/></member>
    2160             <member><xref linkend="f_try-lock"/></member>
    2161             <member><xref linkend="f_make-read-write-lock"/></member>
    2162             <member><xref linkend="f_make-semaphore"/></member>
    2163             <member><xref linkend="f_process-input-wait"/></member>
    2164             <member><xref linkend="f_process-output-wait"/></member>
    2165             <member><xref linkend="m_with-terminal-input"/></member>
    2166           </simplelist>
    2167         </refsect1>
    2168       </refentry>
    2169 
    2170       <refentry id="m_with-lock-grabbed">
    2171         <indexterm zone="m_with-lock-grabbed">
    2172           <primary>with-lock-grabbed</primary>
    2173         </indexterm>
    2174 
    2175         <refnamediv>
    2176           <refname>WITH-LOCK-GRABBED</refname>
    2177           <refpurpose>Waits until a given lock can be obtained, then
    2178           evaluates its body with the lock held.</refpurpose>
    2179           <refclass>Macro</refclass>
    2180         </refnamediv>
    2181 
    2182         <refsynopsisdiv>
    2183           <synopsis><function>with-lock-grabbed</function>
    2184           (lock) &body; body</synopsis>
    2185         </refsynopsisdiv>
    2186 
    2187         <refsect1>
    2188           <title>Arguments and Values</title>
    2189 
    2190           <variablelist>
    2191             <varlistentry>
    2192               <term>lock</term>
    2193               <listitem>
    2194                 <para>an object of type CCL:LOCK.</para>
    2195               </listitem>
    2196             </varlistentry>
    2197             <varlistentry>
    2198               <term>body</term>
    2199               <listitem>
    2200                 <para>an implicit progn.</para>
    2201               </listitem>
    2202             </varlistentry>
    2203             <varlistentry>
    2204               <term>result</term>
    2205               <listitem>
    2206                 <para>the primary value returned by
    2207                 <varname>body</varname>.</para>
    2208               </listitem>
    2209             </varlistentry>
    2210           </variablelist>
    2211         </refsect1>
    2212 
    2213         <refsect1>
    2214           <title>Description</title>
    2215 
    2216           <para>Waits until <varname>lock</varname> is either free or
    2217           owned by the calling
    2218           thread, then excutes <varname>body</varname> with the
    2219           lock owned by the calling thread. If <varname>lock</varname>
    2220           was free when <function>with-lock-grabbed</function> was called,
    2221           it is restored to a free state after <varname>body</varname>
    2222           is executed.</para>
    2223         </refsect1>
    2224 
    2225         <refsect1>
    2226           <title>See Also</title>
    2227          
    2228           <simplelist type="inline">
    2229             <member><xref linkend="f_make-lock"/></member>
    2230             <member><xref linkend="f_grab-lock"/></member>
    2231             <member><xref linkend="f_release-lock"/></member>
    2232             <member><xref linkend="f_try-lock"/></member>
    2233             <member><xref linkend="f_make-read-write-lock"/></member>
    2234             <member><xref linkend="f_make-semaphore"/></member>
    2235             <member><xref linkend="f_process-input-wait"/></member>
    2236             <member><xref linkend="f_process-output-wait"/></member>
    2237             <member><xref linkend="m_with-terminal-input"/></member>
    2238           </simplelist>
    2239         </refsect1>
    2240       </refentry>
    2241 
    2242       <refentry id="f_grab-lock">
    2243         <indexterm zone="f_grab-lock">
    2244           <primary>grab-lock</primary>
    2245         </indexterm>
    2246 
    2247         <refnamediv>
    2248           <refname>GRAB-LOCK</refname>
    2249           <refpurpose>Waits until a given lock can be obtained, then
    2250           obtains it.</refpurpose>
    2251           <refclass>Function</refclass>
    2252         </refnamediv>
    2253 
    2254         <refsynopsisdiv>
    2255           <synopsis><function>grab-lock</function> lock</synopsis>
    2256         </refsynopsisdiv>
    2257 
    2258         <refsect1>
    2259           <title>Arguments and Values</title>
    2260 
    2261           <variablelist>
    2262             <varlistentry>
    2263               <term>lock</term>
    2264               <listitem>
    2265                 <para>an object of type CCL:LOCK.</para>
    2266               </listitem>
    2267             </varlistentry>
    2268           </variablelist>
    2269         </refsect1>
    2270 
    2271         <refsect1>
    2272           <title>Description</title>
    2273 
    2274           <para>Blocks until <varname>lock</varname> is owned by the
    2275           calling thread.</para>
    2276 
    2277           <para>The macro <xref linkend="m_with-lock-grabbed"/>
    2278           <emphasis>could</emphasis> be defined in
    2279           terms of <function>grab-lock</function> and
    2280           <xref linkend="f_release-lock"/>, but it is actually
    2281           implemented at a slightly lower level.</para>
    2282         </refsect1>
    2283 
    2284         <refsect1>
    2285           <title>See Also</title>
    2286          
    2287           <simplelist type="inline">
    2288             <member><xref linkend="f_make-lock"/></member>
    2289             <member><xref linkend="m_with-lock-grabbed"/></member>
    2290             <member><xref linkend="f_release-lock"/></member>
    2291             <member><xref linkend="f_try-lock"/></member>
    2292             <member><xref linkend="f_make-read-write-lock"/></member>
    2293             <member><xref linkend="f_make-semaphore"/></member>
    2294             <member><xref linkend="f_process-input-wait"/></member>
    2295             <member><xref linkend="f_process-output-wait"/></member>
    2296             <member><xref linkend="m_with-terminal-input"/></member>
    2297           </simplelist>
    2298         </refsect1>
    2299       </refentry>
    2300 
    2301       <refentry id="f_release-lock">
    2302         <indexterm zone="f_release-lock">
    2303           <primary>release-lock</primary>
    2304         </indexterm>
    2305 
    2306         <refnamediv>
    2307           <refname>RELEASE-LOCK</refname>
    2308           <refpurpose>Relinquishes ownership of a given lock.</refpurpose>
    2309           <refclass>Function</refclass>
    2310         </refnamediv>
    2311 
    2312         <refsynopsisdiv>
    2313           <synopsis><function>release-lock</function> lock</synopsis>
    2314         </refsynopsisdiv>
    2315 
    2316         <refsect1>
    2317           <title>Arguments and Values</title>
    2318 
    2319           <variablelist>
    2320             <varlistentry>
    2321               <term>lock</term>
    2322               <listitem>
    2323                 <para>an object of type CCL:LOCK.</para>
    2324               </listitem>
    2325             </varlistentry>
    2326           </variablelist>
    2327         </refsect1>
    2328 
    2329         <refsect1>
    2330           <title>Description</title>
    2331 
    2332           <para>Signals an error of type CCL:LOCK-NOT-OWNER if
    2333           <varname>lock</varname>
    2334           is not already owned by the calling thread; otherwise, undoes the
    2335           effect of one previous
    2336           <xref linkend="f_grab-lock"/>.  If this means that
    2337           <function>release-lock</function> has now been called on
    2338           <varname>lock</varname> the same number of times as
    2339           <xref linkend="f_grab-lock"/> has, <varname>lock</varname>
    2340           becomes free.</para>
    2341         </refsect1>
    2342 
    2343         <refsect1>
    2344           <title>See Also</title>
    2345          
    2346           <simplelist type="inline">
    2347             <member><xref linkend="f_make-lock"/></member>
    2348             <member><xref linkend="m_with-lock-grabbed"/></member>
    2349             <member><xref linkend="f_grab-lock"/></member>
    2350             <member><xref linkend="f_try-lock"/></member>
    2351             <member><xref linkend="f_make-read-write-lock"/></member>
    2352             <member><xref linkend="f_make-semaphore"/></member>
    2353             <member><xref linkend="f_process-input-wait"/></member>
    2354             <member><xref linkend="f_process-output-wait"/></member>
    2355             <member><xref linkend="m_with-terminal-input"/></member>
    2356           </simplelist>
    2357         </refsect1>
    2358       </refentry>
    2359 
    2360       <refentry id="f_try-lock">
    2361         <indexterm zone="f_try-lock">
    2362           <primary>try-lock</primary>
    2363         </indexterm>
    2364 
    2365         <refnamediv>
    2366           <refname>TRY-LOCK</refname>
    2367           <refpurpose>Obtains the given lock, but only if it is not
    2368           necessary to wait for it.</refpurpose>
    2369           <refclass>Function</refclass>
    2370         </refnamediv>
    2371 
    2372         <refsynopsisdiv>
    2373           <synopsis><function>try-lock</function> lock => result</synopsis>
    2374         </refsynopsisdiv>
    2375 
    2376         <refsect1>
    2377           <title>Arguments and Values</title>
    2378 
    2379           <variablelist>
    2380             <varlistentry>
    2381               <term>lock</term>
    2382               <listitem>
    2383                 <para>an object of type CCL:LOCK.</para>
    2384               </listitem>
    2385             </varlistentry>
    2386             <varlistentry>
    2387               <term>result</term>
    2388               <listitem>
    2389                 <para>T if <varname>lock</varname> has been obtained,
    2390                 or NIL if it has not.</para>
    2391               </listitem>
    2392             </varlistentry>
    2393           </variablelist>
    2394         </refsect1>
    2395 
    2396         <refsect1>
    2397           <title>Description</title>
    2398 
    2399           <para>Tests whether <varname>lock</varname>
    2400           can be obtained without blocking - that is, either
    2401           <varname>lock</varname> is already free, or it is already owned
    2402           by <xref linkend="v_current-process"/>.  If it can,
    2403           causes it to
    2404           be owned by the calling lisp process (thread) and returns T.
    2405           Otherwise, the lock
    2406           is already owned by another thread and cannot be obtained without
    2407           blocking; NIL is returned in this case.</para>
    2408         </refsect1>
    2409 
    2410         <refsect1>
    2411           <title>See Also</title>
    2412          
    2413           <simplelist type="inline">
    2414             <member><xref linkend="f_make-lock"/></member>
    2415             <member><xref linkend="m_with-lock-grabbed"/></member>
    2416             <member><xref linkend="f_grab-lock"/></member>
    2417             <member><xref linkend="f_release-lock"/></member>
    2418             <member><xref linkend="f_make-read-write-lock"/></member>
    2419             <member><xref linkend="f_make-semaphore"/></member>
    2420             <member><xref linkend="f_process-input-wait"/></member>
    2421             <member><xref linkend="f_process-output-wait"/></member>
    2422             <member><xref linkend="m_with-terminal-input"/></member>
    2423           </simplelist>
    2424         </refsect1>
    2425       </refentry>
    2426 
    2427       <refentry id="f_make-read-write-lock">
    2428         <indexterm zone="f_make-read-write-lock">
    2429           <primary>make-read-write-lock</primary>
    2430         </indexterm>
    2431 
    2432         <refnamediv>
    2433           <refname>MAKE-READ-WRITE-LOCK</refname>
    2434           <refpurpose>Creates and returns a read-write lock, which can
    2435           be used for synchronization between threads.</refpurpose>
    2436           <refclass>Function</refclass>
    2437         </refnamediv>
    2438 
    2439         <refsynopsisdiv>
    2440           <synopsis><function>make-read-write-lock</function>
    2441           => read-write-lock</synopsis>
    2442         </refsynopsisdiv>
    2443 
    2444         <refsect1>
    2445           <title>Arguments and Values</title>
    2446 
    2447           <variablelist>
    2448             <varlistentry>
    2449               <term>read-write-lock</term>
    2450               <listitem>
    2451                 <para>a newly-allocated object of type
    2452                 CCL:READ-WRITE-LOCK.</para>
    2453               </listitem>
    2454             </varlistentry>
    2455           </variablelist>
    2456         </refsect1>
    2457 
    2458         <refsect1>
    2459           <title>Description</title>
    2460 
    2461           <para>Creates and returns an object of type CCL::READ-WRITE-LOCK.
    2462           A read-write lock may, at any given time, belong to any number
    2463           of lisp processes (threads) which act as "readers"; or, it may
    2464           belong to at most one process which acts as a "writer".  A
    2465           read-write lock may never be held by a reader at the same time as
    2466           a writer.  Intially, <varname>read-write-lock</varname> has
    2467           no readers and no writers.</para>
    2468         </refsect1>
    2469 
    2470         <refsect1>
    2471           <title>See Also</title>
    2472          
    2473           <simplelist type="inline">
    2474             <member><xref linkend="m_with-read-lock"/></member>
    2475             <member><xref linkend="m_with-write-lock"/></member>
    2476             <member><xref linkend="f_make-lock"/></member>
    2477             <member><xref linkend="f_make-semaphore"/></member>
    2478             <member><xref linkend="f_process-input-wait"/></member>
    2479             <member><xref linkend="f_process-output-wait"/></member>
    2480             <member><xref linkend="m_with-terminal-input"/></member>
    2481           </simplelist>
    2482         </refsect1>
    2483 
    2484         <refsect1>
    2485           <title>Notes</title>
    2486 
    2487           <para>There probably should be some way to
    2488           atomically &#34;promote&#34; a reader, making it a writer without
    2489           releasing the lock, which could otherwise cause delay.</para>
    2490         </refsect1>
    2491       </refentry>
    2492 
    2493       <refentry id="m_with-read-lock">
    2494         <indexterm zone="m_with-read-lock">
    2495           <primary>with-read-lock</primary>
    2496         </indexterm>
    2497 
    2498         <refnamediv>
    2499           <refname>WITH-READ-LOCK</refname>
    2500           <refpurpose>Waits until a given lock is available for
    2501           read-only access, then evaluates its body with the lock
    2502           held.</refpurpose>
    2503           <refclass>Macro</refclass>
    2504         </refnamediv>
    2505 
    2506         <refsynopsisdiv>
    2507           <synopsis><function>with-read-lock</function>
    2508           (read-write-lock) &body; body => result</synopsis>
    2509         </refsynopsisdiv>
    2510 
    2511         <refsect1>
    2512           <title>Arguments and Values</title>
    2513 
    2514           <variablelist>
    2515             <varlistentry>
    2516               <term>read-write-lock</term>
    2517               <listitem>
    2518                 <para>an object of type
    2519                 CCL:READ-WRITE-LOCK.</para>
    2520               </listitem>
    2521             </varlistentry>
    2522             <varlistentry>
    2523               <term>body</term>
    2524               <listitem>
    2525                 <para>an implicit progn.</para>
    2526               </listitem>
    2527             </varlistentry>
    2528             <varlistentry>
    2529               <term>result</term>
    2530               <listitem>
    2531                 <para>the primary value returned by
    2532                 <varname>body</varname>.</para>
    2533               </listitem>
    2534             </varlistentry>
    2535           </variablelist>
    2536         </refsect1>
    2537 
    2538         <refsect1>
    2539           <title>Description</title>
    2540 
    2541           <para>Waits until <varname>read-write-lock</varname> has no
    2542           writer,
    2543           ensures that <xref linkend="v_current-process"/> is a
    2544           reader of it, then executes <varname>body</varname>.
    2545           </para>
    2546 
    2547           <para>After executing <varname>body</varname>, if
    2548           <xref linkend="v_current-process"/> was not a reader of
    2549           <varname>read-write-lock</varname> before
    2550           <function>with-read-lock</function> was called, the lock is
    2551           released.  If it was already a reader, it remains one.</para>
    2552         </refsect1>
    2553 
    2554         <refsect1>
    2555           <title>See Also</title>
    2556          
    2557           <simplelist type="inline">
    2558             <member><xref linkend="f_make-read-write-lock"/></member>
    2559             <member><xref linkend="m_with-write-lock"/></member>
    2560             <member><xref linkend="f_make-lock"/></member>
    2561             <member><xref linkend="f_make-semaphore"/></member>
    2562             <member><xref linkend="f_process-input-wait"/></member>
    2563             <member><xref linkend="f_process-output-wait"/></member>
    2564             <member><xref linkend="m_with-terminal-input"/></member>
    2565           </simplelist>
    2566         </refsect1>
    2567       </refentry>
    2568 
    2569       <refentry id="m_with-write-lock">
    2570         <indexterm zone="m_with-write-lock">
    2571           <primary>with-write-lock</primary>
    2572         </indexterm>
    2573 
    2574         <refnamediv>
    2575           <refname>WITH-WRITE-LOCK</refname>
    2576           <refpurpose>Waits until the given lock is available for write
    2577           access, then executes its body with the lock held.</refpurpose>
    2578           <refclass>Macro</refclass>
    2579         </refnamediv>
    2580 
    2581         <refsynopsisdiv>
    2582           <synopsis><function>with-write-lock</function>
    2583           (read-write-lock) &body; body</synopsis>
    2584         </refsynopsisdiv>
    2585 
    2586         <refsect1>
    2587           <title>Arguments and Values</title>
    2588 
    2589           <variablelist>
    2590             <varlistentry>
    2591               <term>read-write-lock</term>
    2592               <listitem>
    2593                 <para>an object of type
    2594                 CCL:READ-WRITE-LOCK.</para>
    2595               </listitem>
    2596             </varlistentry>
    2597             <varlistentry>
    2598               <term>body</term>
    2599               <listitem>
    2600                 <para>an implicit progn.</para>
    2601               </listitem>
    2602             </varlistentry>
    2603             <varlistentry>
    2604               <term>result</term>
    2605               <listitem>
    2606                 <para>the primary value returned by
    2607                 <varname>body</varname>.</para>
    2608               </listitem>
    2609             </varlistentry>
    2610           </variablelist>
    2611         </refsect1>
    2612 
    2613         <refsect1>
    2614           <title>Description</title>
    2615 
    2616           <para>Waits until <varname>read-write-lock</varname> has no
    2617           readers and no writer other than <xref linkend="v_current-process"/>,
    2618           then ensures that <xref linkend="v_current-process"/> is the
    2619           writer of it.  With the lock held, executes <varname>body</varname>.
    2620           </para>
    2621 
    2622           <para>After executing <varname>body</varname>, if
    2623           <xref linkend="v_current-process"/> was not the writer of
    2624           <varname>read-write-lock</varname> before
    2625           <function>with-write-lock</function> was called, the lock is
    2626           released.  If it was already the writer, it remains the
    2627           writer.</para>
    2628         </refsect1>
    2629 
    2630         <refsect1>
    2631           <title>See Also</title>
    2632          
    2633           <simplelist type="inline">
    2634             <member><xref linkend="f_make-read-write-lock"/></member>
    2635             <member><xref linkend="m_with-read-lock"/></member>
    2636             <member><xref linkend="f_make-lock"/></member>
    2637             <member><xref linkend="f_make-semaphore"/></member>
    2638             <member><xref linkend="f_process-input-wait"/></member>
    2639             <member><xref linkend="f_process-output-wait"/></member>
    2640             <member><xref linkend="m_with-terminal-input"/></member>
    2641           </simplelist>
    2642         </refsect1>
    2643       </refentry>
    2644 
    2645       <refentry id="f_make-semaphore">
    2646         <indexterm zone="f_make-semaphore">
    2647           <primary>make-semaphore</primary>
    2648         </indexterm>
    2649 
    2650         <refnamediv>
    2651           <refname>MAKE-SEMAPHORE</refname>
    2652           <refpurpose>Creates and returns a semaphore, which can be used
    2653           for synchronization between threads.</refpurpose>
    2654           <refclass>Function</refclass>
    2655         </refnamediv>
    2656 
    2657         <refsynopsisdiv>
    2658           <synopsis><function>make-semaphore</function>
    2659           => semaphore</synopsis>
    2660         </refsynopsisdiv>
    2661 
    2662         <refsect1>
    2663           <title>Arguments and Values</title>
    2664          
    2665           <variablelist>
    2666             <varlistentry>
    2667               <term>semaphore</term>
    2668               <listitem>
    2669                 <para>a newly-allocated object of type CCL:SEMAPHORE.</para>
    2670               </listitem>
    2671             </varlistentry>
    2672           </variablelist>
    2673         </refsect1>
    2674 
    2675         <refsect1>
    2676           <title>Description</title>
    2677 
    2678           <para>Creates and returns an object of type CCL:SEMAPHORE.
    2679           A semaphore has an associated "count" which may be incremented
    2680           and decremented atomically; incrementing it represents sending
    2681           a signal, and decrementing it represents handling that signal.
    2682           <varname>semaphore</varname> has an initial count of 0.</para>
    2683         </refsect1>
    2684 
    2685         <refsect1>
    2686           <title>See Also</title>
    2687          
    2688           <simplelist type="inline">
    2689             <member><xref linkend="f_signal-semaphore"/></member>
    2690             <member><xref linkend="f_wait-on-semaphore"/></member>
    2691             <member><xref linkend="f_timed-wait-on-semaphore"/></member>
    2692             <member><xref linkend="f_make-lock"/></member>
    2693             <member><xref linkend="f_make-read-write-lock"/></member>
    2694             <member><xref linkend="f_process-input-wait"/></member>
    2695             <member><xref linkend="f_process-output-wait"/></member>
    2696             <member><xref linkend="m_with-terminal-input"/></member>
    2697           </simplelist>
    2698         </refsect1>
    2699       </refentry>
    2700 
    2701       <refentry id="f_signal-semaphore">
    2702         <indexterm zone="f_signal-semaphore">
    2703           <primary>signal-semaphore</primary>
    2704         </indexterm>
    2705 
    2706         <refnamediv>
    2707           <refname>SIGNAL-SEMAPHORE</refname>
    2708           <refpurpose>Atomically increments the count of a given
    2709           semaphore.</refpurpose>
    2710           <refclass>Function</refclass>
    2711         </refnamediv>
    2712 
    2713         <refsynopsisdiv>
    2714           <synopsis><function>signal-semaphore</function>
    2715           semaphore => result</synopsis>
    2716         </refsynopsisdiv>
    2717 
    2718         <refsect1>
    2719           <title>Arguments and Values</title>
    2720          
    2721           <variablelist>
    2722             <varlistentry>
    2723               <term>semaphore</term>
    2724               <listitem>
    2725                 <para>an object of type CCL:SEMAPHORE.</para>
    2726               </listitem>
    2727             </varlistentry>
    2728             <varlistentry>
    2729               <term>result</term>
    2730               <listitem>
    2731                 <para>an integer representing an error identifier
    2732                 which was returned by the underlying OS call.</para>
    2733               </listitem>
    2734             </varlistentry>
    2735           </variablelist>
    2736         </refsect1>
    2737 
    2738         <refsect1>
    2739           <title>Description</title>
    2740 
    2741           <para>Atomically increments <varname>semaphore</varname>'s
    2742           "count" by 1; this
    2743           may enable a waiting thread to resume execution.</para>
    2744         </refsect1>
    2745 
    2746         <refsect1>
    2747           <title>See Also</title>
    2748          
    2749           <simplelist type="inline">
    2750             <member><xref linkend="f_make-semaphore"/></member>
    2751             <member><xref linkend="f_wait-on-semaphore"/></member>
    2752             <member><xref linkend="f_timed-wait-on-semaphore"/></member>
    2753             <member><xref linkend="f_make-lock"/></member>
    2754             <member><xref linkend="f_make-read-write-lock"/></member>
    2755             <member><xref linkend="f_process-input-wait"/></member>
    2756             <member><xref linkend="f_process-output-wait"/></member>
    2757             <member><xref linkend="m_with-terminal-input"/></member>
    2758           </simplelist>
    2759         </refsect1>
    2760 
    2761         <refsect1>
    2762           <title>Notes</title>
    2763 
    2764           <para><varname>result</varname> should probably be interpreted
    2765           and acted on by <function>signal-semaphore</function>, because
    2766           it is not likely to be meaningful to a lisp program, and the
    2767           most common cause of failure is a type error.</para>
    2768         </refsect1>
    2769       </refentry>
    2770 
    2771       <refentry id="f_wait-on-semaphore">
    2772         <indexterm zone="f_wait-on-semaphore">
    2773           <primary>wait-on-semaphore</primary>
    2774         </indexterm>
    2775 
    2776         <refnamediv>
    2777           <refname>WAIT-ON-SEMAPHORE</refname>
    2778           <refpurpose>Waits until the given semaphore has a positive
    2779           count which can be atomically decremented.</refpurpose>
    2780           <refclass>Function</refclass>
    2781         </refnamediv>
    2782 
    2783         <refsynopsisdiv>
    2784           <synopsis><function>wait-on-semaphore</function>
    2785           semaphore => result</synopsis>
    2786         </refsynopsisdiv>
    2787 
    2788