Changeset 8703


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

added discussion of type annotations; minor edits

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

Legend:

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

    r8673 r8703  
    1919      <title>Overview</title>
    2020      <para>&CCL; provides a fairly rich language for defining and
    21       specifying foreign data types (this language is derived from
    22       CMUCL's "alien type" system.)</para>
     21        specifying foreign data types (this language is derived from
     22        CMUCL's "alien type" system.)</para>
    2323      <para>In practice, most foreign type definitions are
    24       introduced into &CCL; via its interface database (see ),
    25       though it's also possible to define foreign types
    26       interactively and/or programmatically.</para>
     24        introduced into &CCL; via its interface database (see ),
     25        though it's also possible to define foreign types
     26        interactively and/or programmatically.</para>
    2727      <para>&CCL;'s foreign type system is "evolving" (a polite word
    28       for not-quite-complete): there are some inconsistencies
    29       involving package usage, for instance. Symbols used in foreign
    30       type specifiers <emphasis>should</emphasis> be keywords, but
    31       this convention isn't always enforced.</para> <para>Foreign
    32       type, record, and field names are case-sensitive; &CCL; uses
    33       some escaping conventions (see ) to allow keywords to be used to
    34       denote these names.</para>
    35       </sect2>
     28        for not-quite-complete): there are some inconsistencies
     29        involving package usage, for instance. Symbols used in foreign
     30        type specifiers <emphasis>should</emphasis> be keywords, but
     31        this convention isn't always enforced.</para> <para>Foreign
     32        type, record, and field names are case-sensitive; &CCL; uses
     33        some escaping conventions (see ) to allow keywords to be used to
     34        denote these names.</para>
     35
     36      <sect3 id="type annotations">
     37        <title>Type Annotations</title>
     38        <para>As of version 1.2, &CCL; supports annotating the types of
     39          foreign pointers on Mac OS X. Forms that create pointers to
     40          foreign memory&mdash;that is, <code>MACPTR</code>s&mdash;store
     41          with the <code>MACPTR</code> object a type annotation that
     42          identifies the foreign type of the object pointed
     43          to. Calling <code>PRINT-OBJECT</code> on a <code>MACPTR</code>
     44          attempts to print information about the identified foreign
     45          type, including whether it was allocated on the heap or the
     46          stack, and whether it's scheduled for automatic reclamation by
     47          the garbage collector.</para>
     48
     49        <para>Support for type annotation is not yet complete. In
     50          particular, some uses of <code>PREF</code>
     51          and <code>SLOT-VALUE</code> do ot yet take type annotations into
     52          account, and neither do <code>DESCRIBE</code>
     53          and <code>INSPECT</code>.</para>
     54      </sect3>
     55
     56    </sect2>
    3657
    3758      <sect2 id="Syntax-of-Foreign-Type-Specifiers">
  • trunk/source/doc/src/glossary.xml

    r8702 r8703  
    245245        </glossentry>
    246246   
     247        <glossentry id="special_variable">
     248          <glossterm>special variable</glossterm>
     249
     250          <glossdef>
     251
     252                <para>A variable whose binding is in the dynamic
     253                environment. Special variables are essentally equivalent to
     254                global variables in languages other than Lisp. A special
     255                variable binding is visible in any lexical environment, so
     256                long as a lexical binding has not shadowed it.</para>
     257
     258          </glossdef>
     259
     260        </glossentry>
     261   
     262        <glossentry id="static_variable">
     263          <glossterm>static variable</glossterm>
     264
     265          <glossdef>
     266
     267                <para>In &CCL;, a variable whose value is shared across all
     268                threads, and which may not be dynamically rebound. Changing a
     269                static variable's value in one thread causes all threads to
     270                see the new value. Attempting to dynamically rebind the
     271                variable (for instance, by using <code>LET</code>, or using
     272                the variable name as a parameter in a <code>LAMBDA</code>
     273                form) signals an error.</para>
     274
     275          </glossdef>
     276
     277        </glossentry>
     278   
    247279  </glossdiv>
    248280
  • trunk/source/doc/src/ide.xml

    r8695 r8703  
    214214
    215215    <para>
    216       <command><varname>BUILD-APPLICATION</varname> <varname>&amp;key</varname>
     216      <command><varname>BUILD-APPLICATION</varname> <varname>&key;</varname>
    217217        (<parameter>name</parameter> <replaceable>"MyApplication"</replaceable>)
    218218        (<parameter>type-string</parameter> <replaceable>"APPL"</replaceable>)
  • trunk/source/doc/src/using.xml

    r8702 r8703  
    170170  </sect1>
    171171
    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>
     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>
    237237      <varlistentry>
    238238        <term><varname>pathname</varname></term>
     
    241241        </listitem>
    242242      </varlistentry>
    243    
     243     
    244244      <varlistentry>
    245245        <term><varname>element-type</varname></term>
    246246        <listitem>
    247247          <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>
     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>
    255255
    256256
     
    266266
    267267    <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>
     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>
    273273
    274274    <para>Because of alignment issues, the mapped file's contents
     
    284284
    285285    <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 
     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>
    324395
    325396</chapter>
Note: See TracChangeset for help on using the changeset viewer.