Changeset 8903


Ignore:
Timestamp:
Mar 27, 2008, 9:14:27 PM (11 years ago)
Author:
mikel
Message:

added discussion of support for foreign types as classes

File:
1 edited

Legend:

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

    r8896 r8903  
    5353          account, and neither do <code>DESCRIBE</code>
    5454          and <code>INSPECT</code>.</para>
     55      </sect3>
     56
     57      <sect3 id="foreign-type-classes">
     58        <title>Foreign Types as Classes</title>
     59        <para>Some types of foreign pointers take advantage of the
     60          support for type annotations, and pointers of these types
     61          can be treated as instances of known classes. Specifically,
     62          a pointer to an <code>:&lt;NSR&gt;ect</code> is recognized
     63          as an instance of the built-in
     64          class <code>NS:NS-RECT</code>, a pointer to
     65          an <code>&lt;NSS&gt;ize</code> is treated as an instance
     66          of <code>NS:NS-SIZE</code>, a pointer to
     67          an <code>&lt;NSP&gt;oint</code> is recognized as an
     68          instsance of <code>NS:NS-POINT</code>, and a pointer to
     69          an <code>&lt;NSR&gt;ange</code> is recognized as an
     70          instance of <code>NS:NS-RANGE</code>.</para>
     71
     72        <para>A few more obscure structure types also support this
     73        mechanism, and it's possible that a future version will
     74        support user definition of similar type mappings.</para>
     75
     76        <para>This support for foreign types as classes provides the
     77        following conveniences for each supported type:</para>
     78
     79      <itemizedlist>
     80        <listitem>
     81          <para>a <code>PRINT-OBJECT</code> method is defined</para>
     82        </listitem>
     83        <listitem>
     84          <para>a foreign type name is created and treated as an alias
     85          for the corresponding type. As an example, the
     86          name <code>:NS-RECT</code> is a name for the type that
     87          corresponds to <code>NS:NS-RECT</code>, and you can
     88          use <code>:NS-RECT</code> as a type designator
     89          in <link linkend="anchor_rlet"><code>RLET</code></link> forms to
     90          specify a structure of type <code>NS-RECT</code>.</para>
     91        </listitem>
     92        <listitem>
     93          <para>the class is integrated into the type system so that
     94            <code>(TYPEP R 'NS:NS-RECT)</code> is implemented with
     95            fair efficiency.</para>
     96        </listitem>
     97        <listitem>
     98          <para>inlined accessor and <code>SETF</code> inverses are
     99            defined for the structure type's fields.  In the case of
     100            an <code>&lt;NSR*gt;ect</code>, for example, the fields in
     101            question are the fields of the embedded point and size, so
     102            that <code>NS:NS-RECT-X</code>, <code>NS:NS-RECT-Y</code>, <code>NS:NS-RECT-WIDTH</code>,
     103            <code>NS-RECT-HEIGHT</code> and <code>SETF</code> inverses
     104            are defined.  The accessors and setter functions typecheck
     105            their arguments and the setters handle coercion to the
     106            approprate type of <code>CGFLOAT</code> where
     107            applicable.</para>
     108        </listitem>
     109        <listitem>
     110          <para>an initialization function is defined; for
     111            example,</para>
     112
     113          <programlisting>
     114(NS:INIT-NS-SIZE s w h)
     115          </programlisting>
     116
     117          <para>is roughly equivalent to</para>
     118
     119          <programlisting>
     120(SETF (NS:NS-SIZE-WIDTH s) w
     121      (NS:NS-SIZE-HEIGHT s) h)
     122          </programlisting>
     123
     124          <para>but might be a little more efficient.</para>
     125        </listitem>
     126        <listitem>
     127          <para>a creation function is defined; for
     128            example</para>
     129
     130          <programlisting>
     131(NS:NS-MAKE-POINT x y)
     132          </programlisting>
     133
     134          <para>is functionally equivalent to</para>
     135
     136          <programlisting>
     137(LET ((P (MAKE-GCABLE-RECORD :NS-POINT)))
     138  (NS:INIT-NS-POINT P X Y)
     139  p)
     140          </programlisting>
     141
     142        </listitem>
     143        <listitem>
     144          <para>a macro is defined which, like <code>RLET</code>,
     145            stack-allocates an instance of the foreign record type,
     146            optionally iniitializes that instance, and executes a body
     147            of code with a variable bound to that instance.</para>
     148
     149          <para>For example,</para>
     150          <programlisting>
     151(ns:with-ns-range (r loc len)
     152  (format t "~&amp; range has location ~s, length ~s"
     153     (ns:ns-range-location r) (ns:ns-range-length r)))
     154          </programlisting>
     155        </listitem>
     156        <listitem>
     157          <para></para>
     158        </listitem>
     159      </itemizedlist>
    55160      </sect3>
    56161
     
    40774182
    40784183    <!-- ====================================  -->
     4184    <anchor id="anchor_rlet"/>
    40794185    <refentry id="m_rlet">
    40804186          <indexterm zone="m_rlet">
Note: See TracChangeset for help on using the changeset viewer.