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

Last change on this file since 8703 was 8703, checked in by mikel, 12 years ago

added discussion of type annotations; minor edits

File size: 15.9 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      <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>
149  </sect1>
150
151  <sect1 id="Strings-and-Pathanmes"><title>Strings and Pathnames</title>
152    <sect2>
153      <title>OS X (Darwin)</title>
154
155      <para>Clozure CL assumes that pathname strings are decomposed UTF-8.</para>
156    </sect2>
157    <sect2>
158      <title>Linux</title>
159
160      <para>Pathname strings are treated as null-terminated strings
161        encoded according to the current locale.</para>
162    </sect2>
163    <sect2>
164      <title>FreeBSD</title>
165
166      <para>Pathname strings are treated as null-terminated strings
167        encoded according to the current locale; a future release may
168        change this convention to use UTF-8.</para>
169    </sect2>
170  </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  <sect1 id="Static Variables">
325    <title>Static Variables</title>
326
327    <para>&CCL; supports the definition
328    of <glossterm linkend="static_variable">static
329    variables</glossterm>, whose values are the same across threads,
330    and which may not be dynamically bound. The value of a static
331    variable is thus the same across all threads; changing the value
332    in one thread changes it for all threads.</para> 
333
334    <para>Attempting to dynamically rebind a static variable (for
335    instance, by using <code>LET</code>, or using the variable name as
336    a parameter in a <code>LAMBDA</code> form) signals an
337    error. Static variables are shared global resources; a dynamic
338    binding is private to a single thread.</para>
339
340    <para>Static variables therefore provide a simple way to share
341    mutable state across threads. They also provide a simple way to
342    introduce race conditions and obscure bugs into your code, since
343    every thread reads and writes the same instance of a given static
344    variable. You must take care, therefore, in how you change the
345    values of static variables, and use normal multithreaded
346    programming techniques, such as locks or sempahores, to protect
347    against race conditions.</para>
348
349    <para>In &CCL;, access to a static variable is usually faster than
350    access to a special variable that has not been declared
351    static.</para>
352
353    <para>
354      <command><varname>DEFSTATIC</varname>
355        <parameter>var</parameter>
356        <parameter>value</parameter>
357        <varname>&key;</varname>
358        <parameter>doc-string</parameter>
359        [Macro]</command>
360    </para>
361   
362    <variablelist>
363      <varlistentry>
364        <term><varname>var</varname></term>
365        <listitem>
366          <para>The name of the new static variable.</para>
367        </listitem>
368      </varlistentry>
369     
370      <varlistentry>
371        <term><varname>value</varname></term>
372        <listitem>
373          <para>The initial value of the new static variable.</para>
374        </listitem>
375      </varlistentry>
376     
377      <varlistentry>
378        <term><varname>doc-string</varname></term>
379        <listitem>
380          <para>A documentation string that is assigned to the new
381          variable.</para>
382        </listitem>
383      </varlistentry>
384    </variablelist>
385
386    <para>Proclaims the
387      variable <glossterm linkend="special_variable">special</glossterm>,
388      assigns the variable the supplied value, and assigns
389      the <varname>doc-string</varname> to the
390      variable's <code>VARIABLE</code> documentation. Marks the
391      variable static, preventing any attempt to dynamically rebind
392      it. Any attempt to dynamically rebind <varname>var</varname>
393      signals an error.</para>
394  </sect1>
395
396</chapter>
Note: See TracBrowser for help on using the repository browser.