Changeset 8981


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

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

Location:
trunk/source/doc/src
Files:
15 edited

Legend:

Unmodified
Added
Removed
  • trunk/source/doc/src/external-process.xml

    r8820 r8981  
    4747      <title>Limitations and known bugs</title>
    4848      <itemizedlist>
    49         <listitem><para>&CCL; and the external processs may get
    50         confused about whoowns which streams when input, output, or
     49        <listitem><para>&CCL; and the external process may get
     50        confused about who owns which streams when input, output, or
    5151        error are specified as T and wait is specified as
    5252        NIL.</para></listitem>
     
    216216                  <para>A user-defined function of one argument (the
    217217                  EXTERNAL-PROCESS structure.) This function is called
    218                   whenever &CCL; detects a change in the staus of the
     218                  whenever &CCL; detects a change in the status of the
    219219                  EXTERNAL-PROCESS.</para>
    220220                </listitem>
     
    273273
    274274            <para>Sends the specified "signal" to the specified
    275             external process. (Typically, it would only be useful tocall
     275            external process. (Typically, it would only be useful to call
    276276            this function if the EXTERNAL-PROCESS was created with :WAIT
    277277            NIL. ) Returns T if successful; signals an error otherwise.</para>
  • trunk/source/doc/src/ffi.xml

    r8903 r8981  
    6666          of <code>NS:NS-SIZE</code>, a pointer to
    6767          an <code>&lt;NSP&gt;oint</code> is recognized as an
    68           instsance of <code>NS:NS-POINT</code>, and a pointer to
     68          instance of <code>NS:NS-POINT</code>, and a pointer to
    6969          an <code>&lt;NSR&gt;ange</code> is recognized as an
    7070          instance of <code>NS:NS-RANGE</code>.</para>
     
    104104            are defined.  The accessors and setter functions typecheck
    105105            their arguments and the setters handle coercion to the
    106             approprate type of <code>CGFLOAT</code> where
     106            appropriate type of <code>CGFLOAT</code> where
    107107            applicable.</para>
    108108        </listitem>
     
    144144          <para>a macro is defined which, like <code>RLET</code>,
    145145            stack-allocates an instance of the foreign record type,
    146             optionally iniitializes that instance, and executes a body
     146            optionally initializes that instance, and executes a body
    147147            of code with a variable bound to that instance.</para>
    148148
     
    174174        <listitem>
    175175          <para>Constructors such as :SIGNED and :UNSIGNED can be
    176             used to denotesigned and unsigned integer subtypes
    177             (analogous to the CL typespecifiers SIGNED-BYTE and
     176            used to denote signed and unsigned integer subtypes
     177            (analogous to the CL type specifiers SIGNED-BYTE and
    178178            UNSIGNED-BYTE.) :SIGNED is shorthand for(:SIGNED 32) and
    179179            :UNSIGNED is shorthand for (:UNSIGNED 32).</para>
     
    181181        <listitem>
    182182          <para>Aliases for other (perhaps more complicated) types
    183             can bedefined via CCL:DEF-FOREIGN-TYPE (sort of like
    184             CL:DEFTYPE or the Ctypedef facility). The type :CHAR is
     183            can be defined via CCL:DEF-FOREIGN-TYPE (sort of like
     184            CL:DEFTYPE or the C typedef facility). The type :CHAR is
    185185            defined as an alias for (:SIGNED8) on some platforms, as
    186186            (:UNSIGNED 8) on others.</para>
     
    188188        <listitem>
    189189              <para>The construct (:STRUCT <emphasis>name</emphasis>)
    190                 can be used torefer to a named structure type; (:UNION
     190                can be used to refer to a named structure type; (:UNION
    191191                <emphasis>name</emphasis>)can be used to refer to a named
    192                 union type. It isn't necessary toenumerate a structure or
    193                 union type's fields in order to refer tothe type.</para>
     192                union type. It isn't necessary to enumerate a structure or
     193                union type's fields in order to refer to the type.</para>
    194194            </listitem>
    195195        <listitem>
    196196              <para>If <emphasis>X</emphasis> is a valid foreign type
    197197                reference,then (:* <emphasis>X</emphasis>) denotes the
    198                 foreign type "pointerto<emphasis> X</emphasis>". By
    199                 convention, (:* T) denotes ananonymous pointer type,
     198                foreign type "pointer to<emphasis> X</emphasis>". By
     199                convention, (:* T) denotes an anonymous pointer type,
    200200                vaguely equivalent to "void*" in C.</para>
    201201            </listitem>
     
    204204                is a foreign field name (keyword) and whose CADR is a
    205205                foreign type specifier, then (:STRUCT
    206                 <emphasis>name</emphasis> ,@fieldlist) is adefinition of
     206                <emphasis>name</emphasis> ,@fieldlist) is a definition of
    207207                the structure type <emphasis>name</emphasis>,
    208208                and (:UNION<emphasis> name</emphasis> ,@fieldlist) is a
    209                 definition of theunion type
     209                definition of the union type
    210210                <emphasis>name</emphasis>. Note that it's necessary
    211                 todefine a structure or union type in order to include
     211                to define a structure or union type in order to include
    212212                that type in a structure, union, or array, but only
    213                 necessary to "refer to" a strucure or union type in order
     213                necessary to "refer to" a structure or union type in order
    214214                to define a type alias or a pointer type.</para>
    215215            </listitem>
     
    217217              <para>If <emphasis>X</emphasis> is a defined foreign type
    218218                , then (:array <emphasis>X</emphasis> &amp;rest dims)
    219                 denotes the foreigntype "array of
    220                 <emphasis>X</emphasis>". Although multiplearray dimensions
     219                denotes the foreign type "array of
     220                <emphasis>X</emphasis>". Although multiple array dimensions
    221221                are allowed by the :array constructor,
    222222                only single-dimensioned arrays are (at all) well-supported
     
    246246      <para>There's no supported way to directly pass lisp data to
    247247        foreign functions: scalar lisp data must be coerced to an
    248         equivalent foreign representatation, and lisp arrays (notably
     248        equivalent foreign representation, and lisp arrays (notably
    249249        strings) must be copied to non-GCed memory.</para>
    250250
     
    362362              by value and how is very dependent on the Application
    363363              Binary Interface (ABI) of the platform; unless you're
    364               very familar with ABI detatils (some of which are quite
     364              very familiar with ABI details (some of which are quite
    365365              baroque), it's often easier to let higher-level constructs
    366366              deal with these details.</para>
     
    400400          <para><emphasis>Exactly</emphasis> how a C function that's
    401401            defined to return a foreign structure does so is dependent on
    402             the ABI (and on the size ad composition of the structure/union
     402            the ABI (and on the size and composition of the structure/union
    403403            in many cases.)</para>
    404404    </sect2>
     
    425425        <para>It's sometimes convenient to blur the distinction
    426426          between a MACPTR and the address it represents; it's
    427           sometimes necessary to maintain that distiction. It's
     427          sometimes necessary to maintain that distinction. It's
    428428          important to remember that a MACPTR is (generally) a
    429429          first-class Lisp object in the same sense that a CONS cell
     
    447447          <listitem>
    448448                <para>Creating a MACPTR with a specified address, usually
    449                   via thefunction CCL:%INT-TO-PTR.</para>
     449                  via the function CCL:%INT-TO-PTR.</para>
    450450              </listitem>
    451451          <listitem>
    452                 <para>Referencing the return valueof a foreign function
     452                <para>Referencing the return value of a foreign function
    453453                  call (see )that's specified to return an address.</para>
    454454              </listitem>
     
    483483          question of whether this code fragment exhibits a good way
    484484          to poll for external events (it doesn't), it's not hard to
    485           imagine that this loop could execute several millon times
     485          imagine that this loop could execute several million times
    486486          per second (producing several million MACPTRs per second.)
    487487          Clearly, the "naive" approach is impractical in many
     
    752752                <listitem>
    753753                      <para>References and returns an unsigned integer composed from the
    754                         width bits found bit-offsetbits from the address encapsulated by
     754                        width bits found bit-offset bits from the address encapsulated by
    755755                        ptr. (The least significant bit of the result is the value of
    756756                        (%get-bit ptr (1- (+ bit-offset width))). Can be used with SETF.</para>
     
    13111311
    13121312              <para>WITH-ENCODED-CSTRS does not automatically prepend
    1313                 bte-order marks to its output; the size of the terminating
     1313                byte-order marks to its output; the size of the terminating
    13141314                #\NUL character depends on the number of octets per code unit
    13151315                in the encoding.</para>
     
    14801480      <itemizedlist>
    14811481        <listitem>
    1482               <para>&CCL; now preserves the case of external symbols
    1483                 in itsdatabase files. See for information about case in
    1484                 foreign symbol names.</para>
     1482              <para>&CCL; now preserves the case of external symbols in
     1483                its database
     1484                files. See <link linkend="Case-sensitivity-of-foreign-names-in-CCL">Case-sensitivity
     1485                of foreign names in &CCL;</link> for information about
     1486                case in foreign symbol names.</para>
    14851487            </listitem>
    14861488            <listitem>
     
    15211523        headers/gnome/C/populate.sh
    15221524        headers/gnome/constants.cdb
    1523         headers/gnome/functions.cb
     1525        headers/gnome/functions.cdb
    15241526        headers/gnome/records.cdb
    15251527        headers/gnome/objc-classes.cdb
     
    15561558        distribution.  "libc" corresponds pretty closely to the
    15571559        interfaces associated with "glibc/libc6" header files, "gl"
    1558         corresponds to an "openGL+GLUT" developmnent package, "gtk"
     1560        corresponds to an "openGL+GLUT" development package, "gtk"
    15591561        and "gnome" contain interface information from the GTK+1.2 and
    15601562        GNOME libraries, respectively.</para>
     
    16821684        started, an attempt is made to reopen all libraries that were
    16831685        open when the image was saved, and an attempt is made to
    1684         resolve all entrypoints that had been referenced when the
     1686        resolve all entry points that had been referenced when the
    16851687        image was saved. Either of these attempts can fail "quietly",
    16861688        leaving some entry points in an unresolved state.</para>
     
    16931695        several names; the library's soname is often the most
    16941696        appropriate identifier.</para>
    1695       <para>sonames are often less version-specific than other names
     1697      <para>so names are often less version-specific than other names
    16961698        for libraries; a program that refers to a library by the name
    16971699        "libc.so.6" is more portable than one which refers to
     
    17271729          <itemizedlist>
    17281730        <listitem>
    1729               <para>"dylibs" (which often have the extension".dylib")
    1730                 are primarily intended to be linked against atcompile/link
     1731              <para>"dylibs" (which often have the extension".dylib") are
     1732                primarily intended to be linked against at compile/link
    17311733                time. They can be loaded dynamically,<emphasis>but can't
    1732                   be unloaded</emphasis>. Accordingly,OPEN-SHARED-LIBRARY
     1734                be unloaded</emphasis>. Accordingly,OPEN-SHARED-LIBRARY
    17331735                can be used to open a .dylib-style library;calling
    1734                 CLOSE-SHARED-LIBRARY on the result of such a callproduces
    1735                 a warning, and has no other effect.It appears that (due to
    1736                 an OS bug) attempts to open .dylibshared-libraries that
    1737                 are already open can cause memory corruptionunless the
    1738                 full pathname of the .dylib file is specified on thefirst
    1739                 and all subsequent calls.</para>
     1736                CLOSE-SHARED-LIBRARY on the result of such a call produces
     1737                a warning, and has no other effect. It appears that (due
     1738                to an OS bug) attempts to open .dylib shared-libraries
     1739                that are already open can cause memory corruption unless
     1740                the full pathname of the .dylib file is specified on the
     1741                first and all subsequent calls.</para>
    17401742            </listitem>
    17411743        <listitem>
     
    17551757    <title>The Interface Translator</title>
    17561758
    1757     <sect2 id="Inteface-translator-overview">
     1759    <sect2 id="Interface-translator-overview">
    17581760          <title>Overview</title>
    17591761          <para>&CCL; uses an interface translation system based on the FFIGEN
     
    18271829              <para>Ensure that the FFIGEN program is installed. See
    18281830                the"README" file in the source or binary archive for
    1829                 specificinstallation instructions.This example assumes
     1831                specific installation instructions.This example assumes
    18301832                LinuxPPC; for 32-bit DarwinPPC,
    18311833                substitute"ccl:darwin-headers;" for "ccl:headers;".  For
     
    18371839                "ccl:headers;<emphasis>subdir</emphasis>;C;populate.sh"shell
    18381840                script. When you're confident that the files
    1839                 andpreprocessor options match your environment, cd to
     1841                and preprocessor options match your environment, cd to
    18401842                the"ccl:headers;<emphasis>subdir</emphasis>;C;" directory
    1841                 andinvoke ./populate.sh. Repeat this step until you're
    1842                 able tocleanly translate all files refrenced in the shell
     1843                and invoke ./populate.sh. Repeat this step until you're
     1844                able to cleanly translate all files referenced in the shell
    18431845                script.</para>
    18441846            </listitem>
     
    18731875        many users (and implementors) would prefer not to deal with
    18741876        case-related issues. The fact that some information in the
    1875         interface databases was incomplete or inaccessable because of
     1877        interface databases was incomplete or inaccessible because of
    18761878        this policy made it clearer that the policy was untenable. I
    18771879        can't claim that the approach described here is aesthetically
     
    19391941        <listitem>
    19401942              <para>Any alphabetic characters in the symbol's pname
    1941                 thataren't enclosed in angle brackets are treated as
     1943                that aren't enclosed in angle brackets are treated as
    19421944                lower-case,regardless of the value of READTABLE-CASE and
    19431945                regardless of the case in which they were written.</para>
     
    19451947        <listitem>
    19461948              <para>Alphabetic characters that appear within angle
    1947                 brackets aremapped to upper-case, again regardless of how
    1948                 they were written orinterned.</para>
     1949                brackets are mapped to upper-case, again regardless of how
     1950                they were written or interned.</para>
    19491951            </listitem>
    19501952      </itemizedlist>
     
    26522654      new array, just keeps the same one and reverses what's in it.
    26532655      Finally, the C function passes control back to &CCL;.  Since
    2654       the allocated array memory has been directly modifed, &CCL;
     2656      the allocated array memory has been directly modified, &CCL;
    26552657      reflects those changes directly in the array as well.</para>
    26562658    <para>There is one final bit of housekeeping to deal with.
     
    27132715      &CCL;'s nonstandard "termination" mechanism, which is
    27142716      essentially the same as what Java and other languages call
    2715       "finialization".</para>
     2717      "finalization".</para>
    27162718    <para>Termination is a way of asking the garbage collector to
    27172719      let you know when it's about to destroy an object which isn't
     
    27622764    <para>If it makes sense to say that the foreign object should
    27632765      live as long as there's Lisp code that references it (through
    2764       the encapsulating obect) and no longer, this is one way of doing
     2766      the encapsulating object) and no longer, this is one way of doing
    27652767      that.</para>
    27662768    <para>Now we've covered passing basic types back and forth with
     
    28912893
    28922894            <para>Foreign variables in C code tend to be platform- and
    2893               packge-specific (the canonical example - &#34;errno&#34; - is typically
     2895              package-specific (the canonical example - &#34;errno&#34; - is typically
    28942896              not a variable when threads are involved. )</para>
    28952897
     
    30453047
    30463048        <para>The argument and result coercion that the bridge has
    3047           tradionally supported is supported by the new mechanism (e.g.,
     3049          traditionally supported is supported by the new mechanism (e.g.,
    30483050          :&lt;BOOL&gt; arguments can be specified as lisp booleans and :&lt;BOOL&gt;
    30493051          results are returned as lisp boolean values, and an argument
     
    37503752
    37513753        <para>If the argument to <code>CCL:FREE</code> is a gcable
    3752         pointer (for example, an object reurned
     3754        pointer (for example, an object returned
    37533755        by <code>MAKE-GCABLE-RECORD</code>)
    37543756        then <code>CCL:FREE</code> informs the garbage collector that
     
    39193921
    39203922            <para>
    3921               Expands into code which allocates and initalizes
     3923              Expands into code which allocates and initializes
    39223924              an instance of the type
    39233925              denoted by <varname>typespec</varname>, on the foreign
     
    39743976              that would mean that any stand-alone application using it would
    39753977              have to include a copy of the interface database
    3976               (see <xref linkend="The-Interface-Database"/>), which is undesireable
     3978              (see <xref linkend="The-Interface-Database"/>), which is undesirable
    39773979              because it's large.
    39783980            </para>
     
    43044306              bound to <link
    43054307                          linkend="Referencing-and-Using-Foreign-Memory-Addresses">a
    4306                 MACPTR</link> encapuslating the address of a stack-allocated
     4308                MACPTR</link> encapsulating the address of a stack-allocated
    43074309              foreign memory block, allocated and initialized from
    43084310              typespec and initforms as ccl:make-record.</para>
  • trunk/source/doc/src/gc.xml

    r8820 r8981  
    2828      after each full GC, the lisp kernel will try to ensure that a
    2929      specified amount (the "lisp-heap-gc-threshold") of free memory
    30       is available. The inital value of this kernel variable is 16MB
     30      is available. The initial value of this kernel variable is 16MB
    3131      on 32-bit implementations and 32MB on 64-bit implementations ;
    3232      it can be manipulated from Lisp (see below.)</para>
     
    116116      necessary to do more expensive GCs of the entire heap in order
    117117      to reclaim unreferenced memory.  In some environments, the
    118       pauses associated with such full GCs can be noticable and
     118      pauses associated with such full GCs can be noticeable and
    119119      disruptive, and minimizing the frequency (and sometimes the
    120120      duration) of these pauses is probably the EGC's primary goal
     
    124124      amortized GC time), but there are cases where it can improve
    125125      overall performance as well; the nature and degree of its impact
    126       on performance is highly application-dependant.</para>
     126      on performance is highly application-dependent.</para>
    127127      <para>Most EGC strategies (including the one employed by
    128128      &CCL;) logically or physically divide memory into one or more
     
    136136      This filtering process isn't perfect - a certain amount of
    137137      premature tenuring may take place - but it usually works very
    138       well in practive.</para>
     138      well in practice.</para>
    139139      <para>It's important to note that a GC of the youngest
    140140      generation is typically very fast (perhaps a few milliseconds on
     
    185185      <para>For some programs (especially those that cons at a very
    186186      high rate), the default policy may be less than ideal: releasing
    187       pages that're going to be needed almost immediately - and
     187      pages that are going to be needed almost immediately - and
    188188      zero-fill-faulting them back in, lazily - incurs unnecessary
    189189      overhead. (There's a false economy associated with minimizing
     
    236236      their memory will never be reclaimed, even if they are
    237237      referenced nowhere else in the program.  You may want this
    238       behaviour.  If you don't, you need weak references.</para>
     238      behavior.  If you don't, you need weak references.</para>
    239239      <para>&CCL; supports weak references with "weak hash tables".
    240240      Hash tables may be weak with respect to either their keys or
  • trunk/source/doc/src/glossary.xml

    r8894 r8981  
    288288
    289289                <para>A variable whose binding is in the dynamic
    290                 environment. Special variables are essentally equivalent to
     290                environment. Special variables are essentially equivalent to
    291291                global variables in languages other than Lisp. A special
    292292                variable binding is visible in any lexical environment, so
  • trunk/source/doc/src/ide.xml

    r8894 r8981  
    148148        the case of a simple data value such as a character, to the
    149149        complex, in the case of structured data such as lists or CLOS
    150         objects. The lefthand column of the window's display shows the
     150        objects. The left-hand column of the window's display shows the
    151151        names of the object's attributes; the righthand column shows the
    152152        values associated with those attributes. You can inspect the
     
    189189      using <code>REQUIRE</code>. For example, if you want to use the
    190190      Cocoa features of &CCL; from a terminal session (or from an Emacs
    191       session using SLIE or ILISP), you can evaluate <code>(require
     191      session using SLIME or ILISP), you can evaluate <code>(require
    192192        :cocoa)</code>.</para>
    193193  </sect1>
     
    319319        <term><varname>application-class</varname></term>
    320320        <listitem>
    321           <para>The name of the application's CLOS class. The defaut
     321          <para>The name of the application's CLOS class. The default
    322322            value is the class provided by &CCL; for graphical
    323323            applications. Supply the name of your application class if you
     
    348348    easy way to specify an application delegate different from the
    349349    default. If you find the current limitations
    350     of <code>BUILD-APPLICATION</code> too restrictive, and want to rty
     350    of <code>BUILD-APPLICATION</code> too restrictive, and want to try
    351351    extending it for your use, you can find the source code for it
    352352    in "ccl/cocoa-ide/build-application.lisp".</para>
  • trunk/source/doc/src/implementation.xml

    r8976 r8981  
    2828      implications of this are discussed elsewhere; this section tries
    2929      to describe how threads look from the lisp kernel's perspective
    30       (and especailly from the GC's point of view.)</para>
     30      (and especially from the GC's point of view.)</para>
    3131      <para>&CCL;'s runtime system tries to use machine-level
    3232      exception mechanisms (conditional traps when available, illegal
     
    9393        thread's value stack, and (on x86-64) RSP is switched to the
    9494        control stack.  A field in the TCR (tcr.valence) is then set
    95         to indicate that the thread is running foreigm code, foreign
     95        to indicate that the thread is running foreign code, foreign
    9696        argument registers are loaded from a frame on the foreign
    9797        stack, and the foreign function is called. (That's a little
     
    115115        execute an illegal instruction or access protected memory.)
    116116        It makes some sense to defer ("block") handling of
    117         aysnchronous signals so that some critical code sequences
     117        asynchronous signals so that some critical code sequences
    118118        complete without interruption; since it's generally not
    119119        possible for a thread to proceed after a synchronous exception
     
    136136        &CCL; uses Mach thread-level exception handling facilities
    137137        which run before GDB or CrashReporter get a chance to confuse
    138         themeselves; &CCL;'s Mach exception handling tries to force
     138        themselves; &CCL;'s Mach exception handling tries to force
    139139        the thread which received a synchronous exception to invoke a
    140140        signal handling function ("as if" signal handling worked more
     
    155155        signals blocked.  (This behavior is specified in the call to
    156156        the sigaction() function which established the signal
    157         handler.)  The signal handler recieves three arguments from
    158         the OS kernel; the first is an intger which identifies the
     157        handler.)  The signal handler receives three arguments from
     158        the OS kernel; the first is an integer which identifies the
    159159        signal, the second is a pointer to an object of type
    160160        "siginfo_t", which may or may not contain a few fields that
     
    173173        <para>On Darwin, the Mach exception thread creates a signal
    174174        context (and maybe a siginfo_t structure), stores the signal
    175         context in the thread's TCR, sets the TCR field wich describes
     175        context in the thread's TCR, sets the TCR field which describes
    176176        the thread's state, and arranges that the thread resume
    177177        execution at its signal handling function (with a signal
     
    193193        signal to be delivered on (and the signal context and siginfo
    194194        to be allocated on) a special stack area (the last few pages
    195         of the thread's cntrol stack, in practice.  When the signal
     195        of the thread's control stack, in practice.  When the signal
    196196        handler runs, it (carefully) copies the signal context and
    197197        siginfo to the thread's control stack and makes RSP point into
     
    233233        signal, then iterates over the list again, waiting for a
    234234        per-thread semaphore that indicates that the thread has
    235         received the "suspend" signal and responded appropriatedly.
     235        received the "suspend" signal and responded appropriately.
    236236        Once all other threads have acknowledged the request to
    237237        suspend themselves, the GC thread can run the GC proper (after
     
    265265            fully atomic.It takes at least a few instructions to
    266266            allocate an object in memory(and slap a header on it if
    267             necesssary); if a thread is interrupted inthe middle of
     267            necessary); if a thread is interrupted in the middle of
    268268            that instruction sequence, the new object may or may
    269             nothave been created or fully initialized at the point in
    270             time that theinterrupt occurred.  (There are actually a
    271             few different states ofpartial initialization)</para>
     269            not have been created or fully initialized at the point in
     270            time that the interrupt occurred.  (There are actually a
     271            few different states of partial initialization)</para>
    272272          </listitem>
    273273          <listitem>
     
    306306        interrupting thread to recognize when the interrupted thread
    307307        is in the middle of such a sequence.  When this is detected,
    308         the interrupting thread modfies the state of the interrupted
     308        the interrupting thread modifies the state of the interrupted
    309309        thread (modifying its PC and other registers) so that it is no
    310         longer in the middle of such a sequenece (it's either backed
     310        longer in the middle of such a sequence (it's either backed
    311311        out of it or the remaining instructions are emulated.)</para>
    312312        <para>This works because (a) many of the troublesome
     
    383383        a <xref linkend="Tagging-scheme"/> describes how the node's
    384384        value and type are encoded in that machine word.</para>
    385         <para>Most of this - so far - has discussed thigs from the
     385        <para>Most of this - so far - has discussed things from the
    386386        GC's very low-level perspective.  From a much higher point of
    387387        view, lisp functions accept nodes as arguments, return nodes
     
    407407        cases where locatives are allowed in &CCL; mostly involve
    408408        the behavior of function call and return instructions.  (To be
    409         technicaly accurate, the other case also arises on x86-64, but
     409        technically accurate, the other case also arises on x86-64, but
    410410        that case isn't as user-visible.)</para>
    411411        <para>On the PowerPC (both PPC32 and PPC64), all machine
    412         instructions are 32 bits wide and all in1struction words are
     412        instructions are 32 bits wide and all instruction words are
    413413        allocated on 32-bit boundaries.  In PPC &CCL;, a CODE-VECTOR
    414414        is a specialized type of vector-like object; its elements are
     
    423423        and aligned on 32-bit boundaries, the low two bits of the PC
    424424        are always 0.  If the function executes a call (simple call
    425         instrucions have the mnemonic "bl" on the PPC, which stands
     425        instructions have the mnemonic "bl" on the PPC, which stands
    426426        for "branch and link"), the address of the next instruction
    427427        (also a word-aligned locative into a code-vector) is copied
     
    434434        <para>&CCL;'s GC understands that certain registers contain
    435435        these special "pc-locatives" (locatives that point into
    436         CODE-VECTOR objects); it contains specal support for finding
     436        CODE-VECTOR objects); it contains special support for finding
    437437        the containing CODE-VECTOR object and for adjusting all of
    438438        these "pc-locatives" if the containing object is moved in
    439439        memory.  The first part of that - finding the containing
    440440        object - is possible and practical on the PPC because of
    441         architectural artifcacts (fixed-width instructions and arcana
     441        architectural artifacts (fixed-width instructions and arcana
    442442        of instruction encoding.)  It's not possible on x86-64, but
    443443        fortunately not necessary either (though the second part -
     
    502502              addresses the top of the value stack when running lisp
    503503              code; that address is saved in the TCR when running
    504               foreign code.  On the PPC, a dedicated regiter (VSP,
     504              foreign code.  On the PPC, a dedicated register (VSP,
    505505              currently r15) is used to address the top of the value
    506506              stack when running lisp code, and the VSP value is saved
     
    532532              x86-64, where temp stack frames always contain nodes,
    533533              the second word is always 0.  The temp stack grows down.
    534               It usually takes several instuctions to allocate and
     534              It usually takes several instructions to allocate and
    535535              safely initialize a temp stack frame that's intended to
    536536              contain nodes, and the GC has to recognize the case
     
    595595              <para>All other registers (RBX, RSI, RDI, and R8-R15)
    596596              are asserted to contain node values at (almost) all
    597               times; legacy "string" operationsthat implicitly use RSI
     597              times; legacy "string" operations that implicitly use RSI
    598598              and/or RDI are not used.</para>
    599599            </listitem>
     
    618618                <listitem>
    619619                  <para>r0 (symbolic name rzero) always contains the
    620                   value 0 when runninglisp code.  Its value is
     620                  value 0 when running lisp code.  Its value is
    621621                  sometimes read as 0 when it's used as the base
    622622                  register in a memory address; keeping the value 0
     
    651651                </listitem>
    652652                <listitem>
    653                   <para>r13 is used to hold the TCR on PPC32 sytems;
     653                  <para>r13 is used to hold the TCR on PPC32 systems;
    654654                  it's not used on PPC64.</para>
    655655                </listitem>
     
    717717        fields of things like CONS cells and structures, it's
    718718        desirable that that the tags chosen for CONS cells and
    719         structures allow the use of these intructions as opposed to
     719        structures allow the use of these instructions as opposed to
    720720        more expensive alternatives.)</para>
    721721        <para>One architecture-dependent tagging trick that works well
     
    755755            usually fairly common.It therefore makes sense to give
    756756            CONS cells their own tag.  Unlike the fixnum case - where a
    757             tag value of 0 had positive implications - theredoesn't
     757            tag value of 0 had positive implications - there doesn't
    758758            seem to be any advantage to using any particular value.
    759759            (A longtime ago - in the case of 68K MCL - the CONS tag
     
    816816            uniformly.There are some disadvantages to that uniform
    817817            treatment as well, and the treatment of "memory-allocated
    818             non-CONS objects" isn't entirely uniform accross all
     818            non-CONS objects" isn't entirely uniform across all
    819819            &CCL; implementations.  Let's first pretend that
    820820            the treatment is uniform, then discuss the ways in which it
    821821            isn't.The "uniform approach" is to treat all
    822             memory-allocated non-CONS objectsas if they were vectors;
     822            memory-allocated non-CONS objects as if they were vectors;
    823823            this use of the term is a little looser than what's implied
    824824            by the CL VECTOR type.  &CCL; actually uses the
     
    880880      <para>Reserving address space that can't (yet) be read or
    881881      written to doesn't cost much; in particular, it doesn't require
    882       that correspinding swap space or physical memory be available.
     882      that corresponding swap space or physical memory be available.
    883883      Marking the address range as being "mapped" helps to ensure that
    884884      other things (results from random calls to malloc(), dynamically
     
    908908        maintained in the current threads's TCR.  (An "empty" heap
    909909        segment is one whose high pointer and low pointer are equal.)
    910         When a thread is not in the midde of allocating something, the
     910        When a thread is not in the middle of allocating something, the
    911911        low 3 or 4 bits of the high and low pointers are clear (the
    912912        pointers are doublenode-aligned.)</para>
     
    974974        <para>If a thread traps while trying to allocate memory, the
    975975        thread goes through the usual exception-handling protocol (to
    976         ensure that any oher thread that GCs "sees" the state of the
     976        ensure that any other thread that GCs "sees" the state of the
    977977        trapping thread and to serialize exception handling.)  When
    978978        the exception handler runs, it determines the nature and size
     
    987987        GC before returning a new segment.  It's worth noting that the
    988988        [E]GC is triggered based on the number of and size of these
    989         segments that've been allocated since the last GC; it doesn't
     989        segments that have been allocated since the last GC; it doesn't
    990990        have much to do with how "full" each of those per-thread
    991991        segments are.  It's possible for a large number of threads to
     
    10161016        condition if lisp is ... out of memory</para>
    10171017        <para>I don't know that I've ever seen an abrupt out-of-memory
    1018         failure that wasn't preceeded by several minutes of excessive
     1018        failure that wasn't preceded by several minutes of excessive
    10191019        paging activity.  The most expedient course in cases like this
    10201020        is to either (a) use less memory or (b) get more memory; it's
     
    10441044          <para>the relocation table, which contains a native word for
    10451045          every 32 or 64 doublenodes in the dynamic heap, plus an
    1046           extra word used to keep trackof the end of the heap.</para>
     1046          extra word used to keep track of the end of the heap.</para>
    10471047        </listitem>
    10481048      </orderedlist>
     
    10551055        <para>Each doublenode in the dynamic heap has a corresponding
    10561056        bit in the markbits vector. (For any doublenode in the heap,
    1057         the index of its mark bit is determined by subtracing the
     1057        the index of its mark bit is determined by subtracting the
    10581058        address of the start of the heap from the address of the
    10591059        object and dividing the result by 8 or 16.) The GC knows the
     
    11151115              , </emphasis>the vector which contains the
    11161116              internal symbols of the current package is marked on
    1117               entry to the mark phasebut the symbols themselves are
     1117              entry to the mark phase, but the symbols themselves are
    11181118              not marked at this time. Near the end of the mark phase,
    11191119              symbols referenced from this vector which are
     
    11501150        precede it>)) or alternately (&lt;the base of the heap> +
    11511151        (size_of_doublenode * &lt;the number of marked markbits that
    1152         preced it &gt;)). Rather than count the number of preceding
     1152        precede it &gt;)). Rather than count the number of preceding
    11531153        markbits each time, the relocation table is used to precompute
    11541154        an approximation of the forwarding addresses for all
     
    12221222        any allocation request that may have triggered the GC, the
    12231223        exception handler returns; otherwise, a "seriously low on
    1224         memory" condition is signalled, possibly after releasing a
     1224        memory" condition is signaled, possibly after releasing a
    12251225        small emergency pool of memory.</para>
    12261226      </sect2>
     
    12481248        <listitem>
    12491249          <para>old objects can only point to newer objects as the
    1250           result of adestructive modification (e.g., via
     1250          result of a destructive modification (e.g., via
    12511251          SETF.)</para>
    12521252        </listitem>
     
    12931293      <itemizedlist>
    12941294        <listitem>
    1295           <para>the "base of the heap" used to determine anobject's
     1295          <para>the "base of the heap" used to determine an object's
    12961296          markbit address is the base of the generation
    12971297          being collected;</para>
     
    13101310        <listitem>
    13111311          <para>the intergenerational references table is used to
    1312           findadditional roots for the mark and forward phases. If a
     1312          find additional roots for the mark and forward phases. If a
    13131313          bit is set inthe intergenerational references table, that
    1314           means that thecorresponding doubleword (in some "old"
    1315           generation, insome "earlier" part of the heap) may have had
    1316           a pointerto an object in a younger generation stored into
     1314          means that the corresponding doubleword (in some "old"
     1315          generation, in some "earlier" part of the heap) may have had
     1316          a pointer to an object in a younger generation stored into
    13171317          it.</para>
    13181318        </listitem>
     
    14291429        that are introduced to the lisp runtime in other ways (as
    14301430        function arguments, return values, SLOT-VALUE results, etc. as
    1431         well as those instances that're created under lisp
     1431        well as those instances that are created under lisp
    14321432        control.)</para>
    14331433        <para>This doesn't all work yet (in fact, not much of it works
  • trunk/source/doc/src/install.xml

    r8822 r8981  
    157157        <listitem>
    158158          <para>Configuring a shell script so &CCL; can locate
    159           necessary library files and other auxilliary files.</para>
     159          necessary library files and other auxiliary files.</para>
    160160        </listitem>
    161161      </orderedlist>
     
    200200      </sect2>
    201201
    202       <sect2 id="The-openmcl-Shell-Script"><title>The openmcl Shell Script"</title>
     202      <sect2 id="The-openmcl-Shell-Script"><title>The openmcl Shell Script</title>
    203203      <para>&CCL; needs to be able to find the
    204204      <literal>ccl</literal> directory in order to support features
     
    237237            a local variable (<literal>OPENMCL_KERNEL</literal>) to
    238238            the standard name of the &CCL; kernel approprate for the
    239             platform (asdetermined by 'uname -s'.) You might prefer to
     239            platform (as determined by 'uname -s'.) You might prefer to
    240240            set this variable manually in the shell script</para>
    241241          </listitem>
     
    246246            ~/openmcl/ccl/scripts/openmcl64</literal>This command
    247247            grants execute permission to the named script. If you
    248             areusing a 32-bit platform, substitute "openmcl" in place
     248            are using a 32-bit platform, substitute "openmcl" in place
    249249            of "openmcl64".
    250250            <warning>
     
    309309        "home:openmcl-init")</literal>.  If it is unable to load the
    310310        file (for example because it does not exist) no action is
    311         taken; an error is not signalled.</para>
     311        taken; an error is not signaled.</para>
    312312        <para>The <literal>"home:"</literal> prefix to the filename is
    313313        a Common Lisp logical host, which &CCL; initializes to refer
     
    414414            supports XEmacs Version21. Mac OS X includes an Emacs
    415415            installation.  If you want to look into different versions,
    416             you can check out theEmacsWiki, whichmaintains a
     416            you can check out theEmacsWiki, which maintains a
    417417            page,EmacsForMacOS,that provides much more information
    418418            about using Emacs on the Mac.
     
    421421              Aquamacs. This application is a version of GNU Emacs
    422422              with a number of customizations meant to make it behave
    423               more like a standard Maciontosh application, with
     423              more like a standard Macintosh application, with
    424424              windows, a menubar, etc.  Aquamacs includes SLIME; if
    425425              you like Aquamacs then you can use SLIME right away,
    426426              without getting and installing it separately. You just
    427427              need to tell SLIME where to find your installation of
    428               &CCL;. (See FIXTHIS.)</para>
     428              &CCL;.</para>
    429429            </warning>
    430430          </para>
     
    436436            than<literal>"~/openmcl/ccl"</literal> then these
    437437            instructions still work, but you must remember to use your
    438             path to your ccl directory instead of theone that we give
     438            path to your ccl directory instead of the one that we give
    439439            here.</para>
    440440          </listitem>
     
    445445            you prefer to install Emacs add-ons in some place other
    446446            than<literal>"~/emacs/site/"</literal> then you must
    447             remember to use your path toEmacs add-ons in place of
     447            remember to use your path to Emacs add-ons in place of
    448448            ours.</para>
    449449          </listitem>
  • trunk/source/doc/src/modifying.xml

    r8820 r8981  
    8888Continue/Debugger/eXit &lt;enter&gt;?
    8989</programlisting>
     90
    9091      <para>As you may have noticed, it's not a perfect world; it's rare
    91 that the cause (attempting to reference the CDR of -1, and therefore
    92 accessing unmapped memory near location 0) of this effect (an
    93 "Unhandled exception ..." message) is so obvious.</para>
     92        that the cause (attempting to reference the CDR of -1, and therefore
     93        accessing unmapped memory near location 0) of this effect (an
     94        "Unhandled exception ..." message) is so obvious.</para>
    9495      <para>The addresses printed in the message above aren't very useful
    95 unless you're debugging the kernel with GDB (and they're often
    96 very useful if you are.)</para>
     96        unless you're debugging the kernel with GDB (and they're often
     97        very useful if you are.)</para>
    9798      <para>Aside from causing an exception that the lisp kernel doesn't
    98 know how to handle, one can also enter the kernel debugger (more)
    99 deliberately:</para>
     99        know how to handle, one can also enter the kernel debugger (more)
     100        deliberately:</para>
     101
    100102      <programlisting>
    101103? (defun classify (n)
     
    113115[12345] &CCL; kernel debugger:
    114116      </programlisting>
     117
    115118      <para>CCL::BUG isn't quite the right tool for this example (a
    116       call to BREAK or PRINT might do a better job of clearing up the
    117       mystery), but it's sometimes helpful when those other tools
    118       can't be used.  The lisp error system notices, for instance, if
    119       attempts to signal errors themselves cause errors to be
    120       signaled; this sort of thing can happen if CLOS or the I/O
    121       system are broken or missing. After some small number of
    122       recursive errors, the error system gives up and calls
    123       CCL::BUG.</para>
     119        call to BREAK or PRINT might do a better job of clearing up the
     120        mystery), but it's sometimes helpful when those other tools
     121        can't be used.  The lisp error system notices, for instance, if
     122        attempts to signal errors themselves cause errors to be
     123        signaled; this sort of thing can happen if CLOS or the I/O
     124        system are broken or missing. After some small number of
     125        recursive errors, the error system gives up and calls
     126        CCL::BUG.</para>
    124127      <para>If one enters a '?' at the kernel debugger prompt, one
    125       will see output like:</para>
     128        will see output like:</para>
     129
    126130      <programlisting>
    127131(S)  Find and describe symbol matching specified name
     
    130134(K)  Kill &CCL; process
    131135(?)  Show this help
    132 </programlisting>
     136      </programlisting>
     137
    133138      <para>CCL::BUG just does an FF-CALL into the lisp kernel.  If
    134       the kernel debugger was invoked because of an unhandled
    135       exception (such as an illegal memory reference) the OS kernel
    136       saves the machine state ("context") in a data structure for us,
    137       and in that case some additional options can be used to display
    138       the contents of the registers at the point of the
    139       exception. Another function - CCL::DBG - causes a special
    140       exception to be generated and enters the lisp kernel debugger
    141       with a non-null "context":</para>
     139        the kernel debugger was invoked because of an unhandled
     140        exception (such as an illegal memory reference) the OS kernel
     141        saves the machine state ("context") in a data structure for us,
     142        and in that case some additional options can be used to display
     143        the contents of the registers at the point of the
     144        exception. Another function - CCL::DBG - causes a special
     145        exception to be generated and enters the lisp kernel debugger
     146        with a non-null "context":</para>
     147
    142148      <programlisting>
    143149? (defun classify2 (n)
     
    165171(?)  Show this help
    166172</programlisting>
     173
    167174      <para>CCL::DBG takes an argument, whose value is copied into the register
    168 that &CCL; uses to return a function's primary value (arg_z, which
    169 is r23 on the PowerPC). If we were to choose the (L) option at this point,
    170 we'd see a dislay like:</para>
    171       <programlisting>rnil = 0x01836015
     175        that &CCL; uses to return a function's primary value (arg_z, which
     176        is r23 on the PowerPC). If we were to choose the (L) option at this point,
     177        we'd see a dislay like:</para>
     178
     179      <programlisting>
     180rnil = 0x01836015
    172181nargs = 0
    173182r16 (fn) = #&lt;Function CLASSIFY2 #x30379386>
     
    187196r25 (save6) = ()
    188197r24 (save7) = ()
    189 </programlisting>
     198      </programlisting>
     199
    190200      <para>From this we can conclude that the problematic argument to CLASSIFY2
    191 was 0 (see r23/arg_z), and that I need to work on a better example.</para>
     201        was 0 (see r23/arg_z), and that I need to work on a better example.</para>
    192202      <para>The R option shows the values of the ALU (and PPC branch unit)
    193 registers in hex; the F option shows the values of the FPU registers.</para>
     203        registers in hex; the F option shows the values of the FPU registers.</para>
    194204      <para>The (B) option shows a raw stack backtrace; it'll try to
    195 identify foreign functions as well as lisp functions. (Foreign function
    196 names are guesses based on the nearest preceding exported symbol.)</para>
     205        identify foreign functions as well as lisp functions. (Foreign function
     206        names are guesses based on the nearest preceding exported symbol.)</para>
    197207      <para>If you ever unexpectedly find yourself in the "lisp kernel
    198 debugger", the output of the (L) and (B) options are often the most
    199 helpful things to include in a bug report.</para>
     208        debugger", the output of the (L) and (B) options are often the most
     209        helpful things to include in a bug report.</para>
    200210    </sect1>
    201211
     
    205215      <sect2 id="Overview--16-">
    206216        <title>Overview</title>
    207         <para>It's now possible to use AltiVec instructions in PPC LAP
    208         (assembler) functions.</para>
    209         <para>The lisp kernel detects the presence or absence of
    210         AltiVec and preserves AltiVec state on lisp thread switch and
    211         in response to exceptions, but the implementation doesn't
    212         otherwise use vector operations.</para>
    213         <para>This document doesn't document PPC LAP programming in
    214         general.  Ideally, there would be some document that
    215         did.</para>
    216         <para>This document does explain AltiVec register-usage
    217         conventions in &CCL; and explains the use of some lap macros
    218         that help to enforce those conventions.</para>
    219         <para>All of the global symbols described below are exported
    220         from the CCL package. Note that lap macro names, ppc
    221         instruction names, and (in most cases) register names are
    222         treated as strings, so this only applies to functions and
    223         global variable names.</para>
    224         <para>Much of the &CCL; support for AltiVec LAP programming
    225         is based on work contributed to MCL by Shannon Spires.</para>
     217    <para>It's now possible to use AltiVec instructions in PPC LAP
     218      (assembler) functions.</para>
     219    <para>The lisp kernel detects the presence or absence of
     220      AltiVec and preserves AltiVec state on lisp thread switch and
     221      in response to exceptions, but the implementation doesn't
     222      otherwise use vector operations.</para>
     223    <para>This document doesn't document PPC LAP programming in
     224      general.  Ideally, there would be some document that
     225      did.</para>
     226    <para>This document does explain AltiVec register-usage
     227      conventions in &CCL; and explains the use of some lap macros
     228      that help to enforce those conventions.</para>
     229    <para>All of the global symbols described below are exported
     230      from the CCL package. Note that lap macro names, ppc
     231      instruction names, and (in most cases) register names are
     232      treated as strings, so this only applies to functions and
     233      global variable names.</para>
     234    <para>Much of the &CCL; support for AltiVec LAP programming
     235      is based on work contributed to MCL by Shannon Spires.</para>
    226236      </sect2>
    227237
    228238      <sect2 id="Register-usage-conventions">
    229239        <title>Register usage conventions</title>
    230         <para>&CCL; LAP functions that use AltiVec instructions must
    231         interoperate with each other and with C functions; that
    232         suggests that they follow C AltiVec register usage
    233         conventions. (vr0-vr1 scratch, vr2-vr13 parameters/return
    234         value, vr14-vr19 temporaries, vr20-vr31 callee-save
    235         non-volatile registers.)</para>
    236         <para>The EABI (Embedded Application Binary Interface) used in
    237         LinuxPPC doesn't ascribe particular significance to the vrsave
    238         special-purpose register; on other platforms (notably MacOS),
    239         it's used as a bitmap which indicates to system-level code
    240         which vector registers contain meaningful values.</para>
    241         <para>The WITH-ALTIVEC-REGISTERS lapmacro generates code which
    242         which saves, updates, and restores VRSAVE on platforms where
    243         this is required (as indicated by the value of the special
    244         variable which controls this) and ignores VRSAVE on platforms
    245         that don't require it to be maintained.</para>
    246         <para>On all PPC platforms, it's necessary to save any non-volatile
    247 vector registers (vr20 .. vr31) before assigning to them and to restore
    248 such registers before returning to the caller.</para>
    249         <para>On platforms that require that VRSAVE be maintained, it's not
    250 necessary to mention the "use" of vector registers that're
    251 used as incoming parameters. It's not incorrect to mention their use
    252 in a WITH-ALTIVEC-REGISTERS form, but it may be unneccessary in many
    253 interesting cases. One can likewise assume that the caller of any function
    254 that returns a vector value (in vr2 has already set the apropriate bit in
    255 VRSAVE to indicate that this register is live. One could therefore write a
    256 leaf function that added the bytes in vr3 and vr2 and returned the result
    257 in vr2 as:</para>
     240    <para>&CCL; LAP functions that use AltiVec instructions must
     241      interoperate with each other and with C functions; that
     242      suggests that they follow C AltiVec register usage
     243      conventions. (vr0-vr1 scratch, vr2-vr13 parameters/return
     244      value, vr14-vr19 temporaries, vr20-vr31 callee-save
     245      non-volatile registers.)</para>
     246    <para>The EABI (Embedded Application Binary Interface) used in
     247      LinuxPPC doesn't ascribe particular significance to the vrsave
     248      special-purpose register; on other platforms (notably MacOS),
     249      it's used as a bitmap which indicates to system-level code
     250      which vector registers contain meaningful values.</para>
     251    <para>The WITH-ALTIVEC-REGISTERS lapmacro generates code which
     252      which saves, updates, and restores VRSAVE on platforms where
     253      this is required (as indicated by the value of the special
     254      variable which controls this) and ignores VRSAVE on platforms
     255      that don't require it to be maintained.</para>
     256    <para>On all PPC platforms, it's necessary to save any non-volatile
     257      vector registers (vr20 .. vr31) before assigning to them and to restore
     258      such registers before returning to the caller.</para>
     259    <para>On platforms that require that VRSAVE be maintained, it's not
     260      necessary to mention the "use" of vector registers that are
     261      used as incoming parameters. It's not incorrect to mention their use
     262      in a WITH-ALTIVEC-REGISTERS form, but it may be unnecessary in many
     263      interesting cases. One can likewise assume that the caller of any function
     264      that returns a vector value (in vr2 has already set the appropriate bit in
     265      VRSAVE to indicate that this register is live. One could therefore write a
     266      leaf function that added the bytes in vr3 and vr2 and returned the result
     267      in vr2 as:</para>
     268
    258269        <programlisting>
    259270(defppclapfunction vaddubs ((y vr3) (z vr2))
     
    261272  (blr))
    262273</programlisting>
     274
    263275        <para>When vector registers that aren't incoming parameters are used
    264 in a LAP function, WITH-ALTIVEC-REGISTERS takes care of maintaining VRSAVE
    265 and of saving/restoring any non-volatile vector registers:</para>
     276          in a LAP function, WITH-ALTIVEC-REGISTERS takes care of maintaining VRSAVE
     277          and of saving/restoring any non-volatile vector registers:</para>
     278
    266279        <programlisting>
    267280(defppclapfunction load-array ((n arg_z))
     
    276289    (dbg t)) ; Look at result in some debugger
    277290  (blr))
    278 </programlisting>
     291        </programlisting>
     292
    279293        <para>AltiVec registers are not preserved by CATCH and UNWIND-PROTECT.
    280 Since AltiVec is only accessible from LAP in &CCL; and since LAP
    281 functions rarely use high- level control structures, this should rarely be
    282 a problem in practice.</para>
     294          Since AltiVec is only accessible from LAP in &CCL; and since LAP
     295          functions rarely use high- level control structures, this should rarely be
     296          a problem in practice.</para>
    283297        <para>LAP functions which use non-volatile vector registers and which call
    284 (Lisp ?) code which may use CATCH or UNWIND-PROTECT should save those
    285 vector registers before such a call and restore them on return. This is
    286 one of the intended uses of the WITH-VECTOR-BUFFER lap macro.</para>
     298          (Lisp ?) code which may use CATCH or UNWIND-PROTECT should save those
     299          vector registers before such a call and restore them on return. This is
     300          one of the intended uses of the WITH-VECTOR-BUFFER lap macro.</para>
    287301      </sect2>
    288302    </sect1>
     
    292306
    293307      <refentry id="v_warn-if-redefine-kernel">
    294         <indexterm zone="v_warn-if-redefine-kernel">
    295           <primary>*warn-if-redefine-kernel</primary>
    296         </indexterm>
    297 
    298         <refnamediv>
    299           <refname>*WARN-IF-REDEFINE-KERNEL*</refname>
    300           <refpurpose></refpurpose>
    301           <refclass>Variable</refclass>
    302         </refnamediv>
    303 
    304         <refsect1>
    305           <title>Description</title>
    306 
    307           <para>When true, attempts to redefine (via DEFUN or DEFMETHOD)
    308           functions and methods that are marked as being
    309           &#34;predefined&#34; signal continuable errors.</para>
    310 
    311           <para>Note that these are CERRORs, not warnings, and that
    312           no lisp functions or methods have been defined in the kernel
    313           in MCL or &CCL; since 1987 or so.</para>
    314         </refsect1>
     308            <indexterm zone="v_warn-if-redefine-kernel">
     309              <primary>*warn-if-redefine-kernel</primary>
     310            </indexterm>
     311
     312            <refnamediv>
     313              <refname>*WARN-IF-REDEFINE-KERNEL*</refname>
     314              <refpurpose></refpurpose>
     315              <refclass>Variable</refclass>
     316            </refnamediv>
     317
     318            <refsect1>
     319              <title>Description</title>
     320
     321              <para>When true, attempts to redefine (via DEFUN or DEFMETHOD)
     322                functions and methods that are marked as being
     323                &#34;predefined&#34; signal continuable errors.</para>
     324
     325              <para>Note that these are CERRORs, not warnings, and that
     326                no lisp functions or methods have been defined in the kernel
     327                in MCL or &CCL; since 1987 or so.</para>
     328            </refsect1>
    315329      </refentry>
    316330
    317331      <refentry id="f_set-development-environment">
    318         <indexterm zone="f_set-development-environment">
    319           <primary>set-development-environment</primary>
    320         </indexterm>
    321 
    322         <refnamediv>
    323           <refname>SET-DEVELOPMENT-ENVIRONMENT</refname>
    324           <refpurpose></refpurpose>
    325           <refclass>Function</refclass>
    326         </refnamediv>
    327 
    328         <refsynopsisdiv>
    329           <synopsis><function>set-development-environment</function>
    330           &optional;
    331           unmark-builtin-functions</synopsis>
    332         </refsynopsisdiv>
    333 
    334         <refsect1>
    335           <title>Description</title>
    336 
    337           <para>Arranges that the outermost special bindings of *PACKAGE*
    338           and *WARN-IF-REDEFINE-KERNEL* restore values of the &#34;CCL&#34;
    339           package and NIL to these variables, respectively. If the optional
    340           argument is true, marks all globally defined functions and methods
    341           as being &#34;not predefined&#34; (this is a fairly expensive
    342           operation.)</para>
    343         </refsect1>
     332            <indexterm zone="f_set-development-environment">
     333              <primary>set-development-environment</primary>
     334            </indexterm>
     335
     336            <refnamediv>
     337              <refname>SET-DEVELOPMENT-ENVIRONMENT</refname>
     338              <refpurpose></refpurpose>
     339              <refclass>Function</refclass>
     340            </refnamediv>
     341
     342            <refsynopsisdiv>
     343              <synopsis><function>set-development-environment</function>
     344                &optional;
     345                unmark-builtin-functions</synopsis>
     346            </refsynopsisdiv>
     347
     348            <refsect1>
     349              <title>Description</title>
     350
     351              <para>Arranges that the outermost special bindings of *PACKAGE*
     352                and *WARN-IF-REDEFINE-KERNEL* restore values of the &#34;CCL&#34;
     353                package and NIL to these variables, respectively. If the optional
     354                argument is true, marks all globally defined functions and methods
     355                as being &#34;not predefined&#34; (this is a fairly expensive
     356                operation.)</para>
     357            </refsect1>
    344358      </refentry>
    345359
    346360      <refentry id="f_set-user-environment">
    347         <indexterm zone="f_set-user-environment">
    348           <primary>set-user-environment</primary>
    349         </indexterm>
    350 
    351         <refnamediv>
    352           <refname>SET-USER-ENVIRONMENT</refname>
    353           <refpurpose></refpurpose>
    354           <refclass>Function</refclass>
    355         </refnamediv>
    356 
    357         <refsynopsisdiv>
    358           <synopsis><function>set-user-environment</function>
    359           &optional; mark-builtin-functions</synopsis>
    360         </refsynopsisdiv>
    361 
    362         <refsect1>
    363           <title>Description</title>
    364 
    365           <para>Arranges that the outermost special bindings of *PACKAGE*
    366           and *WARN-IF-REDEFINE-KERNEL* restore values of the
    367           &#34;CL-USER&#34; package and T to these variables, respectively.
    368           If the optional argument is true, marks all globally defined
    369           functions and methods as being &#34;predefined&#34; (this is a
    370           fairly expensive operation.)</para>
    371         </refsect1>
     361            <indexterm zone="f_set-user-environment">
     362              <primary>set-user-environment</primary>
     363            </indexterm>
     364
     365            <refnamediv>
     366              <refname>SET-USER-ENVIRONMENT</refname>
     367              <refpurpose></refpurpose>
     368              <refclass>Function</refclass>
     369            </refnamediv>
     370
     371            <refsynopsisdiv>
     372              <synopsis><function>set-user-environment</function>
     373                &optional; mark-builtin-functions</synopsis>
     374            </refsynopsisdiv>
     375
     376            <refsect1>
     377              <title>Description</title>
     378
     379              <para>Arranges that the outermost special bindings of *PACKAGE*
     380                and *WARN-IF-REDEFINE-KERNEL* restore values of the
     381                &#34;CL-USER&#34; package and T to these variables, respectively.
     382                If the optional argument is true, marks all globally defined
     383                functions and methods as being &#34;predefined&#34; (this is a
     384                fairly expensive operation.)</para>
     385            </refsect1>
    372386      </refentry>
    373387      <refentry id="v_altivec-available">
    374         <indexterm zone="v_altivec-available">
    375           <primary>*altivec-available*</primary>
    376         </indexterm>
    377 
    378         <refnamediv>
    379           <refname>*ALTIVEC-AVAILABLE*</refname>
    380           <refpurpose></refpurpose>
    381           <refclass>Variable</refclass>
    382         </refnamediv>
    383 
    384         <refsect1>
    385           <title>Description</title>
    386           <para>This variable is intitialized each time an &CCL; session
    387           starts based on information provided by the lisp kernel. Its value
    388           is true if AltiVec is present and false otherwise. This variable
    389           shouldn't be set by user code.</para>
    390         </refsect1>
     388            <indexterm zone="v_altivec-available">
     389              <primary>*altivec-available*</primary>
     390            </indexterm>
     391
     392            <refnamediv>
     393              <refname>*ALTIVEC-AVAILABLE*</refname>
     394              <refpurpose></refpurpose>
     395              <refclass>Variable</refclass>
     396            </refnamediv>
     397
     398            <refsect1>
     399              <title>Description</title>
     400              <para>This variable is initialized each time an &CCL; session
     401                starts based on information provided by the lisp kernel. Its value
     402                is true if AltiVec is present and false otherwise. This variable
     403                shouldn't be set by user code.</para>
     404            </refsect1>
    391405      </refentry>
    392406
    393407      <refentry id="f_altivec-available-p">
    394         <indexterm zone="f_altivec-available-p">
    395           <primary>altivec-available-p</primary>
    396         </indexterm>
    397 
    398         <refnamediv>
    399           <refname>ALTIVEC-AVAILABLE-P</refname>
    400           <refpurpose></refpurpose>
    401           <refclass>Function</refclass>
    402         </refnamediv>
    403        
    404         <refsynopsisdiv>
    405           <synopsis><function>altivec-available-p</function></synopsis>
    406         </refsynopsisdiv>
    407 
    408         <refsect1>
    409           <title>Description</title>
    410 
    411           <para>Returns non-NIL if AltiVec is available.</para>
    412         </refsect1>
     408            <indexterm zone="f_altivec-available-p">
     409              <primary>altivec-available-p</primary>
     410            </indexterm>
     411
     412            <refnamediv>
     413              <refname>ALTIVEC-AVAILABLE-P</refname>
     414              <refpurpose></refpurpose>
     415              <refclass>Function</refclass>
     416            </refnamediv>
     417           
     418            <refsynopsisdiv>
     419              <synopsis><function>altivec-available-p</function></synopsis>
     420            </refsynopsisdiv>
     421
     422            <refsect1>
     423              <title>Description</title>
     424
     425              <para>Returns non-NIL if AltiVec is available.</para>
     426            </refsect1>
    413427      </refentry>
    414428
    415429      <refentry id="v_altivec-lapmacros-maintain-vrsave-p">
    416         <indexterm zone="v_altivec-lapmacros-maintain-vrsave-p">
    417           <primary>*altivec-lapmacros-maintain-vrsave-p*</primary>
    418         </indexterm>
    419 
    420         <refnamediv>
    421           <refname>*ALTIVEC-LAPMACROS-MAINTAIN-VRSAVE-P*</refname>
    422           <refpurpose></refpurpose>
    423           <refclass>Variable</refclass>
    424         </refnamediv>
    425        
    426         <refsect1>
    427           <title>Description</title>
    428 
    429           <para>Intended to control the expansion of certain lap macros.
    430           Initialized to NIL on LinuxPPC; initialized to T on platforms
    431           (such as MacOS X/Darwin) that require that the VRSAVE SPR contain
    432           a bitmask of active vector registers at all times.</para>
    433         </refsect1>
     430            <indexterm zone="v_altivec-lapmacros-maintain-vrsave-p">
     431              <primary>*altivec-lapmacros-maintain-vrsave-p*</primary>
     432            </indexterm>
     433
     434            <refnamediv>
     435              <refname>*ALTIVEC-LAPMACROS-MAINTAIN-VRSAVE-P*</refname>
     436              <refpurpose></refpurpose>
     437              <refclass>Variable</refclass>
     438            </refnamediv>
     439           
     440            <refsect1>
     441              <title>Description</title>
     442
     443              <para>Intended to control the expansion of certain lap macros.
     444                Initialized to NIL on LinuxPPC; initialized to T on platforms
     445                (such as MacOS X/Darwin) that require that the VRSAVE SPR contain
     446                a bitmask of active vector registers at all times.</para>
     447            </refsect1>
    434448      </refentry>
    435449
    436450      <refentry id="lapm_with-altivec-registers">
    437         <indexterm zone="lapm_with-altivec-registers">
    438           <primary>with-altivec-registers</primary>
    439         </indexterm>
    440 
    441         <refnamediv>
    442           <refname>WITH-ALTIVEC-REGISTERS</refname>
    443           <refpurpose></refpurpose>
    444           <refclass>LAP Macro</refclass>
    445         </refnamediv>
    446 
    447         <refsynopsisdiv>
    448           <synopsis><function>with-altivec-registers</function>
    449           reglist &body; body</synopsis>
    450         </refsynopsisdiv>
    451 
    452         <refsect1>
    453           <title>Arguments and Values</title>
    454 
    455           <variablelist>
    456             <varlistentry>
    457               <term>reglist</term>
    458 
    459               <listitem>
    460                 <para>A list of vector register names (vr0 .. vr31).</para>
    461               </listitem>
    462             </varlistentry>
    463 
    464             <varlistentry>
    465               <term>body</term>
    466 
    467               <listitem>
    468                 <para>A sequence of PPC LAP instructions.</para>
    469               </listitem>
    470             </varlistentry>
    471           </variablelist>
    472         </refsect1>
    473 
    474         <refsect1>
    475           <title>Description</title>
    476 
    477           <para>Specifies the set of AltiVec registers used in body. If
    478           *altivec-lapmacros-maintain-vrsave-p* is true when the macro is
    479           expanded, generates code to save the VRSAVE SPR and updates VRSAVE
    480           to incude a bitmask generated from the specified register list.
    481           Generates code which saves any non-volatile vector registers which
    482           appear in the register list, executes body, and restores the saved
    483           non-volatile vector registers (and, if
    484           *altivec-lapmacros-maintain-vrsave-p* is true, restores VRSAVE as
    485           well. Uses the IMM0 register (r3) as a temporary.</para>
    486         </refsect1>
     451            <indexterm zone="lapm_with-altivec-registers">
     452              <primary>with-altivec-registers</primary>
     453            </indexterm>
     454
     455            <refnamediv>
     456              <refname>WITH-ALTIVEC-REGISTERS</refname>
     457              <refpurpose></refpurpose>
     458              <refclass>LAP Macro</refclass>
     459            </refnamediv>
     460
     461            <refsynopsisdiv>
     462              <synopsis><function>with-altivec-registers</function>
     463                reglist &body; body</synopsis>
     464            </refsynopsisdiv>
     465
     466            <refsect1>
     467              <title>Arguments and Values</title>
     468
     469              <variablelist>
     470                <varlistentry>
     471                  <term>reglist</term>
     472
     473                  <listitem>
     474                        <para>A list of vector register names (vr0 .. vr31).</para>
     475                  </listitem>
     476                </varlistentry>
     477
     478                <varlistentry>
     479                  <term>body</term>
     480
     481                  <listitem>
     482                        <para>A sequence of PPC LAP instructions.</para>
     483                  </listitem>
     484                </varlistentry>
     485              </variablelist>
     486            </refsect1>
     487
     488            <refsect1>
     489              <title>Description</title>
     490
     491              <para>Specifies the set of AltiVec registers used in body. If
     492                *altivec-lapmacros-maintain-vrsave-p* is true when the macro is
     493                expanded, generates code to save the VRSAVE SPR and updates VRSAVE
     494                to include a bitmask generated from the specified register list.
     495                Generates code which saves any non-volatile vector registers which
     496                appear in the register list, executes body, and restores the saved
     497                non-volatile vector registers (and, if
     498                *altivec-lapmacros-maintain-vrsave-p* is true, restores VRSAVE as
     499                well. Uses the IMM0 register (r3) as a temporary.</para>
     500            </refsect1>
    487501      </refentry>
    488502
    489503      <refentry id="lapm_with-vector-buffer">
    490         <indexterm zone="lapm_with-vector-buffer">
    491           <primary>with-vector-buffer</primary>
    492         </indexterm>
    493 
    494         <refnamediv>
    495           <refname>WITH-VECTOR-BUFFER</refname>
    496           <refpurpose></refpurpose>
    497           <refclass>LAP Macro</refclass>
    498         </refnamediv>
    499        
    500         <refsynopsisdiv>
    501           <synopsis>with-vector-buffer base n &body; body</synopsis>
    502         </refsynopsisdiv>
    503 
    504         <refsect1>
    505           <title>Arguments and Values</title>
    506 
    507           <variablelist>
    508             <varlistentry>
    509               <term>base</term>
    510 
    511               <listitem>
    512                 <para>Any available general-purpose register.</para>
    513               </listitem>
    514             </varlistentry>
    515 
    516             <varlistentry>
    517               <term>n</term>
    518 
    519               <listitem>
    520                 <para>An integer between 1 and 254, inclusive. (Should
    521                 typically be much, much closer to 1.) Specifies the size of
    522                 the buffer, in 16-byte units.</para>
    523               </listitem>
    524             </varlistentry>
    525 
    526             <varlistentry>
    527               <term>body</term>
    528 
    529               <listitem>
    530                 <para>A sequence of PPC LAP instructions.</para>
    531               </listitem>
    532             </varlistentry>
    533           </variablelist>
    534         </refsect1>
    535 
    536         <refsect1>
    537           <title>Description</title>
    538           <para>Generates code which allocates a 16-byte aligned buffer
    539           large enough to contain N vector registers; the GPR base points to
    540           the lowest address of this buffer. After processing body, the
    541           buffer will be deallocated. The body should preserve the value of
    542           base as long as it needs to reference the buffer. It's
    543           intended that base be used as a base register in stvx and lvx
    544           instructions within the body.</para>
    545         </refsect1>
     504            <indexterm zone="lapm_with-vector-buffer">
     505              <primary>with-vector-buffer</primary>
     506            </indexterm>
     507
     508            <refnamediv>
     509              <refname>WITH-VECTOR-BUFFER</refname>
     510              <refpurpose></refpurpose>
     511              <refclass>LAP Macro</refclass>
     512            </refnamediv>
     513           
     514            <refsynopsisdiv>
     515              <synopsis>with-vector-buffer base n &body; body</synopsis>
     516            </refsynopsisdiv>
     517
     518            <refsect1>
     519              <title>Arguments and Values</title>
     520
     521              <variablelist>
     522                <varlistentry>
     523                  <term>base</term>
     524
     525                  <listitem>
     526                        <para>Any available general-purpose register.</para>
     527                  </listitem>
     528                </varlistentry>
     529
     530                <varlistentry>
     531                  <term>n</term>
     532
     533                  <listitem>
     534                        <para>An integer between 1 and 254, inclusive. (Should
     535                          typically be much, much closer to 1.) Specifies the size of
     536                          the buffer, in 16-byte units.</para>
     537                  </listitem>
     538                </varlistentry>
     539
     540                <varlistentry>
     541                  <term>body</term>
     542
     543                  <listitem>
     544                        <para>A sequence of PPC LAP instructions.</para>
     545                  </listitem>
     546                </varlistentry>
     547              </variablelist>
     548            </refsect1>
     549
     550            <refsect1>
     551              <title>Description</title>
     552              <para>Generates code which allocates a 16-byte aligned buffer
     553                large enough to contain N vector registers; the GPR base points to
     554                the lowest address of this buffer. After processing body, the
     555                buffer will be deallocated. The body should preserve the value of
     556                base as long as it needs to reference the buffer. It's
     557                intended that base be used as a base register in stvx and lvx
     558                instructions within the body.</para>
     559            </refsect1>
    546560      </refentry>
    547561    </sect1>
  • trunk/source/doc/src/mop.xml

    r8820 r8981  
    343343      not generally practical for a thread to request exclusive access
    344344      to all of CLOS, and the effects of volitional modification of
    345       the CLOS hierarchy (via clas redefinition, CHANGE-CLASS, etc) in
     345      the CLOS hierarchy (via class redefinition, CHANGE-CLASS, etc) in
    346346      a multithreaded environment aren't always tractable.</para>
    347347      <para>Native threads exacerbate this problem (in that they
  • trunk/source/doc/src/objc-bridge.xml

    r8908 r8981  
    3030    Cocoa.</para>
    3131
     32  <!-- ============================================================ -->
    3233  <sect1 id="Objective-C-Changes-1.2">
    3334    <title>Changes in 1.2</title>
     
    3536    <para>Version 1.2 of &CCL; exports most of the useful symbols
    3637    described in this chapter; in previous releases, most of them were
    37     private in the <code>CCL</code> package.</para>
     38    private in the <literal>CCL</literal> package.</para>
    3839
    3940    <para>There are several new reader macros that make it much more
    40     conveinent than before to refer to several classes of symbols used
     41    convenient than before to refer to several classes of symbols used
    4142    with the Objective-C bridge. For a full description of these
    4243    reader-macros, see
     
    5152
    5253    <para>The Objective-C bridge defines the
    53       type <code>NS:CGFLOAT</code> as the Lisp type of the preferred
     54      type <literal>NS:CGFLOAT</literal> as the Lisp type of the preferred
    5455      floating-point type on the current platform, and defines the
    55       constant <code>NS:+CGFLOAT+</code>.  On DarwinPPC32, the foreign
    56       types <code>:cgfloat</code>, <code>:&lt;NSUI&gt;nteger</code>,
     56      constant <literal>NS:+CGFLOAT+</literal>.  On DarwinPPC32, the foreign
     57      types <literal>:cgfloat</literal>, <literal>:&lt;NSUI&gt;nteger</literal>,
    5758      and
    58       <code>:&lt;NSI&gt;nteger</code> are defined by the Objective-C
     59      <literal>:&lt;NSI&gt;nteger</literal> are defined by the Objective-C
    5960      bridge (as 32-bit float, 32-bit unsigned integer, and 32-bit
    6061      signed integer, respectively); these types are defined as 64-bit
     
    6263
    6364    <para>Every Objective-C class is now properly named, either with a
    64       name exported from the <code>NS</code> package (in the case of a
     65      name exported from the <literal>NS</literal> package (in the case of a
    6566      predefined class declared in the interface files) or with the
    66       name provided in the <code>DEFCLASS</code> form (with <code>:METACLASS</code>
    67       <code>NS:+NS-OBJECT</code>) which defines the class from Lisp.
     67      name provided in the <literal>DEFCLASS</literal> form (with <literal>:METACLASS</literal>
     68      <literal>NS:+NS-OBJECT</literal>) which defines the class from Lisp.
    6869      The class's Lisp name is now proclaimed to be a "static"
    69       variable (as if by <code>DEFSTATIC</code>, as described in the
     70      variable (as if by <literal>DEFSTATIC</literal>, as described in the
    7071      <link linkend="Static_Variables">"Static Variables"
    7172      section</link>) and given the class object as its value.  In
     
    8990  </sect1>
    9091
     92  <!-- ============================================================ -->
    9193  <sect1 id="Using-Objective-C-Classes">
    9294    <title>Using Objective-C Classes</title>
     
    140142  </sect1>
    141143
     144  <!-- ============================================================ -->
    142145  <sect1 id="Instantiating-Objective-C-Objects">
    143146    <title>Instantiating Objective-C Objects</title>
     
    160163    <para>Allocating an instance of an Objective-C class involves sending the
    161164      class an "alloc" message, and then using those initargs that
    162       <emphasis>don't</emphasis> correspond to slot initags as the
     165      <emphasis>don't</emphasis> correspond to slot initargs as the
    163166      "init" message to be sent to the newly-allocated instance.  So, the
    164167      example above could have been done more verbosely as:</para>
     
    199202      do this, the object is only allocated, and not initialized.  It
    200203      then sends the "init" message to do the initialization by hand.</para>
     204
     205    <para>There is an alternative API for instantiating Objective-C
     206      classes. You can
     207      call <literal>OBJC:MAKE-OBJC-INSTANCE</literal>, passing it the
     208      name of the Objective-C class as a string. In previous
     209      releases, <literal>OBJC:MAKE-OBJC-INSTANCE</literal> could be
     210      more efficient than <literal>OBJC:MAKE-INSTANCE</literal> in
     211      cases where the class did not define any Lisp slots; this is no
     212      longer the case. You can now
     213      regard <literal>OBJC:MAKE-OBJC-INSTANCE</literal> as completely
     214      equivalent to <literal>OBJC:MAKE-INSTANCE</literal>, except that
     215      you can pass a string for the classname, which may be convenient
     216      in the case that the classname is in some way unusual.</para>
    201217  </sect1>
    202218
     219  <!-- ============================================================ -->
    203220  <sect1 id="Calling-Objective-C-Methods">
    204221    <title>Calling Objective-C Methods</title>
     
    307324(send v1 :set-bounds (send v2 'bounds))
    308325      </programlisting>
    309       <para>There are also several psuedo-functions provided for convenience
     326      <para>There are also several pseudo-functions provided for convenience
    310327        by the Objective-C compiler, to make objects of specific types. The
    311328        following are currently supported by the bridge: NS-MAKE-POINT,
     
    428445  </sect1>
    429446
     447  <!-- ============================================================ -->
    430448  <sect1 id="Defining-Objective-C-Classes">
    431449    <title>Defining Objective-C Classes</title>
     
    514532  </sect1>
    515533
     534  <!-- ============================================================ -->
    516535  <sect1 id="Defining-Objective-C-Methods">
    517536    <anchor id="anchor_Defining-Objective-C-Methods"/>
     
    523542      belonging to Objective-C classes which have been defined in
    524543      Lisp.</para>
     544
    525545    <para>You can use either of two different macros to define methods
    526     on Objective-C classes. <literal>define-objc-method</literal>
    527     accepts a two-element list containing a message selector name and
    528     a class name, and a body. <literal>objc:defmethod</literal>
    529     superficially resembles the normal
    530     CLOS <literal>defmethod</literal>, but creates methods on
    531     Objective-C classes with the same restrictions as those created
    532     by <literal>define-objc-method</literal>.</para>
     546      on Objective-C classes. <literal>define-objc-method</literal>
     547      accepts a two-element list containing a message selector name
     548      and a class name, and a body. <literal>objc:defmethod</literal>
     549      superficially resembles the normal
     550      CLOS <literal>defmethod</literal>, but creates methods on
     551      Objective-C classes with the same restrictions as those created
     552      by <literal>define-objc-method</literal>.</para>
    533553
    534554    <sect2>
     
    760780       </programlisting>
    761781     
     782       <para>If the <literal>OBJC:DEFMETHOD</literal> creates a new
     783       method, then it displays a message to that effect. These
     784       messages may be helpful in catching errors in the names of
     785       method definitions. In addition, if
     786       a <literal>OBJC:DEFMETHOD</literal> form redefines a method in
     787       a way that changes its type signature, &CCL; signals a
     788       continuable error.</para>
    762789    </sect2>
    763790
     
    768795        how and when you can replace the definition of an Objective C
    769796        method.  Currently, if you break these rules, nothing will
    770         collapse, but the behaviour will be confusing; so
     797        collapse, but the behavior will be confusing; so
    771798        don't.</para>
    772799      <para>Objective C methods can be redefined at runtime, but
     
    783810  </sect1>
    784811
     812  <!-- ============================================================ -->
     813  <sect1 id="Loading-Objc-Frameworks">
     814    <title>Loading Frameworks</title>
     815
     816    <para>On Mac OS X, a framework is a structured directory
     817      containing one or more shared libraries along with metadata such
     818      as C and Objective-C header files. In some cases, frameworks may
     819      also contain additional items such as executables.</para>
     820
     821    <para>Loading a framework means opening the shared libraries and
     822      processing any declarations so that &CCL; can subsequently call
     823      its entry points and use its data structures. &CCL; provides the
     824      function <literal>OBJC:LOAD-FRAMEWORK</literal> for this
     825      purpose.</para>
     826
     827    <programlisting>
     828(OBJC:LOAD-FRAMEWORK framework-name interface-dir)
     829    </programlisting>
     830
     831    <para><literal>framework-name</literal> is a string that names the
     832    framework (for example, "Foundation", or "Cocoa"),
     833    and <literal>interface-dir</literal> is a keyword that names the
     834    set of interface databases associated with the named framework
     835    (for example, <literal>:foundation</literal>,
     836    or <literal>:cocoa</literal>).</para>
     837
     838    <para>Assuming that interface databases for the named frameworks
     839    exist on the standard search
     840    path, <literal>OBJC:LOAD-FRAMEWORK</literal> finds and initializes
     841    the framework bundle by searching OS X's standard framework search
     842    paths. Loading the named framework may create new Objective-C
     843    classes and methods, add foreign type descriptions and entry
     844    points, and adjust &CCL;'s dispatch functions.</para>
     845
     846    <para>If interface databases don't exist for a framework you want
     847    to use, you will need to create them. For more information about
     848    creating interface databases,
     849    see <link linkend="Creating-new-interface-directories">Creating
     850    new interface directories</link>.</para>
     851  </sect1>
     852
     853  <!-- ============================================================ -->
    785854  <sect1 id="How-Objective-C-Names-are-Mapped-to-Lisp-Symbols">
    786855    <title>How Objective-C Names are Mapped to Lisp Symbols</title>
    787856    <para>There is a standard set of naming conventions for Cocoa
    788857      classes, messages, etc.  As long as they are followed, the
    789       bridge is fairly good at automaticallly translating between Objective-C
     858      bridge is fairly good at automatically translating between Objective-C
    790859      and Lisp names.</para>
    791860    <para>For example, "NSOpenGLView" becomes ns:ns-opengl-view;
     
    821890    <para>Alternatively, you can define a special translation rule
    822891      for your exception.  This is useful for an exceptional name that
    823       you need to use througout your code.  Some examples:</para>
     892      you need to use throughout your code.  Some examples:</para>
    824893    <programlisting>
    825894(ccl::define-classname-translation "WiErDclass" wierd-class)
  • trunk/source/doc/src/platform-notes.xml

    r8908 r8981  
    142142      There is no attempt to make these calls correspond to Lisp
    143143      idioms, such as <literal>setf</literal>.  This means that their
    144       behaviour is simple and predictable.</para>
     144      behavior is simple and predictable.</para>
    145145    <para>For working with environment variables, there are
    146146      CCL::GETENV and CCL::SETENV.</para>
     
    250250        pool is sent a &ldquo;-release&rdquo; message, which causes it
    251251        to send &ldquo;-release&rdquo; messages to all of the objects
    252         that've been added to it.</para>
     252        that have been added to it.</para>
    253253      <para>If the current thread doesn't have a current autorelease
    254254        pool, the attempt to autorelease any object will result in a
     
    264264        default autorelease pool; there are REPL colon-commands for
    265265        manipulating the current listener's &ldquo;toplevel
    266         auturelease pool&rdquo;.</para>
     266        autorelease pool&rdquo;.</para>
    267267      <para>In the current scheme, every time that Cocoa calls lisp
    268268        code, a lisp error handler is established which maps any lisp
     
    289289          <title>Acknowledgement</title>
    290290      <para>The Cocoa bridge was originally developed, and
    291         generously contributed by, Randal Beer.</para>
     291        generously contributed by, Randall Beer.</para>
    292292    </sect2>
    293293  </sect1>
     
    321321      OS X 10.3.6.  This is inconvenient when you wish to distribute an
    322322      application you have built this way.</para>
    323     <para>Work in this direction is ongoing.  It is worth looking at the project
    324       "Bosco", by Mikel Evins, which is a template that can be used to build
    325       application bundles in a different way.  It is
    326       available here, as part
    327       of the "Clotho" project, and there is
    328       here.</para>
    329323    <para>When an image which had contained ObjC classes (which are also
    330324      CLOS classes) is re-launched, those classes are "revived": all
     
    10481042                      <listitem>
    10491043                        <para>either a string which represents the name of the
    1050                           selector or a list which describ+es the method's return
     1044                          selector or a list which describes the method's return
    10511045                          type, selector components, and argument types (see below.)
    10521046                          If the first form is used, then the first form in the body
     
    11231117                      <para>a list of alternating keywords and variable/type specifiers,
    11241118                        where the set of keywords can be mapped to a selector string for a
    1125                         parameteriezed method according to the standard name-mapping
     1119                        parameterized method according to the standard name-mapping
    11261120                        conventions for method selectors and each variable/type-specifier is
    11271121                        either a variable name (denoting a value of type :ID) or a list whose
     
    11551149             
    11561150              <para>Their default treatment by the #\; reader macro is the primary way
    1157                 in which #\Return and #\Linefeed differ syntactally; by extending the
     1151                in which #\Return and #\Linefeed differ syntactically; by extending the
    11581152                #\; reader macro to (conditionally) treat #\Return as a
    11591153                comment-terminator, that distinction is eliminated. This seems to make
     
    12021196             
    12031197              <para>When specified as :INFERRED and the file is open for input, the
    1204                 first bufferful of input data is examined; if a #\Return character
     1198                first buffer-full of input data is examined; if a #\Return character
    12051199                appears in the buffer before the first #\Linefeed, the file stream&#39;s
    12061200                external-format is set to :MACOS; otherwise, it is set to :UNIX.</para>
  • trunk/source/doc/src/sockets.xml

    r8820 r8981  
    3838            tcp-stream is a subclass of stream, and you can read and write to it
    3939            using all the usual stream functions. Created by (make-socket
    40             :addess-family :internet :type :stream :connect :active ...) or by
     40            :address-family :internet :type :stream :connect :active ...) or by
    4141            (accept-connection ...).</para>
    4242          </listitem>
  • trunk/source/doc/src/streams.xml

    r8822 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 ]>
     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          ]>
    1111
    1212<chapter id="Streams">
     
    1717    <sect2 id="Stream-Timeouts-And-Deadlines">
    1818      <title>Stream Timeouts and Deadlines</title>
    19     <indexterm>
    20       <primary>stream-input-timeout</primary>
    21     </indexterm>
    22     <indexterm>
    23       <primary>stream-output-timeout</primary>
    24     </indexterm>
    25     <indexterm>
    26       <primary>stream-deadline</primary>
    27     </indexterm>
    28     <indexterm>
    29       <primary>input-timeout</primary>
    30     </indexterm>
    31     <indexterm>
    32       <primary>output-timeout</primary>
    33     </indexterm>
    34     <indexterm>
    35       <primary>communication-deadline-expired</primary>
    36     </indexterm>
    37     <para>A stream that is associated with a file descriptor has
    38     attributes and accessors:
    39     <function>STREAM-INPUT-TIMEOUT</function>,
    40     <function>STREAM-OUTPUT-TIMEOUT</function>, and
    41     <function>STREAM-DEADLINE</function>.  All three accessors have
    42     corresponding <function>SETF</function> methods.
    43     <function>STREAM-INPUT-TIMEOUT</function> and
    44     <function>STREAM-OUTPUT-TIMEOUT</function> are specified in
    45     seconds and can be any positive real number less than one million.
    46     When a timeout is set and the corresponding I/O operation takes
    47     longer than the specified interval, an error is signalled.  The
    48     error is <literal>INPUT-TIMEOUT</literal> for input and
    49     <literal>OUTPUT-TIMEOUT</literal> for output.
    50     <literal>STREAM-DEADLINE</literal> specifies an absolute time in
    51     internal-time-units.  If an I/O operation on the stream does not
    52     complete before the deadline then a
    53     <literal>COMMUNICATION-DEADLINE-EXPIRED</literal> error is
    54     signalled.  A deadline takes precedence over any
    55     input/output timeouts that may be set.</para>
     19      <indexterm>
     20        <primary>stream-input-timeout</primary>
     21      </indexterm>
     22      <indexterm>
     23        <primary>stream-output-timeout</primary>
     24      </indexterm>
     25      <indexterm>
     26        <primary>stream-deadline</primary>
     27      </indexterm>
     28      <indexterm>
     29        <primary>input-timeout</primary>
     30      </indexterm>
     31      <indexterm>
     32        <primary>output-timeout</primary>
     33      </indexterm>
     34      <indexterm>
     35        <primary>communication-deadline-expired</primary>
     36      </indexterm>
     37      <para>A stream that is associated with a file descriptor has
     38        attributes and accessors:
     39        <function>STREAM-INPUT-TIMEOUT</function>,
     40        <function>STREAM-OUTPUT-TIMEOUT</function>, and
     41        <function>STREAM-DEADLINE</function>.  All three accessors have
     42        corresponding <function>SETF</function> methods.
     43        <function>STREAM-INPUT-TIMEOUT</function> and
     44        <function>STREAM-OUTPUT-TIMEOUT</function> are specified in
     45        seconds and can be any positive real number less than one million.
     46        When a timeout is set and the corresponding I/O operation takes
     47        longer than the specified interval, an error is signalled.  The
     48        error is <literal>INPUT-TIMEOUT</literal> for input and
     49        <literal>OUTPUT-TIMEOUT</literal> for output.
     50        <literal>STREAM-DEADLINE</literal> specifies an absolute time in
     51        internal-time-units.  If an I/O operation on the stream does not
     52        complete before the deadline then a
     53        <literal>COMMUNICATION-DEADLINE-EXPIRED</literal> error is
     54        signalled.  A deadline takes precedence over any
     55        input/output timeouts that may be set.</para>
    5656    </sect2>
    5757
     
    5959      <title>Open File Streams</title>
    6060      <para>Historically, &CCL; and MCL maintained a list of open
    61       file streams in the value of
    62       <literal>CCL:*OPEN-FILE-STREAMS*</literal>.  This functionality
    63       has been replaced with the thread-safe function:
    64       <literal>CCL:OPEN-FILE-STREAMS</literal> and its two helper
    65       functions: <literal>CCL:NOTE-OPEN-FILE-STREAM</literal> and
    66       <literal>CCL:REMOVE-OPEN-FILE-STREAM</literal>.  Maintaining
    67       this list helps to ensure that streams get closed in an orderly
    68       manner when the lisp exits.</para>
     61        file streams in the value of
     62        <literal>CCL:*OPEN-FILE-STREAMS*</literal>.  This functionality
     63        has been replaced with the thread-safe function:
     64        <literal>CCL:OPEN-FILE-STREAMS</literal> and its two helper
     65        functions: <literal>CCL:NOTE-OPEN-FILE-STREAM</literal> and
     66        <literal>CCL:REMOVE-OPEN-FILE-STREAM</literal>.  Maintaining
     67        this list helps to ensure that streams get closed in an orderly
     68        manner when the lisp exits.</para>
    6969
    7070      <refentry id="f_open-file-streams">
    71         <indexterm zone="f_open-file-streams">
    72           <primary>open-file-streams</primary>
    73         </indexterm>
    74 
    75         <refnamediv>
    76           <refname>OPEN-FILE-STREAMS</refname>
    77           <refpurpose>Returns the list of file streams that are currently open.</refpurpose>
    78           <refclass>Function</refclass>
    79         </refnamediv>
    80 
    81         <refsynopsisdiv>
    82           <synopsis>
    83             <function>open-file-streams</function>
    84             => stream-list
    85           </synopsis>
    86         </refsynopsisdiv>
    87 
    88         <refsect1>
    89           <title>Values</title>
    90          
    91           <variablelist>
    92             <varlistentry>
    93               <term>stream-list</term>
    94               <listitem>
    95                 <para>A list of open file streams.  This is a copy of
    96                 an internal list so it may be destructively
    97                 modified without ill effect.</para>
    98               </listitem>
    99             </varlistentry>
    100           </variablelist>
    101         </refsect1>
    102 
    103         <refsect1>
    104           <title>Description</title>
    105           <para>Returns a list of open file streams.</para>
    106         </refsect1>
    107 
    108         <refsect1>
    109           <title>See Also</title>       
    110           <simplelist type="inline">
    111             <member><xref linkend="f_note-open-file-stream"/></member>
    112             <member><xref linkend="f_remove-open-file-stream"/></member>
    113           </simplelist>
    114         </refsect1>
     71            <indexterm zone="f_open-file-streams">
     72              <primary>open-file-streams</primary>
     73            </indexterm>
     74
     75            <refnamediv>
     76              <refname>OPEN-FILE-STREAMS</refname>
     77              <refpurpose>Returns the list of file streams that are currently open.</refpurpose>
     78              <refclass>Function</refclass>
     79            </refnamediv>
     80
     81            <refsynopsisdiv>
     82              <synopsis>
     83                <function>open-file-streams</function>
     84                => stream-list
     85              </synopsis>
     86            </refsynopsisdiv>
     87
     88            <refsect1>
     89              <title>Values</title>
     90             
     91              <variablelist>
     92                <varlistentry>
     93                  <term>stream-list</term>
     94                  <listitem>
     95                        <para>A list of open file streams.  This is a copy of
     96                          an internal list so it may be destructively
     97                          modified without ill effect.</para>
     98                  </listitem>
     99                </varlistentry>
     100              </variablelist>
     101            </refsect1>
     102
     103            <refsect1>
     104              <title>Description</title>
     105              <para>Returns a list of open file streams.</para>
     106            </refsect1>
     107
     108            <refsect1>
     109              <title>See Also</title>   
     110              <simplelist type="inline">
     111                <member><xref linkend="f_note-open-file-stream"/></member>
     112                <member><xref linkend="f_remove-open-file-stream"/></member>
     113              </simplelist>
     114            </refsect1>
    115115      </refentry>
    116116
    117117      <refentry id="f_note-open-file-stream">
    118         <indexterm zone="f_note-open-file-stream">
    119           <primary>note-open-file-stream</primary>
    120         </indexterm>
    121 
    122         <refnamediv>
    123           <refname>NOTE-OPEN-FILE-STREAM</refname>
    124           <refpurpose>Adds a file stream to the internal list of open
    125           file streams that is returned by
    126           <function>note-open-file-stream</function>.</refpurpose>
    127           <refclass>Function</refclass>
    128         </refnamediv>
    129 
    130         <refsynopsisdiv>
    131           <synopsis>
    132             <function>note-open-file-stream</function>
    133             file-stream
    134           </synopsis>
    135         </refsynopsisdiv>
    136 
    137         <refsect1>
    138           <title>Arguments</title>
    139          
    140           <variablelist>
    141             <varlistentry>
    142               <term>file-stream</term>
    143               <listitem>
    144                 <para>A file stream.</para>
    145               </listitem>
    146             </varlistentry>
    147           </variablelist>
    148         </refsect1>
    149 
    150         <refsect1>
    151           <title>Description</title>
    152           <para>Adds a file stream to the internal list of open
    153           file streams that is returned by
    154           <function>open-file-streams</function>.  This function is
    155           thread-safe.  It will usually only be called from custom
    156           stream code when a file-stream is created.</para>
    157         </refsect1>
    158 
    159         <refsect1>
    160           <title>See Also</title>       
    161           <simplelist type="inline">
    162             <member><xref linkend="f_open-file-streams"/></member>
    163             <member><xref linkend="f_remove-open-file-stream"/></member>
    164           </simplelist>
    165         </refsect1>
     118            <indexterm zone="f_note-open-file-stream">
     119              <primary>note-open-file-stream</primary>
     120            </indexterm>
     121
     122            <refnamediv>
     123              <refname>NOTE-OPEN-FILE-STREAM</refname>
     124              <refpurpose>Adds a file stream to the internal list of open
     125                file streams that is returned by
     126                <function>note-open-file-stream</function>.</refpurpose>
     127              <refclass>Function</refclass>
     128            </refnamediv>
     129
     130            <refsynopsisdiv>
     131              <synopsis>
     132                <function>note-open-file-stream</function>
     133                file-stream
     134              </synopsis>
     135            </refsynopsisdiv>
     136
     137            <refsect1>
     138              <title>Arguments</title>
     139             
     140              <variablelist>
     141                <varlistentry>
     142                  <term>file-stream</term>
     143                  <listitem>
     144                        <para>A file stream.</para>
     145                  </listitem>
     146                </varlistentry>
     147              </variablelist>
     148            </refsect1>
     149
     150            <refsect1>
     151              <title>Description</title>
     152              <para>Adds a file stream to the internal list of open
     153                file streams that is returned by
     154                <function>open-file-streams</function>.  This function is
     155                thread-safe.  It will usually only be called from custom
     156                stream code when a file-stream is created.</para>
     157            </refsect1>
     158
     159            <refsect1>
     160              <title>See Also</title>   
     161              <simplelist type="inline">
     162                <member><xref linkend="f_open-file-streams"/></member>
     163                <member><xref linkend="f_remove-open-file-stream"/></member>
     164              </simplelist>
     165            </refsect1>
    166166
    167167      </refentry>
    168168
    169169      <refentry id="f_remove-open-file-stream">
    170         <indexterm zone="f_remove-open-file-stream">
    171           <primary>remove-open-file-stream</primary>
    172         </indexterm>
    173 
    174         <refnamediv>
    175           <refname>REMOVE-OPEN-FILE-STREAM</refname>
    176           <refpurpose>Removes file stream from the internal list of open
    177           file streams that is returned by
    178           <function>open-file-streams</function>.</refpurpose>
    179           <refclass>Function</refclass>
    180         </refnamediv>
    181 
    182         <refsynopsisdiv>
    183           <synopsis>
    184             <function>remove-open-file-stream</function>
    185             file-stream
    186           </synopsis>
    187         </refsynopsisdiv>
    188 
    189         <refsect1>
    190           <title>Arguments</title>
    191          
    192           <variablelist>
    193             <varlistentry>
    194               <term>file-stream</term>
    195               <listitem>
    196                 <para>A file stream.</para>
    197               </listitem>
    198             </varlistentry>
    199           </variablelist>
    200         </refsect1>
    201 
    202         <refsect1>
    203           <title>Description</title>
    204           <para>Remove file stream from the internal list of open file
    205           streams that is returned by
    206           <function>open-file-streams</function>.  This function is
    207           thread-safe.  It will usually only be called from custom
    208           stream code when a file-stream is closed.</para>
    209         </refsect1>
    210 
    211         <refsect1>
    212           <title>See Also</title>       
    213           <simplelist type="inline">
    214             <member><xref linkend="f_open-file-streams"/></member>
    215             <member><xref linkend="f_note-open-file-stream"/></member>
    216           </simplelist>
    217         </refsect1>
     170            <indexterm zone="f_remove-open-file-stream">
     171              <primary>remove-open-file-stream</primary>
     172            </indexterm>
     173
     174            <refnamediv>
     175              <refname>REMOVE-OPEN-FILE-STREAM</refname>
     176              <refpurpose>Removes file stream from the internal list of open
     177                file streams that is returned by
     178                <function>open-file-streams</function>.</refpurpose>
     179              <refclass>Function</refclass>
     180            </refnamediv>
     181
     182            <refsynopsisdiv>
     183              <synopsis>
     184                <function>remove-open-file-stream</function>
     185                file-stream
     186              </synopsis>
     187            </refsynopsisdiv>
     188
     189            <refsect1>
     190              <title>Arguments</title>
     191             
     192              <variablelist>
     193                <varlistentry>
     194                  <term>file-stream</term>
     195                  <listitem>
     196                        <para>A file stream.</para>
     197                  </listitem>
     198                </varlistentry>
     199              </variablelist>
     200            </refsect1>
     201
     202            <refsect1>
     203              <title>Description</title>
     204              <para>Remove file stream from the internal list of open file
     205                streams that is returned by
     206                <function>open-file-streams</function>.  This function is
     207                thread-safe.  It will usually only be called from custom
     208                stream code when a file-stream is closed.</para>
     209            </refsect1>
     210
     211            <refsect1>
     212              <title>See Also</title>   
     213              <simplelist type="inline">
     214                <member><xref linkend="f_open-file-streams"/></member>
     215                <member><xref linkend="f_note-open-file-stream"/></member>
     216              </simplelist>
     217            </refsect1>
    218218
    219219      </refentry>
     
    228228      <title>Overview</title>
    229229      <para>This sect1 is still being written and revised, because
    230       it is woefully incomplete.  The dictionary section currently
    231       only lists a couple functions.  Caveat lector.</para>
     230        it is woefully incomplete.  The dictionary section currently
     231        only lists a couple functions.  Caveat lector.</para>
    232232      <para>Gray streams are an extension to Common Lisp.  They were
    233       proposed for standardization by David Gray (the astute reader
    234       now understands their name) quite some years ago, but not
    235       accepted, because they had not been tried sufficiently to find
    236       conceptual problems with them.</para>
     233        proposed for standardization by David Gray (the astute reader
     234        now understands their name) quite some years ago, but not
     235        accepted, because they had not been tried sufficiently to find
     236        conceptual problems with them.</para>
    237237      <para>They have since been implemented by quite a few modern
    238       Lisp implementations.  However, they do indeed have some
    239       inadequacies, and each implementation has addressed these in
    240       different ways.  The situation today is that it's difficult to
    241       even find out how to get started using Gray streams.  This is
    242       why standards are important.</para>
     238        Lisp implementations.  However, they do indeed have some
     239        inadequacies, and each implementation has addressed these in
     240        different ways.  The situation today is that it's difficult to
     241        even find out how to get started using Gray streams.  This is
     242        why standards are important.</para>
    243243      <para>Here's a list of some classes which you might wish for
    244       your new stream class to inherit from:</para>
     244        your new stream class to inherit from:</para>
    245245     
    246246      <simplelist>
    247         <member>fundamental-stream</member>
    248         <member>fundamental-input-stream</member>
    249         <member>fundamental-output-stream</member>
    250         <member>fundamental-character-stream</member>
    251         <member>fundamental-binary-stream</member>
    252         <member>fundamental-character-input-stream</member>
    253         <member>fundamental-character-output-stream</member>
    254         <member>fundamental-binary-input-stream</member>
    255         <member>fundamental-binary-output-stream</member>
    256         <member>ccl::buffered-stream-mixin</member>
    257         <member>ccl::buffered-input-stream-mixin</member>
    258         <member>ccl::buffered-output-stream-mixin</member>
    259         <member>ccl::buffered-io-stream-mixin</member>
    260         <member>ccl::buffered-character-input-stream-mixin</member>
    261         <member>ccl::buffered-character-output-stream-mixin</member>
    262         <member>ccl::buffered-character-io-stream-mixin</member>
    263         <member>ccl::buffered-binary-input-stream-mixin</member>
    264         <member>ccl::buffered-binary-output-stream-mixin</member>
    265         <member>ccl::buffered-binary-io-stream-mixin</member>
    266         <member>file-stream</member>
    267         <member>file-input-stream</member>
    268         <member>file-output-stream</member>
    269         <member>file-io-stream</member>
    270         <member>file-character-input-stream</member>
    271         <member>file-character-output-stream</member>
    272         <member>file-charcter-io-stream</member>
    273         <member>file-binary-input-stream</member>
    274         <member>file-binary-output-stream</member>
    275         <member>file-binary-io-stream</member>
    276         <member>ccl::fd-stream</member>
    277         <member>ccl::fd-input-stream</member>
    278         <member>ccl::fd-output-stream</member>
    279         <member>ccl::fd-io-stream</member>
    280         <member>ccl::fd-character-input-stream</member>
    281         <member>ccl::fd-character-output-stream</member>
    282         <member>ccl::fd-character-io-stream</member>
    283         <member>ccl::fd-binary-input-stream</member>
    284         <member>ccl::fd-binary-output-stream</member>
    285         <member>ccl::fd-binary-io-stream</member>
     247            <member>fundamental-stream</member>
     248            <member>fundamental-input-stream</member>
     249            <member>fundamental-output-stream</member>
     250            <member>fundamental-character-stream</member>
     251            <member>fundamental-binary-stream</member>
     252            <member>fundamental-character-input-stream</member>
     253            <member>fundamental-character-output-stream</member>
     254            <member>fundamental-binary-input-stream</member>
     255            <member>fundamental-binary-output-stream</member>
     256            <member>ccl::buffered-stream-mixin</member>
     257            <member>ccl::buffered-input-stream-mixin</member>
     258            <member>ccl::buffered-output-stream-mixin</member>
     259            <member>ccl::buffered-io-stream-mixin</member>
     260            <member>ccl::buffered-character-input-stream-mixin</member>
     261            <member>ccl::buffered-character-output-stream-mixin</member>
     262            <member>ccl::buffered-character-io-stream-mixin</member>
     263            <member>ccl::buffered-binary-input-stream-mixin</member>
     264            <member>ccl::buffered-binary-output-stream-mixin</member>
     265            <member>ccl::buffered-binary-io-stream-mixin</member>
     266            <member>file-stream</member>
     267            <member>file-input-stream</member>
     268            <member>file-output-stream</member>
     269            <member>file-io-stream</member>
     270            <member>file-character-input-stream</member>
     271            <member>file-character-output-stream</member>
     272            <member>file-character-io-stream</member>
     273            <member>file-binary-input-stream</member>
     274            <member>file-binary-output-stream</member>
     275            <member>file-binary-io-stream</member>
     276            <member>ccl::fd-stream</member>
     277            <member>ccl::fd-input-stream</member>
     278            <member>ccl::fd-output-stream</member>
     279            <member>ccl::fd-io-stream</member>
     280            <member>ccl::fd-character-input-stream</member>
     281            <member>ccl::fd-character-output-stream</member>
     282            <member>ccl::fd-character-io-stream</member>
     283            <member>ccl::fd-binary-input-stream</member>
     284            <member>ccl::fd-binary-output-stream</member>
     285            <member>ccl::fd-binary-io-stream</member>
    286286      </simplelist>
    287287
    288288      <para>All of these are defined in ccl/level-1/l1-streams.lisp,
    289       except for the ccl:file-* ones, which are in
    290       ccl/level-1/l1-sysio.lisp.</para>
     289        except for the ccl:file-* ones, which are in
     290        ccl/level-1/l1-sysio.lisp.</para>
    291291      <para>According to the original Gray streams proposal, you
    292       should inherit from the most specific of the fundamental-*
    293       classes which applies.  Using &CCL;, though, if you want
    294       buffering for better performance, which, unless you know of some
    295       reason you wouldn't, you do, you should instead inherit from the
    296       appropriate ccl::buffered-* class The buffering you get this way
    297       is exactly the same as the buffering which is used on ordinary,
    298       non-Gray streams, and force-output will work properly on
    299       it.</para>
     292        should inherit from the most specific of the fundamental-*
     293        classes which applies.  Using &CCL;, though, if you want
     294        buffering for better performance, which, unless you know of some
     295        reason you wouldn't, you do, you should instead inherit from the
     296        appropriate ccl::buffered-* class The buffering you get this way
     297        is exactly the same as the buffering which is used on ordinary,
     298        non-Gray streams, and force-output will work properly on
     299        it.</para>
    300300      <para>Notice that -mixin suffix in the names of all the
    301       ccl::buffered-* classes?  The suffix means that this class is
    302       not "complete" by itself; you still need to inherit from a
    303       fundamental-* stream, even if you also inherit from a *-mixin
    304       stream.  You might consider making your own class like this.
    305       ....  Except that they do inherit from the fundamental-*
    306       streams, that's weird.</para>
     301        ccl::buffered-* classes?  The suffix means that this class is
     302        not "complete" by itself; you still need to inherit from a
     303        fundamental-* stream, even if you also inherit from a *-mixin
     304        stream.  You might consider making your own class like this.
     305        ....  Except that they do inherit from the fundamental-*
     306        streams, that's weird.</para>
    307307      <para>If you want to be able to create an instance of your class
    308       with the :class argument to (open) and (with-open-file), you
    309       should make it inherit from one of the file-* classes.  If you
    310       do this, it's not necessary to inherit from any of the other
    311       classes (though it won't hurt anything), since the file-*
    312       classes already do.</para>
     308        with the :class argument to (open) and (with-open-file), you
     309        should make it inherit from one of the file-* classes.  If you
     310        do this, it's not necessary to inherit from any of the other
     311        classes (though it won't hurt anything), since the file-*
     312        classes already do.</para>
    313313      <para>When you inherit from the file-* classes, you can use
    314       (call-next-method) in any of your methods to get the standard
    315       behaviour.  This is especially useful if you want to create a
    316       class which performs some simple filtering operation, such as
    317       changing everything to uppercase or to a different character
    318       encoding.  If you do this, you will definitely need to
    319       specialize ccl::select-stream-class.  Your method on
    320       ccl::stream-select-class should accept an instance of the class,
    321       but pay no attention to its contents, and return a symbol naming
    322       the class to actually be instantiated.</para>
     314        (call-next-method) in any of your methods to get the standard
     315        behavior.  This is especially useful if you want to create a
     316        class which performs some simple filtering operation, such as
     317        changing everything to uppercase or to a different character
     318        encoding.  If you do this, you will definitely need to
     319        specialize ccl::select-stream-class.  Your method on
     320        ccl::stream-select-class should accept an instance of the class,
     321        but pay no attention to its contents, and return a symbol naming
     322        the class to actually be instantiated.</para>
    323323      <para>If you need to make your functionality generic across all
    324       the different types of stream, probably the best way to
    325       implement it is to make it a mixin, define classes with all the
    326       variants of input, output, io, character, and binary, which
    327       inherit both from your mixin and from the appropriate other
    328       class, then define a method on ccl::select-stream-class which
    329       chooses from among those classes.</para>
     324        the different types of stream, probably the best way to
     325        implement it is to make it a mixin, define classes with all the
     326        variants of input, output, io, character, and binary, which
     327        inherit both from your mixin and from the appropriate other
     328        class, then define a method on ccl::select-stream-class which
     329        chooses from among those classes.</para>
    330330      <para>Note that some of these classes are internal to the CLL
    331       package.  If you try to inherit from those ones without the
    332       ccl:: prefix, you'll get an error which may confuse you, calling
    333       them "forward-referenced classes".  That just means you used the
    334       wrong symbol, so add the prefix.</para>
     331        package.  If you try to inherit from those ones without the
     332        ccl:: prefix, you'll get an error which may confuse you, calling
     333        them "forward-referenced classes".  That just means you used the
     334        wrong symbol, so add the prefix.</para>
    335335      <para>Here's a list of some generic functions which you might
    336       wish to specialize for your new stream class, and which ought to
    337       be documented at some point.</para>
     336        wish to specialize for your new stream class, and which ought to
     337        be documented at some point.</para>
    338338      <simplelist>
    339         <member>stream-direction stream =></member>
    340         <member>stream-device stream direction =></member>
    341         <member>stream-length stream &optional; new =></member>
    342         <member>stream-position stream &optional; new =></member>
    343         <member>streamp stream => boolean</member>
    344         <member>stream-write-char output-stream char =></member>
    345         <member>stream-write-entire-string output-stream string =></member>
    346         <member>stream-read-char input-stream =></member>
    347         <member>stream-unread-char input-stream char =></member>
    348         <member>stream-force-output output-stream => nil</member>
    349         <member>stream-maybe-force-output output-stream => nil</member>
    350         <member>stream-finish-output output-stream => nil</member>
    351         <member>stream-clear-output output-stream => nil</member>
    352         <member>close stream &key; abort => boolean</member>
    353         <member>stream-fresh-line stream => t</member>
    354         <member>stream-line-length stream => length</member>
    355         <member>interactive-stream-p stream => boolean</member>
    356         <member>stream-clear-input input-stream => nil</member>
    357         <member>stream-listen input-stream => boolean</member>
    358         <member>stream-filename stream => string</member>
    359         <member>ccl::select-stream-class instance in-p out-p char-p =>
    360         class</member>
     339            <member>stream-direction stream =></member>
     340            <member>stream-device stream direction =></member>
     341            <member>stream-length stream &optional; new =></member>
     342            <member>stream-position stream &optional; new =></member>
     343            <member>streamp stream => boolean</member>
     344            <member>stream-write-char output-stream char =></member>
     345            <member>stream-write-entire-string output-stream string =></member>
     346            <member>stream-read-char input-stream =></member>
     347            <member>stream-unread-char input-stream char =></member>
     348            <member>stream-force-output output-stream => nil</member>
     349            <member>stream-maybe-force-output output-stream => nil</member>
     350            <member>stream-finish-output output-stream => nil</member>
     351            <member>stream-clear-output output-stream => nil</member>
     352            <member>close stream &key; abort => boolean</member>
     353            <member>stream-fresh-line stream => t</member>
     354            <member>stream-line-length stream => length</member>
     355            <member>interactive-stream-p stream => boolean</member>
     356            <member>stream-clear-input input-stream => nil</member>
     357            <member>stream-listen input-stream => boolean</member>
     358            <member>stream-filename stream => string</member>
     359            <member>ccl::select-stream-class instance in-p out-p char-p =>
     360              class</member>
    361361      </simplelist>
    362362      <para>The following functions are standard parts of Common Lisp, but
    363       behave in special ways with regard to Gray streams.</para>
     363        behave in special ways with regard to Gray streams.</para>
    364364      <simplelist>
    365         <member>open-stream-p stream => generalized-boolean</member>
    366         <member>input-stream-p stream => generalized-boolean</member>
    367         <member>output-stream-p stream => generalized-boolean</member>
    368         <member>stream-element-type stream =></member>
    369         <member>stream-error-stream =></member>
    370         <member>open</member>
    371         <member>close</member>
    372         <member>with-open-file</member>
     365            <member>open-stream-p stream => generalized-boolean</member>
     366            <member>input-stream-p stream => generalized-boolean</member>
     367            <member>output-stream-p stream => generalized-boolean</member>
     368            <member>stream-element-type stream =></member>
     369            <member>stream-error-stream =></member>
     370            <member>open</member>
     371            <member>close</member>
     372            <member>with-open-file</member>
    373373      </simplelist>
    374374
    375375      <para>Specifically, (open) and (with-open-file) accept a new
    376       keyword argument, :class, which may be a symbol naming a class;
    377       the class itself; or an instance of it.  The class so given must
    378       be a subtype of 'stream, and an instance of it with no
    379       particular contents will be passed to ccl::select-stream-class
    380       to determine what class to actually instantiate.</para>
     376        keyword argument, :class, which may be a symbol naming a class;
     377        the class itself; or an instance of it.  The class so given must
     378        be a subtype of 'stream, and an instance of it with no
     379        particular contents will be passed to ccl::select-stream-class
     380        to determine what class to actually instantiate.</para>
    381381      <para>The following are standard, and do not behave specially
    382       with regard to Gray streams, but probably should.</para>
     382        with regard to Gray streams, but probably should.</para>
    383383      <simplelist>
    384         <member>stream-external-format</member>
     384            <member>stream-external-format</member>
    385385      </simplelist>
    386386    </sect2>
     
    390390
    391391      <sect3 id="extending-read-write-overview">
    392         <title>Overview</title>
    393         <para>The "Gray Streams" API is based on an informal proposal that was
    394         made before ANSI CL adopted the READ-SEQUENCE and WRITE-SEQUENCE
    395         functions; as such, there is no "standard" way for the author of a Gray
    396         stream class to improve the performance of these functions by exploiting
    397         knowledge of the stream's internals (e.g., the buffering mechanism it
    398         uses.)</para>
    399         <para>In the absence of any such knowledge, READ-SEQUENCE and
    400         WRITE-SEQUENCE are effectively just convenient shorthand for a
    401         loop which calls READ-CHAR/READ-BYTE/WRITE-CHAR/WRITE-BYTE as
    402         appropriate. The mechanism described below allows subclasses
    403         of FUNDAMENTAL-STREAM to define more specialized (and
    404         presumably more efficient) behavior.</para>
     392            <title>Overview</title>
     393            <para>The "Gray Streams" API is based on an informal proposal that was
     394              made before ANSI CL adopted the READ-SEQUENCE and WRITE-SEQUENCE
     395              functions; as such, there is no "standard" way for the author of a Gray
     396              stream class to improve the performance of these functions by exploiting
     397              knowledge of the stream's internals (e.g., the buffering mechanism it
     398              uses.)</para>
     399            <para>In the absence of any such knowledge, READ-SEQUENCE and
     400              WRITE-SEQUENCE are effectively just convenient shorthand for a
     401              loop which calls READ-CHAR/READ-BYTE/WRITE-CHAR/WRITE-BYTE as
     402              appropriate. The mechanism described below allows subclasses
     403              of FUNDAMENTAL-STREAM to define more specialized (and
     404              presumably more efficient) behavior.</para>
    405405      </sect3>
    406406
    407407      <sect3 id="Notes">
    408         <title>Notes</title>
    409         <para>READ-SEQUENCE and WRITE-SEQUENCE do a certain amount of
    410         sanity-checking and normalization of their arguments before
    411         dispatching to one of the methods above. If an individual
    412         method can't do anything particularly clever, CALL-NEXT-METHOD
    413         can be used to handle the general case.</para>
     408            <title>Notes</title>
     409            <para>READ-SEQUENCE and WRITE-SEQUENCE do a certain amount of
     410              sanity-checking and normalization of their arguments before
     411              dispatching to one of the methods above. If an individual
     412              method can't do anything particularly clever, CALL-NEXT-METHOD
     413              can be used to handle the general case.</para>
    414414      </sect3>
    415415
    416416      <sect3 id="Example">
    417         <title>Example</title>
    418         <programlisting>
    419           (defclass my-string-input-stream (fundamental-character-input-stream)
    420           ((string :initarg :string :accessor my-string-input-stream-string)
    421           (index :initform 0 :accessor my-string-input-stream-index)
    422           (length)))
    423 
    424           (defmethod stream-read-vector ((stream my-string-input-stream) vector start end)
    425           (if (not (typep vector 'simple-base-string))
    426           (call-next-method)
    427           (with-slots (string index length)
    428           (do* ((outpos start (1+ outpos)))
    429           ((or (= outpos end)
    430           (= index length))
    431           outpos))
    432           (setf (schar vector outpos)
    433           (schar string index))
    434           (incf index)))))
    435         </programlisting>
     417            <title>Example</title>
     418            <programlisting>
     419(defclass my-string-input-stream (fundamental-character-input-stream)
     420  ((string :initarg :string :accessor my-string-input-stream-string)
     421   (index :initform 0 :accessor my-string-input-stream-index)
     422   (length)))
     423
     424(defmethod stream-read-vector ((stream my-string-input-stream) vector start end)
     425  (if (not (typep vector 'simple-base-string))
     426      (call-next-method)
     427      (with-slots (string index length)
     428              (do* ((outpos start (1+ outpos)))
     429               ((or (= outpos end)
     430                    (= index length))
     431                outpos))
     432        (setf (schar vector outpos)
     433              (schar string index))
     434        (incf index)))))
     435            </programlisting>
    436436      </sect3>
    437437    </sect2>
     
    440440      <title>Multibyte I/O</title>
    441441      <para>All heap-allocated objects in &CCL; that cannot contain
    442       pointers to lisp objects are represented as
    443       <emphasis>ivectors</emphasis>. &CCL; provides low-level
    444       functions, and , to efficiently transfer data between buffered
    445       streams and ivectors. There's some overlap in functionality
    446       between the functions described here and the ANSI CL
    447       READ-SEQUENCE and WRITE-SEQUENCE functions.</para>
     442        pointers to lisp objects are represented as
     443        <emphasis>ivectors</emphasis>. &CCL; provides low-level
     444        functions, and , to efficiently transfer data between buffered
     445        streams and ivectors. There's some overlap in functionality
     446        between the functions described here and the ANSI CL
     447        READ-SEQUENCE and WRITE-SEQUENCE functions.</para>
    448448      <para>As used here, the term "octet" means roughly the same
    449       thing as the term "8-bit byte". The functions described below
    450       transfer a specified sequence of octets between a buffered
    451       stream and an ivector, and don't really concern themselves with
    452       higher-level issues (like whether that octet sequence is within
    453       bounds or how it relates to the logical contents of the
    454       ivector.) For these reasons, these functions are generally less
    455       safe and more flexible than their ANSI counterparts.</para>
     449        thing as the term "8-bit byte". The functions described below
     450        transfer a specified sequence of octets between a buffered
     451        stream and an ivector, and don't really concern themselves with
     452        higher-level issues (like whether that octet sequence is within
     453        bounds or how it relates to the logical contents of the
     454        ivector.) For these reasons, these functions are generally less
     455        safe and more flexible than their ANSI counterparts.</para>
    456456    </sect2>
    457457
     
    459459      <title>Gray Streams Dictionary</title>
    460460      <refentry id="f_stream-read-list">
    461         <indexterm zone="f_stream-read-list">
    462           <primary>stream-read-list</primary>
    463         </indexterm>
    464 
    465         <refnamediv>
    466           <refname>CCL:STREAM-READ-LIST</refname>
    467           <refpurpose></refpurpose>
    468           <refclass>Generic Function</refclass>
    469         </refnamediv>
    470 
    471         <refsynopsisdiv>
    472           <synopsis><function>stream-read-list</function>
    473           stream list count</synopsis>
    474         </refsynopsisdiv>
    475 
    476         <refsect1>
    477           <title>Arguments and Values</title>
    478 
    479           <variablelist>
    480             <varlistentry>
    481               <term>stream</term>
    482 
    483               <listitem>
    484                 <para>a stream, presumably a fundamental-input-stream.</para>
    485               </listitem>
    486             </varlistentry>
    487 
    488             <varlistentry>
    489               <term>list</term>
    490 
    491               <listitem>
    492                 <para>a list. When a STREAM-READ-LIST method is called by
    493                 READ-SEQUENCE, this argument is guaranteed to be a proper
    494                 list.</para>
    495               </listitem>
    496             </varlistentry>
    497 
    498             <varlistentry>
    499               <term>count</term>
    500 
    501               <listitem>
    502                 <para>a non-negative integer. When a STREAM-READ-LIST method
    503                 is called by READ-SEQUENCE, this argument is guaranteed not
    504                 to be greater than the length of the list.</para>
    505               </listitem>
    506             </varlistentry>
    507           </variablelist>
    508         </refsect1>
    509 
    510         <refsect1>
    511           <title>Description</title>
    512 
    513           <para>Should try to read up to count elements from stream into the
    514           list list, returning the number of elements actually read (which
    515           may be less than count in case of a premature end-of-file.)</para>
    516         </refsect1>
     461            <indexterm zone="f_stream-read-list">
     462              <primary>stream-read-list</primary>
     463            </indexterm>
     464
     465            <refnamediv>
     466              <refname>CCL:STREAM-READ-LIST</refname>
     467              <refpurpose></refpurpose>
     468              <refclass>Generic Function</refclass>
     469            </refnamediv>
     470
     471            <refsynopsisdiv>
     472              <synopsis><function>stream-read-list</function>
     473                stream list count</synopsis>
     474            </refsynopsisdiv>
     475
     476            <refsect1>
     477              <title>Arguments and Values</title>
     478
     479              <variablelist>
     480                <varlistentry>
     481                  <term>stream</term>
     482
     483                  <listitem>
     484                        <para>a stream, presumably a fundamental-input-stream.</para>
     485                  </listitem>
     486                </varlistentry>
     487
     488                <varlistentry>
     489                  <term>list</term>
     490
     491                  <listitem>
     492                        <para>a list. When a STREAM-READ-LIST method is called by
     493                          READ-SEQUENCE, this argument is guaranteed to be a proper
     494                          list.</para>
     495                  </listitem>
     496                </varlistentry>
     497
     498                <varlistentry>
     499                  <term>count</term>
     500
     501                  <listitem>
     502                        <para>a non-negative integer. When a STREAM-READ-LIST method
     503                          is called by READ-SEQUENCE, this argument is guaranteed not
     504                          to be greater than the length of the list.</para>
     505                  </listitem>
     506                </varlistentry>
     507              </variablelist>
     508            </refsect1>
     509
     510            <refsect1>
     511              <title>Description</title>
     512
     513              <para>Should try to read up to count elements from stream into the
     514                list list, returning the number of elements actually read (which
     515                may be less than count in case of a premature end-of-file.)</para>
     516            </refsect1>
    517517      </refentry>
    518518
    519519      <refentry id="f_stream-write-list">
    520         <indexterm zone="f_stream-write-list">
    521           <primary>stream-write-list</primary>
    522         </indexterm>
    523 
    524         <refnamediv>
    525           <refname>CCL:STREAM-WRITE-LIST</refname>
    526           <refpurpose></refpurpose>
    527           <refclass>Generic Function</refclass>
    528         </refnamediv>
    529 
    530         <refsynopsisdiv>
    531           <synopsis><function>stream-write-list</function>
    532           stream list count</synopsis>
    533         </refsynopsisdiv>
    534 
    535         <refsect1>
    536           <title>Arguments and Values</title>
    537 
    538           <variablelist>
    539             <varlistentry>
    540               <term>stream</term>
    541 
    542               <listitem>
    543                 <para>a stream, presumably a fundamental-ouput-stream.</para>
    544               </listitem>
    545             </varlistentry>
    546 
    547             <varlistentry>
    548               <term>list</term>
    549 
    550               <listitem>
    551                 <para>a list. When a STREAM-WRITE-LIST method is called by
    552                 WRITE-SEQUENCE, this argument is guaranteed to be a proper
    553                 list.</para>
    554               </listitem>
    555             </varlistentry>
    556 
    557             <varlistentry>
    558               <term>count</term>
    559 
    560               <listitem>
    561                 <para>a non-negative integer. When a STREAM-WRITE-LIST
    562                 method is called by WRITE-SEQUENCE, this argument is
    563                 guaranteed not to be greater than the length of the list.</para>
    564               </listitem>
    565             </varlistentry>
    566           </variablelist>
    567         </refsect1>
    568 
    569         <refsect1>
    570           <title>Description</title>
    571 
    572           <para>should try to write the first count elements of list to
    573           stream. The return value of this method is ignored.</para>
    574         </refsect1>
     520            <indexterm zone="f_stream-write-list">
     521              <primary>stream-write-list</primary>
     522            </indexterm>
     523
     524            <refnamediv>
     525              <refname>CCL:STREAM-WRITE-LIST</refname>
     526              <refpurpose></refpurpose>
     527              <refclass>Generic Function</refclass>
     528            </refnamediv>
     529
     530            <refsynopsisdiv>
     531              <synopsis><function>stream-write-list</function>
     532                stream list count</synopsis>
     533            </refsynopsisdiv>
     534
     535            <refsect1>
     536              <title>Arguments and Values</title>
     537
     538              <variablelist>
     539                <varlistentry>
     540                  <term>stream</term>
     541
     542                  <listitem>
     543                        <para>a stream, presumably a fundamental-output-stream.</para>
     544                  </listitem>
     545                </varlistentry>
     546
     547                <varlistentry>
     548                  <term>list</term>
     549
     550                  <listitem>
     551                        <para>a list. When a STREAM-WRITE-LIST method is called by
     552                          WRITE-SEQUENCE, this argument is guaranteed to be a proper
     553                          list.</para>
     554                  </listitem>
     555                </varlistentry>
     556
     557                <varlistentry>
     558                  <term>count</term>
     559
     560                  <listitem>
     561                        <para>a non-negative integer. When a STREAM-WRITE-LIST
     562                          method is called by WRITE-SEQUENCE, this argument is
     563                          guaranteed not to be greater than the length of the list.</para>
     564                  </listitem>
     565                </varlistentry>
     566              </variablelist>
     567            </refsect1>
     568
     569            <refsect1>
     570              <title>Description</title>
     571
     572              <para>should try to write the first count elements of list to
     573                stream. The return value of this method is ignored.</para>
     574            </refsect1>
    575575      </refentry>
    576576
    577577      <refentry id="f_stream-read-vector">
    578         <indexterm zone="f_stream-read-vector">
    579           <primary>stream-read-vector</primary>
    580         </indexterm>
    581 
    582         <refnamediv>
    583           <refname>CCL:STREAM-READ-VECTOR</refname>
    584           <refpurpose></refpurpose>
    585           <refclass>Generic Function</refclass>
    586         </refnamediv>
    587 
    588         <refsynopsisdiv>
    589           <synopsis><function>stream-read-vector</function>
    590           stream vector start end</synopsis>
    591         </refsynopsisdiv>
    592 
    593         <refsect1>
    594           <title>Arguments and Values</title>
    595 
    596           <variablelist>
    597             <varlistentry>
    598               <term>stream</term>
    599 
    600               <listitem>
    601                 <para>a stream, presumably a fundamental-input-stream</para>
    602               </listitem>
    603             </varlistentry>
    604 
    605             <varlistentry>
    606               <term>vector</term>
    607 
    608               <listitem>
    609                 <para>a vector. When a STREAM-READ-VECTOR method is called
    610                 by READ-SEQUENCE, this argument is guaranteed to be a simple
    611                 one-dimensional array.</para>
    612               </listitem>
    613             </varlistentry>
    614 
    615             <varlistentry>
    616               <term>start</term>
    617 
    618               <listitem>
    619                 <para>a non-negative integer. When a STREAM-READ-VECTOR
    620                 method is called by READ-SEQUENCE, this argument is
    621                 guaranteed to be no greater than end and not greater than
    622                 the length of vector.</para>
    623               </listitem>
    624             </varlistentry>
    625 
    626             <varlistentry>
    627               <term>end</term>
    628 
    629               <listitem>
    630                 <para>a non-negative integer. When a STREAM-READ-VECTOR
    631                 method is called by READ-SEQUENCE, this argument is
    632                 guaranteed to be no less than end and not greater than the
    633                 length of vector.</para>
    634               </listitem>
    635             </varlistentry>
    636           </variablelist>
    637         </refsect1>
    638 
    639         <refsect1>
    640           <title>Description</title>
    641 
    642           <para>should try to read successive elements from stream into
    643           vector, starting at element start (inclusive) and continuing
    644           through element end (exclusive.) Should return the index of the
    645           vector element beyond the last one stored into, which may be less
    646           than end in case of premature end-of-file.</para>
    647         </refsect1>
     578            <indexterm zone="f_stream-read-vector">
     579              <primary>stream-read-vector</primary>
     580            </indexterm>
     581
     582            <refnamediv>
     583              <refname>CCL:STREAM-READ-VECTOR</refname>
     584              <refpurpose></refpurpose>
     585              <refclass>Generic Function</refclass>
     586            </refnamediv>
     587
     588            <refsynopsisdiv>
     589              <synopsis><function>stream-read-vector</function>
     590                stream vector start end</synopsis>
     591            </refsynopsisdiv>
     592
     593            <refsect1>
     594              <title>Arguments and Values</title>
     595
     596              <variablelist>
     597                <varlistentry>
     598                  <term>stream</term>
     599
     600                  <listitem>
     601                        <para>a stream, presumably a fundamental-input-stream</para>
     602                  </listitem>
     603                </varlistentry>
     604
     605                <varlistentry>
     606                  <term>vector</term>
     607
     608                  <listitem>
     609                        <para>a vector. When a STREAM-READ-VECTOR method is called
     610                          by READ-SEQUENCE, this argument is guaranteed to be a simple
     611                          one-dimensional array.</para>
     612                  </listitem>
     613                </varlistentry>
     614
     615                <varlistentry>
     616                  <term>start</term>
     617
     618                  <listitem>
     619                        <para>a non-negative integer. When a STREAM-READ-VECTOR
     620                          method is called by READ-SEQUENCE, this argument is
     621                          guaranteed to be no greater than end and not greater than
     622                          the length of vector.</para>
     623                  </listitem>
     624                </varlistentry>
     625
     626                <varlistentry>
     627                  <term>end</term>
     628
     629                  <listitem>
     630                        <para>a non-negative integer. When a STREAM-READ-VECTOR
     631                          method is called by READ-SEQUENCE, this argument is
     632                          guaranteed to be no less than end and not greater than the
     633                          length of vector.</para>
     634                  </listitem>
     635                </varlistentry>
     636              </variablelist>
     637            </refsect1>
     638
     639            <refsect1>
     640              <title>Description</title>
     641
     642              <para>should try to read successive elements from stream into
     643                vector, starting at element start (inclusive) and continuing
     644                through element end (exclusive.) Should return the index of the
     645                vector element beyond the last one stored into, which may be less
     646                than end in case of premature end-of-file.</para>
     647            </refsect1>
    648648      </refentry>
    649649
    650650      <refentry id="f_stream-write-vector">
    651         <indexterm zone="f_stream-write-vector">
    652           <primary>stream-write-vector</primary>
    653         </indexterm>
    654 
    655         <refnamediv>
    656           <refname>CCL:STREAM-WRITE-VECTOR</refname>
    657           <refpurpose></refpurpose>
    658           <refclass>Generic Function</refclass>
    659         </refnamediv>
    660 
    661         <refsynopsisdiv>
    662           <synopsis><function>stream-write-vector</function>
    663           stream vector start end</synopsis>
    664         </refsynopsisdiv>
    665 
    666         <refsect1>
    667           <title>Arguments and Values</title>
    668 
    669           <variablelist>
    670             <varlistentry>
    671               <term>stream</term>
    672 
    673               <listitem>
    674                 <para>a stream, presumably a fundamental-output-stream</para>
    675               </listitem>
    676             </varlistentry>
    677 
    678             <varlistentry>
    679               <term>vector</term>
    680 
    681               <listitem>
    682                 <para>a vector. When a STREAM-WRITE-VECTOR method is called
    683                 by WRITE-SEQUENCE, this argument is guaranteed to be a
    684                 simple one-dimensional array.</para>
    685               </listitem>
    686             </varlistentry>
    687 
    688             <varlistentry>
    689               <term>start</term>
    690 
    691               <listitem>
    692                 <para>a non-negative integer. When a STREAM-WRITE-VECTOR
    693                 method is called by WRITE-SEQUENCE, this argument is
    694                 guaranteed to be no greater than end and not greater than
    695                 the length of vector.</para>
    696               </listitem>
    697             </varlistentry>
    698 
    699             <varlistentry>
    700               <term>end</term>
    701 
    702               <listitem>
    703                 <para>a non-negative integer. When a STREAM-WRITE-VECTOR
    704                 method is called by WRITE-SEQUENCE, this argument is
    705                 guaranteed to be no less than end and not greater than the
    706                 length of vector.</para>
    707               </listitem>
    708             </varlistentry>
    709           </variablelist>
    710         </refsect1>
    711 
    712         <refsect1>
    713           <title>Description</title>
    714 
    715           <para>should try to write successive elements of vector to stream,
    716           starting at element start (inclusive) and continuing through
    717           element end (exclusive.)</para>
    718         </refsect1>
     651            <indexterm zone="f_stream-write-vector">
     652              <primary>stream-write-vector</primary>
     653            </indexterm>
     654
     655            <refnamediv>
     656              <refname>CCL:STREAM-WRITE-VECTOR</refname>
     657              <refpurpose></refpurpose>
     658              <refclass>Generic Function</refclass>
     659            </refnamediv>
     660
     661            <refsynopsisdiv>
     662              <synopsis><function>stream-write-vector</function>
     663                stream vector start end</synopsis>
     664            </refsynopsisdiv>
     665
     666            <refsect1>
     667              <title>Arguments and Values</title>
     668
     669              <variablelist>
     670                <varlistentry>
     671                  <term>stream</term>
     672
     673                  <listitem>
     674                        <para>a stream, presumably a fundamental-output-stream</para>
     675                  </listitem>
     676                </varlistentry>
     677
     678                <varlistentry>
     679                  <term>vector</term>
     680
     681                  <listitem>
     682                        <para>a vector. When a STREAM-WRITE-VECTOR method is called
     683                          by WRITE-SEQUENCE, this argument is guaranteed to be a
     684                          simple one-dimensional array.</para>
     685                  </listitem>
     686                </varlistentry>
     687
     688                <varlistentry>
     689                  <term>start</term>
     690
     691                  <listitem>
     692                        <para>a non-negative integer. When a STREAM-WRITE-VECTOR
     693                          method is called by WRITE-SEQUENCE, this argument is
     694                          guaranteed to be no greater than end and not greater than
     695                          the length of vector.</para>
     696                  </listitem>
     697                </varlistentry>
     698
     699                <varlistentry>
     700                  <term>end</term>
     701
     702                  <listitem>
     703                        <para>a non-negative integer. When a STREAM-WRITE-VECTOR
     704                          method is called by WRITE-SEQUENCE, this argument is
     705                          guaranteed to be no less than end and not greater than the
     706                          length of vector.</para>
     707                  </listitem>
     708                </varlistentry>
     709              </variablelist>
     710            </refsect1>
     711
     712            <refsect1>
     713              <title>Description</title>
     714
     715              <para>should try to write successive elements of vector to stream,
     716                starting at element start (inclusive) and continuing through
     717                element end (exclusive.)</para>
     718            </refsect1>
    719719      </refentry>
    720720
    721721      <refentry id="f_stream-device">
    722         <indexterm zone="f_stream-device">
    723           <primary>stream-device</primary>
    724         </indexterm>
    725 
    726         <refnamediv>
    727           <refname>CCL::STREAM-DEVICE</refname>
    728           <refpurpose>Returns the OS file descriptor associated with a
    729           given lisp stream.</refpurpose>
    730           <refclass>Generic Function</refclass>
    731         </refnamediv>
    732 
    733         <refsynopsisdiv>
    734           <synopsis><function>ccl::stream-device</function>
    735           s direction</synopsis>
    736         </refsynopsisdiv>
    737 
    738         <refsect1>
    739           <title>Method Signatures</title>
    740 
    741           <synopsis><function>ccl::stream-device</function>
    742           (s stream) direction => fd</synopsis>
    743         </refsect1>
    744 
    745         <refsect1>
    746           <title>Arguments and Values</title>
    747          
    748           <variablelist>
    749             <varlistentry>
    750               <term>s</term>
    751               <listitem>
    752                 <para>a stream.</para>
    753               </listitem>
    754             </varlistentry>
    755             <varlistentry>
    756               <term>direction</term>
    757               <listitem>
    758                 <para>either :INPUT or :OUTPUT.</para>
    759               </listitem>
    760             </varlistentry>
    761             <varlistentry>
    762               <term>fd</term>
    763               <listitem>
    764                 <para>a file descriptor, which is a non-negative integer
    765                 used by the OS to refer to an open file, socket, or similar
    766                 I/O connection.  NIL if there is no file descriptor associated
    767                 with <varname>s</varname> in the direction given by
    768                 <varname>direction</varname>.</para>
    769               </listitem>
    770             </varlistentry>
    771           </variablelist>
    772         </refsect1>
    773 
    774         <refsect1>
    775           <title>Description</title>
    776 
    777           <para>Returns the file descriptor associated with
    778           <varname>s</varname> in the direction given by
    779           <varname>direction</varname>.  It is necessary to specify
    780           <varname>direction</varname> because the input and output
    781           file descriptors may be different; the most common case is when
    782           one of them has been redirected by the Unix shell.</para>
    783         </refsect1>
     722            <indexterm zone="f_stream-device">
     723              <primary>stream-device</primary>
     724            </indexterm>
     725
     726            <refnamediv>
     727              <refname>CCL::STREAM-DEVICE</refname>
     728              <refpurpose>Returns the OS file descriptor associated with a
     729                given lisp stream.</refpurpose>
     730              <refclass>Generic Function</refclass>
     731            </refnamediv>
     732
     733            <refsynopsisdiv>
     734              <synopsis><function>ccl::stream-device</function>
     735                s direction</synopsis>
     736            </refsynopsisdiv>
     737
     738            <refsect1>
     739              <title>Method Signatures</title>
     740
     741              <synopsis><function>ccl::stream-device</function>
     742                (s stream) direction => fd</synopsis>
     743            </refsect1>
     744
     745            <refsect1>
     746              <title>Arguments and Values</title>
     747             
     748              <variablelist>
     749                <varlistentry>
     750                  <term>s</term>
     751                  <listitem>
     752                        <para>a stream.</para>
     753                  </listitem>
     754                </varlistentry>
     755                <varlistentry>
     756                  <term>direction</term>
     757                  <listitem>
     758                        <para>either :INPUT or :OUTPUT.</para>
     759                  </listitem>
     760                </varlistentry>
     761                <varlistentry>
     762                  <term>fd</term>
     763                  <listitem>
     764                        <para>a file descriptor, which is a non-negative integer
     765                          used by the OS to refer to an open file, socket, or similar
     766                          I/O connection.  NIL if there is no file descriptor associated
     767                          with <varname>s</varname> in the direction given by
     768                          <varname>direction</varname>.</para>
     769                  </listitem>
     770                </varlistentry>
     771              </variablelist>
     772            </refsect1>
     773
     774            <refsect1>
     775              <title>Description</title>
     776
     777              <para>Returns the file descriptor associated with
     778                <varname>s</varname> in the direction given by
     779                <varname>direction</varname>.  It is necessary to specify
     780                <varname>direction</varname> because the input and output
     781                file descriptors may be different; the most common case is when
     782                one of them has been redirected by the Unix shell.</para>
     783            </refsect1>
    784784      </refentry>
    785785
    786786      <refentry id="f_stream-read-ivector">
    787         <indexterm zone="f_stream-read-ivector">
    788           <primary>stream-read-ivector</primary>
    789         </indexterm>
    790 
    791         <refnamediv>
    792           <refname>STREAM-READ-IVECTOR</refname>
    793           <refpurpose></refpurpose>
    794           <refclass>Generic Function</refclass>
    795         </refnamediv>
    796 
    797         <refsynopsisdiv>
    798           <synopsis><function>stream-read-ivector</function>
    799           stream ivector start-octet max-octets</synopsis>
    800         </refsynopsisdiv>
    801 
    802         <refsect1>
    803           <title>Description</title>
    804 
    805           <para>Reads up to max-octets octets from stream into ivector,
    806           storing them at start-octet. Returns the number of octets actually
    807           read.</para>
    808         </refsect1>
    809 
    810         <refsect1>
    811           <title>Arguments</title>
    812 
    813           <variablelist>
    814             <varlistentry>
    815               <term>stream</term>
    816 
    817               <listitem>
    818                 <para>An input stream. The method defined on
    819                 BUFFERED-INPUT-STREAMs requires that the size in octets of
    820                 an instance of the stream's element type is 1.</para>
    821               </listitem>
    822             </varlistentry>
    823 
    824             <varlistentry>
    825               <term>ivector</term>
    826 
    827               <listitem>
    828                 <para>Any ivector.</para>
    829               </listitem>
    830             </varlistentry>
    831 
    832             <varlistentry>
    833               <term>start-octet</term>
    834 
    835               <listitem>
    836                 <para>A non-negative integer.</para>
    837               </listitem>
    838             </varlistentry>
    839 
    840             <varlistentry>
    841               <term>max-octets</term>
    842 
    843               <listitem>
    844                 <para>A non-negative integer. The return value may be less
    845                 than the value of this parameter if EOF was encountered.</para>
    846               </listitem>
    847             </varlistentry>
    848           </variablelist>
    849         </refsect1>
     787            <indexterm zone="f_stream-read-ivector">
     788              <primary>stream-read-ivector</primary>
     789            </indexterm>
     790
     791            <refnamediv>
     792              <refname>STREAM-READ-IVECTOR</refname>
     793              <refpurpose></refpurpose>
     794              <refclass>Generic Function</refclass>
     795            </refnamediv>
     796
     797            <refsynopsisdiv>
     798              <synopsis><function>stream-read-ivector</function>
     799                stream ivector start-octet max-octets</synopsis>
     800            </refsynopsisdiv>
     801
     802            <refsect1>
     803              <title>Description</title>
     804
     805              <para>Reads up to max-octets octets from stream into ivector,
     806                storing them at start-octet. Returns the number of octets actually
     807                read.</para>
     808            </refsect1>
     809
     810            <refsect1>
     811              <title>Arguments</title>
     812
     813              <variablelist>
     814                <varlistentry>
     815                  <term>stream</term>
     816
     817                  <listitem>
     818                        <para>An input stream. The method defined on
     819                          BUFFERED-INPUT-STREAMs requires that the size in octets of
     820                          an instance of the stream's element type is 1.</para>
     821                  </listitem>
     822                </varlistentry>
     823
     824                <varlistentry>
     825                  <term>ivector</term>
     826
     827                  <listitem>
     828                        <para>Any ivector.</para>
     829                  </listitem>
     830                </varlistentry>
     831
     832                <varlistentry>
     833                  <term>start-octet</term>
     834
     835                  <listitem>
     836                        <para>A non-negative integer.</para>
     837                  </listitem>
     838                </varlistentry>
     839
     840                <varlistentry>
     841                  <term>max-octets</term>
     842
     843                  <listitem>
     844                        <para>A non-negative integer. The return value may be less
     845                          than the value of this parameter if EOF was encountered.</para>
     846                  </listitem>
     847                </varlistentry>
     848              </variablelist>
     849            </refsect1>
    850850      </refentry>
    851851
    852852      <refentry id="f_stream-write-ivector">
    853         <indexterm zone="f_stream-write-ivector">
    854           <primary>stream-write-ivector</primary>
    855         </indexterm>
    856 
    857         <refnamediv>
    858           <refname>STREAM-WRITE-IVECTOR</refname>
    859           <refpurpose></refpurpose>
    860           <refclass>Generic Function</refclass>
    861         </refnamediv>
    862 
    863         <refsynopsisdiv>
    864           <synopsis><function>stream-write-ivector stream</function>
    865           ivector start-octet max-octets</synopsis>
    866         </refsynopsisdiv>
    867 
    868         <refsect1>
    869           <title>Description</title>
    870 
    871           <para>Writes max-octets octets to stream from ivector, starting at
    872           start-octet. Returns max-octets.</para>
    873         </refsect1>
    874 
    875         <refsect1>
    876           <title>Arguments</title>
    877 
    878           <variablelist>
    879             <varlistentry>
    880               <term>stream</term>
    881 
    882               <listitem>
    883                 <para>An input stream. The method defined on
    884                 BUFFERED-OUTPUT-STREAMs requires that the size in octets of
    885                 an instance of the stream's element type is 1.</para>
    886               </listitem>
    887             </varlistentry>
    888 
    889             <varlistentry>
    890               <term>ivector</term>
    891 
    892               <listitem>
    893                 <para>Any ivector</para>
    894               </listitem>
    895             </varlistentry>
    896 
    897             <varlistentry>
    898               <term>start-octet</term>
    899 
    900               <listitem>
    901                 <para>A non-negative integer.</para>
    902               </listitem>
    903             </varlistentry>
    904 
    905             <varlistentry>
    906               <term>max-octet</term>
    907 
    908               <listitem>
    909                 <para>A non-negative integer.</para>
    910               </listitem>
    911             </varlistentry>
    912           </variablelist>
    913         </refsect1>
    914 
    915         <refsect1>
    916           <title>Examples</title>
    917 
    918           <programlisting format="linespecific">;;; Write the contents of a (SIMPLE-ARRAY(UNSIGNED-BYTE 16) 3)
    919           ;;; to a character file stream. Read back the characters.
    920           (let* ((a (make-array 3
    921           :element-type '(unsigned-byte 16)
    922           :initial-contents '(26725 27756 28449))))
    923           (with-open-file (s "junk"
    924           :element-type 'character
    925           :direction :io
    926           :if-does-not-exist :create
    927           :if-exists :supersede)
    928           ;; Write six octets (three elements).
    929           (stream-write-ivector s a 0 6)
    930           ;; Rewind, then read a line
    931           (file-position s 0)
    932           (read-line s)))
    933 
    934           ;;; Write a vector of DOUBLE-FLOATs. Note that (to maintain
    935           ;;; alignment) there are 4 octets of padding before the 0th
    936           ;;; element of a (VECTOR DOUBLE-FLOAT).
    937           ;;; (Note that (= (- arch::misc-dfloat-offset
    938           ;;;                  arch::misc-data-offset) 4))
    939           (defun write-double-float-vector
    940           (stream vector &#38;key (start 0) (end (length vector)))
    941           (check-type vector (vector double-float))
    942           (let* ((start-octet (+ (* start 8)
    943           (- arch::misc-dfloat-offset
    944           arch::misc-data-offset)))
    945           (num-octets (* 8 (- end start))))
    946           (stream-write-ivector stream vector start-octet num-octets)))</programlisting>
    947         </refsect1>
     853            <indexterm zone="f_stream-write-ivector">
     854              <primary>stream-write-ivector</primary>
     855            </indexterm>
     856
     857            <refnamediv>
     858              <refname>STREAM-WRITE-IVECTOR</refname>
     859              <refpurpose></refpurpose>
     860              <refclass>Generic Function</refclass>
     861            </refnamediv>
     862
     863            <refsynopsisdiv>
     864              <synopsis><function>stream-write-ivector stream</function>
     865                ivector start-octet max-octets</synopsis>
     866            </refsynopsisdiv>
     867
     868            <refsect1>
     869              <title>Description</title>
     870
     871              <para>Writes max-octets octets to stream from ivector, starting at
     872                start-octet. Returns max-octets.</para>
     873            </refsect1>
     874
     875            <refsect1>
     876              <title>Arguments</title>
     877
     878              <variablelist>
     879                <varlistentry>
     880                  <term>stream</term>
     881
     882                  <listitem>
     883                        <para>An input stream. The method defined on
     884                          BUFFERED-OUTPUT-STREAMs requires that the size in octets of
     885                          an instance of the stream's element type is 1.</para>
     886                  </listitem>
     887                </varlistentry>
     888
     889                <varlistentry>
     890                  <term>ivector</term>
     891
     892                  <listitem>
     893                        <para>Any ivector</para>
     894                  </listitem>
     895                </varlistentry>
     896
     897                <varlistentry>
     898                  <term>start-octet</term>
     899
     900                  <listitem>
     901                        <para>A non-negative integer.</para>
     902                  </listitem>
     903                </varlistentry>
     904
     905                <varlistentry>
     906                  <term>max-octet</term>
     907
     908                  <listitem>
     909                        <para>A non-negative integer.</para>
     910                  </listitem>
     911                </varlistentry>
     912              </variablelist>
     913            </refsect1>
     914
     915            <refsect1>
     916              <title>Examples</title>
     917
     918              <programlisting format="linespecific">
     919;;; Write the contents of a (SIMPLE-ARRAY(UNSIGNED-BYTE 16) 3)
     920;;; to a character file stream. Read back the characters.
     921(let* ((a (make-array 3
     922                      :element-type '(unsigned-byte 16)
     923                      :initial-contents '(26725 27756 28449))))
     924  (with-open-file (s "junk"
     925                     :element-type 'character
     926                     :direction :io
     927                     :if-does-not-exist :create
     928                     :if-exists :supersede)
     929    ;; Write six octets (three elements).
     930    (stream-write-ivector s a 0 6)
     931    ;; Rewind, then read a line
     932    (file-position s 0)
     933    (read-line s)))
     934
     935;;; Write a vector of DOUBLE-FLOATs. Note that (to maintain
     936;;; alignment) there are 4 octets of padding before the 0th
     937;;; element of a (VECTOR DOUBLE-FLOAT).
     938;;; (Note that (= (- arch::misc-dfloat-offset
     939;;;                  arch::misc-data-offset) 4))
     940(defun write-double-float-vector
     941    (stream vector &#38;key (start 0) (end (length vector)))
     942     (check-type vector (vector double-float))
     943     (let* ((start-octet (+ (* start 8)
     944                            (- arch::misc-dfloat-offset
     945                               arch::misc-data-offset)))
     946                (num-octets (* 8 (- end start))))
     947       (stream-write-ivector stream vector start-octet num-octets)))
     948          </programlisting>
     949            </refsect1>
    948950      </refentry>
    949951    </sect2>
  • 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>