doc/notes.xml

   1 <?xml version='1.0' ?>   <!-- Mode: Docbook -->
   2
   3 <chapter>
   4   <title>Programming Notes</title>
   5
   6   <sect1>
   7     <title>Implementation Specific Notes</title>
   8     <para>
   9     </para>
  10       <sect2>
  11         <title>&acl;</title>
  12         <para>
  13         </para>
  14       </sect2>
  15       <sect2>
  16         <title>&lw;</title>
  17         <para>
  18         </para>
  19       </sect2>
  20       <sect2>
  21         <title>&cmucl;</title>
  22         <para>
  23         </para>
  24       </sect2>
  25   </sect1>
  26
  27   <sect1>
  28     <title>Foreign Object Representation and Access</title>
  29     <para> There are two main approaches used to represent foreign
  30     objects: an integer that represents an address in memory, and a
  31     object that also includes run-time typing. The advantage of
  32     run-time typing is the system can dereference pointers and perform
  33     array access without those functions requiring a type at the cost
  34     of additional overhead to generate and store the run-time
  35     typing. The advantage of integer representation, at least for
  36     &acl;, is that the compiler can generate inline code to
  37     dereference pointers. Further, the overhead of the run-time type
  38     information is eliminated. The disadvantage is the program must
  39     then supply
  40     the type to the functions to dereference objects and array.
  41     </para>
  42   </sect1>
  43
  44   <sect1>
  45     <title>Optimizing Code Using UFFI</title>
  46     <sect2>
  47       <title>Background</title>
  48       <para>
  49         Two implementions have different techniques to optimize
  50         (open-code) foreign objects. &acl; can open-code foreign
  51         object
  52         access if pointers are integers and the type of object is
  53     specified in the access function.  Thus, &uffi; represents objects
  54     in &acl; as integers which don't have type information.
  55     </para> <para>
  56       &cmucl; works best when keeping objects as typed
  57     objects. However, it's compiler can open-code object access when
  58     the object type is specified in <function>declare</function>
  59     commands and in <varname>:type</varname> specifiers in
  60     <function>defstruct</function> and <function>defclass</function>.
  61     </para> <para> &lw;, in converse to &acl; and &cmucl; does not do
  62     any open coding of object access. &lw;, by default, maintains
  63     objects with run-time typing.  </para>
  64     </sect2>
  65     <sect2>
  66       <title>Cross-Implementation Optimization</title>
  67       <para>
  68         To fully optimize across platforms, both explicit type
  69         information must be passed to dereferencing of pointers and
  70         arrays. Though this optimization only helps with &acl;, &uffi;
  71         is designed to require this type information be passed the
  72         dereference functions. Second, declarations of type should be
  73         made in functions, structures, and classes where foreign
  74         objects will be help. This will optimize access for &lw;
  75       </para>
  76       <para>
  77         Here is an example that should both methods being used for
  78         maximum cross-implementation optimization:
  79         <programlisting>
  80 (uffi:def-type the-struct-type-def the-struct-type)
  81 (let ((a-foreign-struct (allocate-foreign-object 'the-struct-type)))
  82   (declare 'the-struct-type-def a-foreign-struct)
  83   (get-slot-value a-foreign-struct 'the-struct-type 'field-name))
  84         </programlisting>
  85       </para>
  86     </sect2>
  87   </sect1>
  88
  89 </chapter>