Changeset 8702


Ignore:
Timestamp:
Mar 10, 2008, 10:23:42 PM (11 years ago)
Author:
mikel
Message:

added discussion of memory-mapped files

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

Legend:

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

    r8695 r8702  
    6666  </glossdiv>
    6767
     68  <glossdiv id="D">
     69        <!-- ******************** D ********************  -->
     70        <title>D</title>
     71
     72        <glossentry id="displaced-array">
     73          <glossterm>displaced array</glossterm>
     74
     75          <glossdef>
     76
     77                <para>An array with no storage of its own for elements, which
     78                points to the storage of another array, called its
     79                target. Reading or writing the elements of the displaced array
     80                returns or changes the contents of the target.</para>
     81
     82          </glossdef>
     83        </glossentry>
     84
     85  </glossdiv>
     86
    6887  <glossdiv id="H">
    6988        <!-- ******************** H ********************  -->
     
    133152                window that contains a pseudo-terminal session that
    134153                communicates with a Lisp <glossterm linkend="REPL">REPL</glossterm>.</para>
     154
     155          </glossdef>
     156
     157        </glossentry>
     158   
     159  </glossdiv>
     160
     161  <glossdiv id="M">
     162        <!-- ******************** M ********************  -->
     163        <title>M</title>
     164
     165        <glossentry id="memory_mapped_file">
     166          <glossterm>memory-mapped file</glossterm>
     167
     168          <glossdef>
     169
     170                <para>A file whose contents are accessible as a range of
     171                memory addresses. Some operating systems support this feature,
     172                in which the virtual memory subsystem arranges for a range of
     173                virtual memory addresses to point to the contents of an open
     174                file. Programs can then gain access to the file's contents by
     175                operating on memory addresses in that range. Access to the
     176                file's contents is valid only as long as the file remains
     177                open.</para>
    135178
    136179          </glossdef>
     
    184227  </glossdiv>
    185228
     229  <glossdiv id="S">
     230
     231        <!-- ******************** S ********************  -->
     232        <title>S</title>
     233
     234        <glossentry id="s-expression">
     235          <glossterm>s-expression</glossterm>
     236
     237          <glossdef>
     238
     239                <para>The simplest, most general element of Lisp syntax. An
     240                s-expression may be an atom (such as a symbol, integer, or
     241                string), or it may be a list of s-expressions.</para>
     242
     243          </glossdef>
     244
     245        </glossentry>
     246   
     247  </glossdiv>
     248
     249  <glossdiv id="T">
     250
     251        <!-- ******************** T ********************  -->
     252        <title>T</title>
     253
     254        <glossentry id="type-specifier">
     255          <glossterm>type-specifier</glossterm>
     256
     257          <glossdef>
     258
     259                <para>An expression that denotes a type. Type specifiers may
     260                be symbols (such as <code>CONS</code>
     261                and <code>STRING</code>), or they may be more complex
     262                <glossterm linkend="s-expression">S-expressions</glossterm>
     263                (such as (UNSIGNED-BYTE 8)).</para>
     264
     265          </glossdef>
     266
     267        </glossentry>
     268   
     269  </glossdiv>
     270
    186271</glossary>
    187272
  • trunk/source/doc/src/q-and-a.xml

    r8606 r8702  
    7373      <para>For the most part, this is only relevant when you are
    7474      trying to insert debug code into your event handlers.  The SLIME
    75       listener runs in a thread where the standard stream varaiables
     75      listener runs in a thread where the standard stream variables
    7676      (like <literal>*STANDARD-OUTPUT* and</literal> and
    7777      <literal>*TERMINAL-IO*</literal> are bound to the stream used to
  • trunk/source/doc/src/using.xml

    r8673 r8702  
    2626  <sect1 id="Trace"><title>Trace</title>
    2727
    28   <para>
    29     &CCL;'s tracing facility is invoked by an extended version of the Common Lisp
    30     <varname>trace</varname> macro.  Extensions allow tracing of methods, as well as finer control
    31     over tracing actions.
    32   </para>
    33 
    34 
    35   <para>
    36   <command><varname>TRACE</varname> {<replaceable>spec</replaceable> |
    37   (<replaceable>spec</replaceable> {<replaceable>option-key</replaceable>
    38   <replaceable>value</replaceable>}*)}* [Macro]</command>
    39   </para>
    40 
    41   <para>
    42     The <varname>trace</varname> macro encapsulates the function named by
    43     <replaceable>spec</replaceable>, causing trace actions to take place on entry and exit from the
    44     function.  The default actions print a message on function entry and exit.
    45   </para>
    46 
    47   <para>
    48     Invoking <varname>(trace)</varname> without arguments returns a list of functions being traced.
    49   </para>
    50      
    51   <para>
    52     A <replaceable>spec</replaceable> is either a symbol that is the name of a function, or an
    53     expression of the form <varname>(setf <replaceable>symbol</replaceable>)</varname>, or a
    54     specific method of a generic function in the form <varname>(:method
    55     <replaceable>gf-name</replaceable> {<replaceable>qualifier</replaceable>}* (
    56     {<replaceable>specializer</replaceable>}* ) )</varname>, where a
    57     <replaceable>specializer</replaceable> can be the name of a class or an <varname>EQL</varname>
    58     specializer.
    59   </para>
    60 
    61    <para>By default, whenever a traced function is entered or exited, a short message is printed
    62    on <varname>*trace-output*</varname> showing the arguments on entry and values on exit.
    63    The following <replaceable>option-keys</replaceable> can be used to modify this behavior:</para>
    64 
    65    <variablelist>
    66      <varlistentry>
    67        <term><varname>:before</varname></term>
    68        <listitem>
    69          <para>specifies the action to be taken just before the traced function is entered.  The
    70          value is one of:</para>
    71          <variablelist>
    72            <varlistentry>
    73              <term><varname>:print</varname></term>
    74              <listitem>
    75                <para>The default, prints a short indented message showing the function name and the invocation arguments </para>
    76              </listitem>
    77            </varlistentry>
    78            <varlistentry>
    79              <term><varname>:break</varname></term>
    80              <listitem>
    81              <para>Enters the debugger after printing the standard function entry message</para>
    82              </listitem>
    83            </varlistentry>
    84            <varlistentry>
    85              <term><replaceable>function</replaceable></term>
    86              <listitem>
    87                <para>Any other value is interpreted as a function to
    88                call on entry instead of printing the standard entry
    89                message.  It is called with its first argument being
    90                the name of the function being traced, the
    91                remaining arguments being all the arguments to the function
    92                being traced, and ccl:*trace-level* bound to the current
    93                nesting level of trace actions.
    94                </para>
    95              </listitem>
    96            </varlistentry>
    97          </variablelist>
    98        </listitem>
    99      </varlistentry>
    100 
    101      <varlistentry>
    102        <term><varname>:after</varname></term>
    103        <listitem>
    104          <para>specifies the action to be taken just after the traced function exits.  The
    105          value is one of:</para>
    106          <variablelist>
    107            <varlistentry>
    108              <term><varname>:print</varname></term>
    109              <listitem>
    110                <para>The default, prints a short indented message showing the function name and the
    111                returned values </para>
    112              </listitem>
    113            </varlistentry>
    114            <varlistentry>
    115              <term><varname>:break</varname></term>
    116              <listitem>
    117              <para>Enters the debugger after printing the standard function exit message</para>
    118              </listitem>
    119            </varlistentry>
    120            <varlistentry>
    121              <term><replaceable>function</replaceable></term>
    122              <listitem>
    123                <para>Any other value is interpreted as a function to
    124                call on exit instead of printing the standard exit
    125                message.  It is called with its first argument being
    126                the name of the function being traced, the
    127                remaining arguments being all the values returned by the function
    128                being traced, and ccl:*trace-level* bound to the current
    129                nesting level of trace actions.
    130                </para>
    131              </listitem>
    132            </varlistentry>
    133          </variablelist>
    134        </listitem>
    135      </varlistentry>
    136 
    137 
    138      <varlistentry>
    139        <term><varname>:backtrace</varname></term>
    140        <listitem>
    141          <para>If true, requests that a stack backtrace (in brief format) be printed whenever the function is
    142          invoked. The value can be an integer, in which case it is the maximum number of frames to
    143          print. Otherwise, all frames are shown.
    144          </para>
    145        </listitem>
    146      </varlistentry>
    147 
    148 
    149 
    150    </variablelist>
     28    <para>
     29      &CCL;'s tracing facility is invoked by an extended version of the Common Lisp
     30      <varname>trace</varname> macro.  Extensions allow tracing of methods, as well as finer control
     31      over tracing actions.
     32    </para>
     33
     34
     35    <para>
     36      <command><varname>TRACE</varname> {<replaceable>spec</replaceable> |
     37        (<replaceable>spec</replaceable> {<replaceable>option-key</replaceable>
     38        <replaceable>value</replaceable>}*)}* [Macro]</command>
     39    </para>
     40
     41    <para>
     42      The <varname>trace</varname> macro encapsulates the function named by
     43      <replaceable>spec</replaceable>, causing trace actions to take place on entry and exit from the
     44      function.  The default actions print a message on function entry and exit.
     45    </para>
     46
     47    <para>
     48      Invoking <varname>(trace)</varname> without arguments returns a list of functions being traced.
     49    </para>
     50   
     51    <para>
     52      A <replaceable>spec</replaceable> is either a symbol that is the name of a function, or an
     53      expression of the form <varname>(setf <replaceable>symbol</replaceable>)</varname>, or a
     54      specific method of a generic function in the form <varname>(:method
     55        <replaceable>gf-name</replaceable> {<replaceable>qualifier</replaceable>}* (
     56        {<replaceable>specializer</replaceable>}* ) )</varname>, where a
     57      <replaceable>specializer</replaceable> can be the name of a class or an <varname>EQL</varname>
     58      specializer.
     59    </para>
     60
     61    <para>By default, whenever a traced function is entered or exited, a short message is printed
     62      on <varname>*trace-output*</varname> showing the arguments on entry and values on exit.
     63      The following <replaceable>option-keys</replaceable> can be used to modify this behavior:</para>
     64
     65    <variablelist>
     66      <varlistentry>
     67        <term><varname>:before</varname></term>
     68        <listitem>
     69              <para>specifies the action to be taken just before the traced function is entered.  The
     70                value is one of:</para>
     71              <variablelist>
     72                <varlistentry>
     73                  <term><varname>:print</varname></term>
     74                  <listitem>
     75                    <para>The default, prints a short indented message showing the function name and the invocation arguments </para>
     76                  </listitem>
     77                </varlistentry>
     78                <varlistentry>
     79                  <term><varname>:break</varname></term>
     80                  <listitem>
     81                    <para>Enters the debugger after printing the standard function entry message</para>
     82                  </listitem>
     83                </varlistentry>
     84                <varlistentry>
     85                  <term><replaceable>function</replaceable></term>
     86                  <listitem>
     87                    <para>Any other value is interpreted as a function to
     88                      call on entry instead of printing the standard entry
     89                      message.  It is called with its first argument being
     90                      the name of the function being traced, the
     91                      remaining arguments being all the arguments to the function
     92                      being traced, and ccl:*trace-level* bound to the current
     93                      nesting level of trace actions.
     94                    </para>
     95                  </listitem>
     96                </varlistentry>
     97              </variablelist>
     98        </listitem>
     99      </varlistentry>
     100
     101      <varlistentry>
     102        <term><varname>:after</varname></term>
     103        <listitem>
     104              <para>specifies the action to be taken just after the traced function exits.  The
     105                value is one of:</para>
     106              <variablelist>
     107                <varlistentry>
     108                  <term><varname>:print</varname></term>
     109                  <listitem>
     110                    <para>The default, prints a short indented message showing the function name and the
     111                      returned values </para>
     112                  </listitem>
     113                </varlistentry>
     114                <varlistentry>
     115                  <term><varname>:break</varname></term>
     116                  <listitem>
     117                    <para>Enters the debugger after printing the standard function exit message</para>
     118                  </listitem>
     119                </varlistentry>
     120                <varlistentry>
     121                  <term><replaceable>function</replaceable></term>
     122                  <listitem>
     123                    <para>Any other value is interpreted as a function to
     124                      call on exit instead of printing the standard exit
     125                      message.  It is called with its first argument being
     126                      the name of the function being traced, the
     127                      remaining arguments being all the values returned by the function
     128                      being traced, and ccl:*trace-level* bound to the current
     129                      nesting level of trace actions.
     130                    </para>
     131                  </listitem>
     132                </varlistentry>
     133              </variablelist>
     134        </listitem>
     135      </varlistentry>
     136
     137
     138      <varlistentry>
     139        <term><varname>:backtrace</varname></term>
     140        <listitem>
     141              <para>If true, requests that a stack backtrace (in brief format) be printed whenever the function is
     142                invoked. The value can be an integer, in which case it is the maximum number of frames to
     143                print. Otherwise, all frames are shown.
     144              </para>
     145        </listitem>
     146      </varlistentry>
     147
     148    </variablelist>
    151149  </sect1>
    152150
     
    171169    </sect2>
    172170  </sect1>
     171
     172<sect1 id="Memory-Mapped-Files">
     173  <title>Memory-mapped Files</title>
     174  <para>In release 1.2 and later, &CCL;
     175    supports <glossterm linkend="memory_mapped_file">memory-mapped
     176      files</glossterm>. On operating systems that support memory-mapped
     177    files (including Mac OS X, Linux, and FreeBSD), the operating
     178    system can arrange for a range of virtual memory addresses to
     179    refer to the contents of an open file. As long as the file remains
     180    open, programs can read values from the file by reading addresses
     181    in the mapped range.</para>
     182
     183  <para>Using memory-mapped files may in some cases be more
     184    efficient than reading the contents of a file into a data
     185    structure in memory.</para>
     186
     187  <para>&CCL; provides the
     188    functions <code>CCL:MAP-FILE-TO-IVECTOR</code>
     189    and <code>CCL:MAP-FILE-TO-OCTET-VECTOR</code> to support
     190    memory-mapping. These functions return vectors whose contents are
     191    the contents of memory-mapped files. Reading an element of such a
     192    vector returns data from the correponding position in the
     193    file.</para>
     194
     195  <para>Without memory-mapped files, a common idiom for reading the
     196  contents of files might be something like this:</para>
     197
     198  <programlisting>
     199  (let* ((stream (open pathname :direction :input :element-type '(unsigned-byte 8)))
     200         (vector (make-array (file-size-to-vector-size stream)
     201                             :element-type '(unsigned-byte 8))))
     202    (read-sequence vector stream))
     203  </programlisting>
     204
     205  <para>Using a memory-mapped files has a result that is the same in
     206  that, like the above example, it returns a vector whose contents are
     207  the same as the contents of the file. It differs in that the above
     208  example creates a new vector in memory and copies the file's
     209  contents into it; using a memory-mapped file instead arranges for
     210  the vector's elements to point to the file's contents on disk
     211  directly, without copying them into memory first.</para>
     212
     213  <para>The vectors returned by <code>CCL:MAP-FILE-TO-IVECTOR</code>
     214    and <code>CCL:MAP-FILE-TO-OCTET-VECTOR</code> are read-only; any
     215    attempt to change an element of a vector returned by these
     216    functions results in a memory-access error. &CCL; does not
     217    currently support writing data to memory-mapped files.</para>
     218
     219  <para>Vectors created by <code>CCL:MAP-FILE-TO-IVECTOR</code>
     220    and <code>CCL:MAP-FILE-TO-OCTET-VECTOR</code> are required to
     221    respect &CCL;'s limit on the total size of an array. That means
     222    that you cannot use these functions to create a vector longer
     223    than <code>ARRAY-TOTAL-SIZE-LIMIT</code>, even if the filesystem
     224    supports file sizes that are larger. The value
     225    of <code>ARRAY-TOTAL-SIZE-LIMIT</code> is <code>(EXPT 2 24)</code>
     226    on 32-but platforms; and <code>(EXPT 2 56)</code> on 64-bit
     227    platforms.</para>
     228
     229  <para>
     230    <command><varname>CCL:MAP-FILE-TO-IVECTOR</varname>
     231      <parameter>pathname</parameter>
     232      <parameter>element-type</parameter>
     233      [Function]</command>
     234  </para>
     235
     236  <variablelist>
     237      <varlistentry>
     238        <term><varname>pathname</varname></term>
     239        <listitem>
     240          <para>The pathname of the file to be memory-mapped.</para>
     241        </listitem>
     242      </varlistentry>
     243   
     244      <varlistentry>
     245        <term><varname>element-type</varname></term>
     246        <listitem>
     247          <para>The element-type of the vector to be
     248          created. Specified as
     249          a <glossterm linkend="type-specifier">type-specifier</glossterm>
     250          that names a subtype of either <code>SIGNED-BYTE</code>
     251          or <code>UNSIGNED-BYTE</code>.</para>
     252        </listitem>
     253      </varlistentry>
     254  </variablelist>
     255
     256
     257    <para>
     258      The <varname>map-file-to-ivector</varname> function tries to
     259      open the file at <parameter>pathname</parameter> for reading. If
     260      successful, the function maps the file's contents to a range of
     261      virtual addresses. If successful, it returns a read-only vector
     262      whose element-type is given
     263      by <parameter>element-type</parameter>, and whose contents are
     264      the contents of the memory-mapped file.
     265    </para>
     266
     267    <para>The returned vector is
     268    a <glossterm linkend="displaced-array">displaced-array</glossterm>
     269    whose element-type is <code>(UPGRADED-ARRAY-ELEMENT-TYPE
     270    element-type)</code>. The target of the displaced array is a
     271    vector of type <code>(SIMPLE-ARRAY element-type (*))</code> whose
     272    elements are the contents of the memory-mapped file.</para>
     273
     274    <para>Because of alignment issues, the mapped file's contents
     275      start a few bytes (4 bytes on 32-bit platforms, 8 bytes on
     276      64-bit platforms) into the vector. The displaced array returned
     277      by <code>CCL:MAP-FILE-TO-IVECTOR</code> hides this overhead, but
     278      it's usually more efficient to operate on the underlying simple
     279      1-dimensional array.  Given a displaced array (like the value
     280      returned by <code>CCL:MAP-FILE-TO-IVECTOR</code>), the function
     281      <code>ARRAY-DISPLACEMENT</code> returns the underlying array and
     282      the displacement index in elements.
     283    </para>
     284
     285    <para>Currently, &CCL; supports only read operations on
     286    memory-mapped files. If you try to change the contents of an array
     287    returned by <varname>map-file-to-ivector</varname>, &CCL; signals
     288    a memory error.</para>
     289
     290  <para>
     291    <command><varname>CCL:UNMAP-IVECTOR</varname>
     292      <parameter>displaced-array</parameter>
     293      [Function]</command>
     294  </para>
     295
     296  <para>If the argument is a displaced-array returned
     297   by <varname>map-file-to-ivector</varname>, and if it has not yet
     298   been unmapped by this function,
     299   then <varname>unmap-ivector</varname> undoes the memory mapping,
     300   closes the mapped file, and changes the displaced-array so that its
     301   target is an empty vector (of length zero).</para>
     302
     303  <para>
     304    <command><varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname>
     305      <parameter>pathname</parameter>
     306      [Function]</command>
     307  </para>
     308
     309  <para>This function is a synonym for <code>(CCL:MAP-FILE-TO-IVECTOR
     310  pathname '(UNSIGNED-BYTE 8))</code> It is provided as a convenience
     311  for the common case of memory-mapping a file as a vector of
     312  bytes.</para>
     313
     314  <para>
     315    <command><varname>CCL:UNMAP-OCTET-VECTOR</varname>
     316      <parameter>displaced-array</parameter>
     317      [Function]</command>
     318  </para>
     319
     320  <para>This function is a synonym
     321  for <code>(CCL:UNMAP-IVECTOR)</code></para>
     322</sect1>
     323
     324
    173325</chapter>
Note: See TracChangeset for help on using the changeset viewer.