source: trunk/source/doc/src/using.xml @ 8776

Last change on this file since 8776 was 8776, checked in by gz, 14 years ago

document a few more trace variables, add indexterm entries for all definitions

File size: 29.1 KB
Line 
1<?xml version="1.0" encoding="utf-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3          "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
4          <!ENTITY rest "<varname>&amp;rest</varname>">
5          <!ENTITY key "<varname>&amp;key</varname>">
6          <!ENTITY optional "<varname>&amp;optional</varname>">
7          <!ENTITY body "<varname>&amp;body</varname>">
8          <!ENTITY aux "<varname>&amp;aux</varname>">
9          <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
10          <!ENTITY CCL "<literal>CCL</literal>">
11          ]>
12
13<chapter><title>Using &CCL;</title>
14 
15  <sect1><title>Introduction</title>
16   
17    <para>The Common Lisp standard allows considerable latitude in the
18      details of an implementation, and each particular Common Lisp
19      system has some idiosyncracies. This chapter describes ordinary
20      user-level features of &CCL;, including features that may be
21      part of the Common Lisp standard, but which may have quirks or
22      details in the &CCL; implementation that are not described by
23      the standard.</para>
24  </sect1>
25
26  <sect1 id="Trace"><title>Trace</title>
27
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    <indexterm zone="trace"/>
37    <command><varname id="trace">TRACE</varname> {<replaceable>keyword</replaceable>
38    <replaceable>global-value</replaceable>}* {<replaceable>spec</replaceable> |
39    (<replaceable>spec</replaceable> {<replaceable>keyword</replaceable>
40    <replaceable>local-value</replaceable>}*)}* [Macro]</command>
41    </para>
42
43    <para>
44      The <varname>trace</varname> macro encapsulates the functions named by
45      <replaceable>spec</replaceable>s, causing trace actions to take place on entry and
46      exit from each function.  The default actions print a message on function entry and
47      exit. <replaceable>Keyword</replaceable>/<replaceable>value</replaceable> options
48      can be used to specify changes in the default behavior.
49    </para>
50
51    <para>
52      Invoking <varname>(trace)</varname> without arguments returns a list of functions being traced.
53    </para>
54   
55    <para>
56      A <replaceable>spec</replaceable> is either a symbol that is the name of a function, or an
57      expression of the form <varname>(setf <replaceable>symbol</replaceable>)</varname>, or a
58      specific method of a generic function in the form <varname>(:method
59      <replaceable>gf-name</replaceable> {<replaceable>qualifier</replaceable>}*
60      ({<replaceable>specializer</replaceable>}*))</varname>, where a
61      <replaceable>specializer</replaceable> can be the name of a class or an <varname>EQL</varname>
62      specializer.
63    </para>
64
65    <para>
66      A <replaceable>spec</replaceable> can also be a string naming a package, or equivalently a
67      list <varname>(:package <replaceable>package-name</replaceable>)</varname>, in order to
68      request that all functions in the package to be traced.
69    </para>
70
71    <para>
72      By default, whenever a traced function is entered or exited, a short message is
73      printed on <varname>*trace-output*</varname> showing the arguments on entry and
74      values on exit.  Options specified as key/value pairs can be used to modify this
75      behavior.  Options preceding the function <replaceable>spec</replaceable>s apply to
76      all the functions being traced.  Options specified along with a
77      <replaceable>spec</replaceable> apply to that spec only and override any
78      global options. The following options are supported:
79    </para>
80
81    <variablelist>
82
83      <varlistentry>
84        <term><varname>:methods {T | nil}</varname></term>
85        <listitem>
86          <para> If true, and if applied to a <replaceable>spec</replaceable> naming a generic
87          function, arranges to trace all the methods of the generic function in addition to the
88          generic function itself.
89          </para>
90        </listitem>
91      </varlistentry>
92
93      <varlistentry>
94        <term><varname>:if <replaceable>form</replaceable></varname></term>
95        <term><varname>:condition <replaceable>form</replaceable></varname></term>
96        <listitem>
97          <para> Evaluates <replaceable>form</replaceable> whenever the function being traced is
98          about to be entered, and inhibits all trace actions if <replaceable>form</replaceable>
99          returns nil. The form may reference the lexical variable <varname>ccl::args</varname>,
100          which is a list of the arguments in this call. <varname>:condition</varname> is just a
101          synonym for <varname>:if</varname>, though if both are specified, both must return non-nil.
102          </para>
103        </listitem>
104      </varlistentry>
105
106      <varlistentry>
107        <term><varname>:before-if <replaceable>form</replaceable></varname></term>
108        <listitem>
109          <para> Evaluates <replaceable>form</replaceable> whenever the function being traced is
110          about to be entered, and inhibits the entry trace actions if
111          <replaceable>form</replaceable> returns nil.  The form may reference the lexical variable
112          <varname>ccl::args</varname>, which is a list of the arguments in this call. If both
113          <varname>:if</varname> and <varname>:before-if</varname> are specified, both must return
114          non-nil in order for the before entry actions to happen.
115          </para>
116        </listitem>
117      </varlistentry>
118
119      <varlistentry>
120        <term><varname>:after-if <replaceable>form</replaceable></varname></term>
121        <listitem>
122          <para> Evaluates <replaceable>form</replaceable> whenever the function being traced has
123          just exited, and inhibits the exit trace actions if <replaceable>form</replaceable>
124          returns nil.  The form may reference the lexical variable <varname>ccl::vals</varname>,
125          which is a list of values returned by this call. If both <varname>:if</varname> and
126          <varname>:after-if</varname> are specified, both must return non-nil in order for the
127          after exit actions to happen.
128          </para>
129        </listitem>
130      </varlistentry>
131
132      <varlistentry>
133        <term><varname>:print-before <replaceable>form</replaceable></varname></term>
134        <listitem>
135          <para> Evaluates <replaceable>form</replaceable> whenever the function being traced is
136          about to be entered, and prints the result before printing the standard entry message.
137          The form may reference the lexical variable <varname>ccl::args</varname>, which is a list
138          of the arguments in this call.  To see multiple forms, use <varname>values</varname>:
139          <varname>:print-before (values (one-thing) (another-thing))</varname>.
140          </para>
141        </listitem>
142      </varlistentry>
143
144      <varlistentry>
145        <term><varname>:print-after <replaceable>form</replaceable></varname></term>
146        <listitem>
147          <para> Evaluates <replaceable>form</replaceable> whenever the function being traced has
148          just exited, and prints the result after printing the standard exit message.  The form may
149          reference the lexical variable <varname>ccl::vals</varname>, which is a list of values
150          returned by this call. To see multiple forms, use <varname>values</varname>:
151          <varname>:print-after (values (one-thing) (another-thing))</varname>.
152          </para>
153        </listitem>
154      </varlistentry>
155
156      <varlistentry>
157        <term><varname>:print <replaceable>form</replaceable></varname></term>
158        <listitem>
159          <para>Equivalent to <varname>:print-before <replaceable>form</replaceable> :print-after <replaceable>form</replaceable></varname>.
160          </para>
161        </listitem>
162      </varlistentry>
163
164      <varlistentry>
165        <term><varname>:eval-before <replaceable>form</replaceable></varname></term>
166        <listitem>
167          <para>Evaluates <replaceable>form</replaceable> whenever the function being traced is
168          about to be entered.  The form may reference the lexical variable
169          <varname>ccl::args</varname>, which is a list of the arguments in this call.
170          </para>
171        </listitem>
172      </varlistentry>
173
174      <varlistentry>
175        <term><varname>:eval-after <replaceable>form</replaceable></varname></term>
176        <listitem>
177          <para>Evaluates <replaceable>form</replaceable> whenever the function being has just
178          exited.  The form may reference the lexical variable <varname>ccl::vals</varname>, which
179          is a list of values returned by this call.
180          </para>
181        </listitem>
182      </varlistentry>
183
184      <varlistentry>
185        <term><varname>:eval <replaceable>form</replaceable></varname></term>
186        <listitem>
187          <para>Equivalent to <varname>:eval-before <replaceable>form</replaceable>
188          :eval-after <replaceable>form</replaceable></varname>.
189          </para>
190        </listitem>
191      </varlistentry>
192
193      <varlistentry>
194        <term><varname>:break-before <replaceable>form</replaceable></varname></term>
195        <listitem>
196          <para>Evaluates <replaceable>form</replaceable> whenever the function being traced is
197          about to be entered, and if the result is non-nil, enters a debugger break loop.  The form
198          may reference the lexical variable <varname>ccl::args</varname>, which is a list of the
199          arguments in this call.
200          </para>
201        </listitem>
202      </varlistentry>
203
204      <varlistentry>
205        <term><varname>:break-after <replaceable>form</replaceable></varname></term>
206        <listitem>
207          <para>Evaluates <replaceable>form</replaceable> whenever the function being traced has
208          just exited, and if the result is non-nil, enters a debugger break loop. The form may
209          reference the lexical variable <varname>ccl::vals</varname>, which is a list of values
210          returned by this call.
211          </para>
212        </listitem>
213      </varlistentry>
214
215      <varlistentry>
216        <term><varname>:break <replaceable>form</replaceable></varname></term>
217        <listitem>
218          <para>Equivalent to <varname>:break-before <replaceable>form</replaceable> :break-after <replaceable>form</replaceable></varname>.
219          </para>
220        </listitem>
221      </varlistentry>
222
223      <varlistentry>
224        <term><varname>:backtrace-before <replaceable>form</replaceable></varname></term>
225        <term><varname>:backtrace <replaceable>form</replaceable></varname></term>
226        <listitem>
227          <para>Evaluates <replaceable>form</replaceable> whenever the function being traced is
228          about to be entered.  The form may reference the lexical variable
229          <varname>ccl::args</varname>, which is a list of the arguments in this call. The value
230          returned by <replaceable>form</replaceable> is intepreted as follows:
231          </para>
232
233          <variablelist>
234
235            <varlistentry>
236              <term><varname>nil</varname></term>
237              <listitem><para>does nothing</para></listitem>
238            </varlistentry>
239
240            <varlistentry>
241              <term><varname>:detailed</varname></term>
242              <listitem><para>prints a detailed backtrace to
243              <varname>*trace-output*</varname>.</para></listitem>
244            </varlistentry>
245
246            <varlistentry>
247              <term><varname>(:detailed <replaceable>integer</replaceable>)</varname></term>
248              <listitem><para>prints the top <replaceable>integer</replaceable> frames of detailed
249              backtrace to <varname>*trace-output*</varname>.
250              </para></listitem>
251            </varlistentry>
252
253            <varlistentry>
254              <term><replaceable>integer</replaceable></term>
255              <listitem><para>prints top <replaceable>integer</replaceable> frames of a terse
256              backtrace to <varname>*trace-output*</varname>.
257              </para></listitem>
258            </varlistentry>
259
260            <varlistentry>
261              <term>anything else</term>
262              <listitem><para>prints a terse backtrace to <varname>*trace-output*</varname>.
263              </para></listitem>
264            </varlistentry>
265          </variablelist>
266          <para>
267            Note that unlike with the other options, <varname>:backtrace</varname> is equivalent to
268            <varname>:backtrace-before</varname> only, not both before and after, since it's usually
269            not helpful to print the same backtrace both before and after the function call.
270          </para>
271        </listitem>
272      </varlistentry>
273
274      <varlistentry>
275        <term><varname>:backtrace-after <replaceable>form</replaceable></varname></term>
276        <listitem>
277          <para>Evaluates <replaceable>form</replaceable> whenever the function being traced has
278          just exited.  The form may reference the lexical variable <varname>ccl::vals</varname>,
279          which is a list of values returned by this call. The value returned by
280          <replaceable>form</replaceable> is intepreted as follows:
281          </para>
282
283          <variablelist>
284
285            <varlistentry>
286              <term><varname>nil</varname></term>
287              <listitem><para>does nothing</para></listitem>
288            </varlistentry>
289
290            <varlistentry>
291              <term><varname>:detailed</varname></term>
292              <listitem><para>prints a detailed backtrace to
293              <varname>*trace-output*</varname>.</para></listitem>
294            </varlistentry>
295
296            <varlistentry>
297              <term><varname>(:detailed <replaceable>integer</replaceable>)</varname></term>
298              <listitem><para>prints the top <replaceable>integer</replaceable> frames of detailed
299              backtrace to <varname>*trace-output*</varname>.
300              </para></listitem>
301            </varlistentry>
302
303            <varlistentry>
304              <term><replaceable>integer</replaceable></term>
305              <listitem><para>prints top <replaceable>integer</replaceable> frames of a terse
306              backtrace to <varname>*trace-output*</varname>.
307              </para></listitem>
308            </varlistentry>
309
310            <varlistentry>
311              <term>anything else</term>
312              <listitem><para>prints a terse backtrace to <varname>*trace-output*</varname>.
313              </para></listitem>
314            </varlistentry>
315          </variablelist>
316        </listitem>
317      </varlistentry>
318
319      <varlistentry>
320       <term><varname>:before</varname> <replaceable>action</replaceable></term>
321       <listitem>
322          <para>specifies the action to be taken just before the traced function is entered.  <replaceable>action</replaceable> is one of:</para>
323
324          <variablelist>
325            <varlistentry>
326              <term><varname>:print</varname></term>
327              <listitem>
328                <para>The default, prints a short indented message showing the function name and the invocation arguments</para>
329              </listitem>
330            </varlistentry>
331
332            <varlistentry>
333              <term><varname>:break</varname></term>
334              <listitem>
335                <para>Equivalent to <varname>:before :print :break-before t</varname></para>
336              </listitem>
337            </varlistentry>
338
339            <varlistentry>
340              <term><varname>:backtrace</varname></term>
341              <listitem>
342                <para>Equivalent to <varname>:before :print :backtrace-before t</varname></para>
343              </listitem>
344            </varlistentry>
345
346
347            <varlistentry>
348              <term><replaceable>function</replaceable></term>
349              <listitem>
350                <para>
351                  Any other value is interpreted as a function to call on entry instead of
352                  printing the standard entry message.  It is called with its first
353                  argument being the name of the function being traced, the remaining
354                  arguments being all the arguments to the function being traced, and
355                  <varname>ccl:*trace-level*</varname> bound to the current nesting level
356                  of trace actions. </para>
357              </listitem>
358            </varlistentry>
359          </variablelist>
360        </listitem>
361      </varlistentry>
362
363      <varlistentry>
364
365        <term><varname>:after</varname> <replaceable>action</replaceable></term>
366        <listitem>
367
368              <para>specifies the action to be taken just after the traced function exits.  <replaceable>action</replaceable> is one of:</para>
369
370              <variablelist>
371                <varlistentry>
372                  <term><varname>:print</varname></term>
373                  <listitem>
374                    <para>The default, prints a short indented message showing the function name and the
375                      returned values </para>
376                  </listitem>
377                </varlistentry>
378
379                <varlistentry>
380                  <term><varname>:break</varname></term>
381                  <listitem>
382                    <para>Equivalent to <varname>:after :print :break-after t</varname></para>
383                  </listitem>
384                </varlistentry>
385
386                <varlistentry>
387                  <term><varname>:backtrace</varname></term>
388                  <listitem>
389                    <para>Equivalent to <varname>:after :print :backtrace-after t</varname></para>
390                  </listitem>
391                </varlistentry>
392
393                <varlistentry>
394                  <term><replaceable>function</replaceable></term>
395                  <listitem>
396                    <para>Any other value is interpreted as a function to
397                      call on exit instead of printing the standard exit
398                      message.  It is called with its first argument being
399                      the name of the function being traced, the
400                      remaining arguments being all the values returned by the function
401                      being traced, and ccl:*trace-level* bound to the current
402                      nesting level of trace actions.
403                    </para>
404                  </listitem>
405                </varlistentry>
406              </variablelist>
407        </listitem>
408      </varlistentry>
409
410    </variablelist>
411
412
413    <para>
414      <indexterm zone="trace-level"/>
415      <command><varname id="trace-level">CCL:*TRACE-LEVEL*</varname>    [Variable]</command>
416    </para>
417
418    <para>Variable bound to the current nesting level during execution of before and after trace actions.  The default printing actions use it to determine the amount of indentation.</para>
419
420    <para>
421      <indexterm zone="trace-max-indent"/>
422      <command><varname id="trace-max-indent">CCL:*TRACE-MAX-INDENT*</varname>    [Variable]</command>
423    </para>
424
425    <para>The default before and after print actions will not indent by more than the value of <varname>ccl:*trace-max-indent*</varname> regardless of the current trace level.</para>
426
427    <para>
428      <indexterm zone="trace-function"/>
429      <command><varname id="trace-function">CCL:TRACE-FUNCTION</varname> <replaceable>spec</replaceable> &key; {<replaceable>keyword</replaceable> <replaceable>value</replaceable>}*    [Function]</command>
430    </para>
431     
432    <para>
433      This is a functional version of the TRACE macro.  <replaceable>spec</replaceable> and
434      <replaceable>keyword</replaceable>s are as for TRACE, except that all arguments are evaluated.
435    </para>
436
437    <para>
438      <indexterm zone="trace-print-level"/>
439      <command><varname id="trace-print-level">CCL:*TRACE-PRINT-LEVEL*</varname>   [Variable]</command>
440    </para>
441
442    <para>The default print actions bind <varname>CL:*PRINT-LEVEL*</varname> to this value while
443    printing. Note that this rebinding is only in effect during the default entry and exit messages.
444    It does not apply to printing of <varname>:print-before/:print-after</varname> forms or any
445    explicit printing done by user code.</para>
446
447    <para>
448      <indexterm zone="trace-print-length"/>
449      <command><varname id="trace-print-length">CCL:*TRACE-PRINT-LENGTH*</varname>    [Variable]</command>
450    </para>
451 
452    <para>The default print actions bind <varname>CL:*PRINT-LENGTH*</varname> to this value while
453    printing. Note that this rebinding is only in effect during the default entry and exit messages.
454    It does not apply to printing of <varname>:print-before/:print-after</varname> forms or any
455    explicit printing done by user code.</para>
456
457    <para>
458      <indexterm zone="trace-bar-frequency"/>
459      <command><varname id="trace-bar-frequency">CCL:*TRACE-BAR-FREQUENCY*</varname>    [Variable]</command>
460    </para>
461
462    <para>By default, this is nil. If non-nil it should be a integer, and the default entry and exit messages will print a | instead of space every this many levels of indentation.</para>
463
464
465  </sect1>
466
467  <sect1 id="Strings-and-Pathanmes"><title>Strings and Pathnames</title>
468    <sect2>
469      <title>OS X (Darwin)</title>
470
471      <para>Clozure CL assumes that pathname strings are decomposed UTF-8.</para>
472    </sect2>
473    <sect2>
474      <title>Linux</title>
475
476      <para>Pathname strings are treated as null-terminated strings
477        encoded according to the current locale.</para>
478    </sect2>
479    <sect2>
480      <title>FreeBSD</title>
481
482      <para>Pathname strings are treated as null-terminated strings
483        encoded according to the current locale; a future release may
484        change this convention to use UTF-8.</para>
485    </sect2>
486  </sect1>
487
488  <sect1 id="Memory-Mapped-Files">
489    <title>Memory-mapped Files</title>
490    <para>In release 1.2 and later, &CCL;
491      supports <glossterm linkend="memory_mapped_file">memory-mapped
492        files</glossterm>. On operating systems that support memory-mapped
493      files (including Mac OS X, Linux, and FreeBSD), the operating
494      system can arrange for a range of virtual memory addresses to
495      refer to the contents of an open file. As long as the file remains
496      open, programs can read values from the file by reading addresses
497      in the mapped range.</para>
498
499    <para>Using memory-mapped files may in some cases be more
500      efficient than reading the contents of a file into a data
501      structure in memory.</para>
502
503    <para>&CCL; provides the
504      functions <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
505      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> to support
506      memory-mapping. These functions return vectors whose contents are
507      the contents of memory-mapped files. Reading an element of such a
508      vector returns data from the correponding position in the
509      file.</para>
510
511    <para>Without memory-mapped files, a common idiom for reading the
512      contents of files might be something like this:</para>
513
514    <para><programlisting>
515(let* ((stream (open pathname :direction :input :element-type '(unsigned-byte 8)))
516       (vector (make-array (file-size-to-vector-size stream)
517                           :element-type '(unsigned-byte 8))))
518  (read-sequence vector stream))
519    </programlisting></para>
520
521    <para>Using a memory-mapped files has a result that is the same in
522      that, like the above example, it returns a vector whose contents are
523      the same as the contents of the file. It differs in that the above
524      example creates a new vector in memory and copies the file's
525      contents into it; using a memory-mapped file instead arranges for
526      the vector's elements to point to the file's contents on disk
527      directly, without copying them into memory first.</para>
528
529    <para>The vectors returned by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
530      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> are read-only; any
531      attempt to change an element of a vector returned by these
532      functions results in a memory-access error. &CCL; does not
533      currently support writing data to memory-mapped files.</para>
534
535    <para>Vectors created by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
536      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> are required to
537      respect &CCL;'s limit on the total size of an array. That means
538      that you cannot use these functions to create a vector longer
539      than <varname>ARRAY-TOTAL-SIZE-LIMIT</varname>, even if the filesystem
540      supports file sizes that are larger. The value
541      of <varname>ARRAY-TOTAL-SIZE-LIMIT</varname> is <varname>(EXPT 2 24)</varname>
542      on 32-but platforms; and <varname>(EXPT 2 56)</varname> on 64-bit
543      platforms.</para>
544
545    <para>
546      <indexterm zone="map-file-to-ivector"/>
547      <command><varname id="map-file-to-ivector">CCL:MAP-FILE-TO-IVECTOR</varname>
548        <parameter>pathname</parameter>
549        <parameter>element-type</parameter>
550        [Function]</command>
551    </para>
552
553    <variablelist>
554      <varlistentry>
555        <term><varname>pathname</varname></term>
556        <listitem>
557          <para>The pathname of the file to be memory-mapped.</para>
558        </listitem>
559      </varlistentry>
560     
561      <varlistentry>
562        <term><varname>element-type</varname></term>
563        <listitem>
564          <para>The element-type of the vector to be
565            created. Specified as
566            a <glossterm linkend="type-specifier">type-specifier</glossterm>
567            that names a subtype of either <varname>SIGNED-BYTE</varname>
568            or <varname>UNSIGNED-BYTE</varname>.</para>
569        </listitem>
570      </varlistentry>
571    </variablelist>
572
573
574    <para>
575      The <varname>map-file-to-ivector</varname> function tries to
576      open the file at <parameter>pathname</parameter> for reading. If
577      successful, the function maps the file's contents to a range of
578      virtual addresses. If successful, it returns a read-only vector
579      whose element-type is given
580      by <parameter>element-type</parameter>, and whose contents are
581      the contents of the memory-mapped file.
582    </para>
583
584    <para>The returned vector is
585      a <glossterm linkend="displaced-array">displaced-array</glossterm>
586      whose element-type is <varname>(UPGRADED-ARRAY-ELEMENT-TYPE
587        element-type)</varname>. The target of the displaced array is a
588      vector of type <varname>(SIMPLE-ARRAY element-type (*))</varname> whose
589      elements are the contents of the memory-mapped file.</para>
590
591    <para>Because of alignment issues, the mapped file's contents
592      start a few bytes (4 bytes on 32-bit platforms, 8 bytes on
593      64-bit platforms) into the vector. The displaced array returned
594      by <varname>CCL:MAP-FILE-TO-IVECTOR</varname> hides this overhead, but
595      it's usually more efficient to operate on the underlying simple
596      1-dimensional array.  Given a displaced array (like the value
597      returned by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>), the function
598      <varname>ARRAY-DISPLACEMENT</varname> returns the underlying array and
599      the displacement index in elements.
600    </para>
601
602    <para>Currently, &CCL; supports only read operations on
603      memory-mapped files. If you try to change the contents of an array
604      returned by <varname>map-file-to-ivector</varname>, &CCL; signals
605      a memory error.</para>
606
607    <para>
608      <indexterm zone="unmap-ivector"/>
609      <command><varname id="unmap-ivector">CCL:UNMAP-IVECTOR</varname>
610        <parameter>displaced-array</parameter>
611        [Function]</command>
612    </para>
613
614    <para>If the argument is a displaced-array returned
615      by <varname>map-file-to-ivector</varname>, and if it has not yet
616      been unmapped by this function,
617      then <varname>unmap-ivector</varname> undoes the memory mapping,
618      closes the mapped file, and changes the displaced-array so that its
619      target is an empty vector (of length zero).</para>
620
621    <para>
622      <indexterm zone="map-file-to-octet-vector"/>
623      <command><varname id="map-file-to-octet-vector">CCL:MAP-FILE-TO-OCTET-VECTOR</varname>
624        <parameter>pathname</parameter>
625        [Function]</command>
626    </para>
627
628    <para>This function is a synonym for <varname>(CCL:MAP-FILE-TO-IVECTOR
629        pathname '(UNSIGNED-BYTE 8))</varname> It is provided as a convenience
630      for the common case of memory-mapping a file as a vector of
631      bytes.</para>
632
633    <para>
634      <indexterm zone="unmap-octet-vector"/>
635      <command><varname id="unmap-octet-vector">CCL:UNMAP-OCTET-VECTOR</varname>
636        <parameter>displaced-array</parameter>
637        [Function]</command>
638    </para>
639
640    <para>This function is a synonym
641      for <varname>(CCL:UNMAP-IVECTOR)</varname></para>
642  </sect1>
643
644  <sect1 id="Static_Variables">
645    <title>Static Variables</title>
646
647    <para>&CCL; supports the definition
648    of <glossterm linkend="static_variable">static
649    variables</glossterm>, whose values are the same across threads,
650    and which may not be dynamically bound. The value of a static
651    variable is thus the same across all threads; changing the value
652    in one thread changes it for all threads.</para> 
653
654    <para>Attempting to dynamically rebind a static variable (for
655    instance, by using <varname>LET</varname>, or using the variable name as
656    a parameter in a <varname>LAMBDA</varname> form) signals an
657    error. Static variables are shared global resources; a dynamic
658    binding is private to a single thread.</para>
659
660    <para>Static variables therefore provide a simple way to share
661    mutable state across threads. They also provide a simple way to
662    introduce race conditions and obscure bugs into your code, since
663    every thread reads and writes the same instance of a given static
664    variable. You must take care, therefore, in how you change the
665    values of static variables, and use normal multithreaded
666    programming techniques, such as locks or sempahores, to protect
667    against race conditions.</para>
668
669    <para>In &CCL;, access to a static variable is usually faster than
670    access to a special variable that has not been declared
671    static.</para>
672
673    <para>
674      <indexterm zone="defstatic"/>
675      <command><varname id="defstatic">DEFSTATIC</varname>
676        <parameter>var</parameter>
677        <parameter>value</parameter>
678        &key;
679        <parameter>doc-string</parameter>
680        [Macro]</command>
681    </para>
682   
683    <variablelist>
684      <varlistentry>
685        <term><varname>var</varname></term>
686        <listitem>
687          <para>The name of the new static variable.</para>
688        </listitem>
689      </varlistentry>
690     
691      <varlistentry>
692        <term><varname>value</varname></term>
693        <listitem>
694          <para>The initial value of the new static variable.</para>
695        </listitem>
696      </varlistentry>
697     
698      <varlistentry>
699        <term><varname>doc-string</varname></term>
700        <listitem>
701          <para>A documentation string that is assigned to the new
702          variable.</para>
703        </listitem>
704      </varlistentry>
705    </variablelist>
706
707    <para>Proclaims the
708      variable <glossterm linkend="special_variable">special</glossterm>,
709      assigns the variable the supplied value, and assigns
710      the <varname>doc-string</varname> to the
711      variable's <varname>VARIABLE</varname> documentation. Marks the
712      variable static, preventing any attempt to dynamically rebind
713      it. Any attempt to dynamically rebind <varname>var</varname>
714      signals an error.</para>
715  </sect1>
716
717</chapter>
Note: See TracBrowser for help on using the repository browser.