Changeset 8663


Ignore:
Timestamp:
Mar 5, 2008, 7:19:47 PM (12 years ago)
Author:
mikel
Message:

added and extended discussion of 1.2 reader macros to ff.xml

File:
1 edited

Legend:

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

    r8659 r8663  
    1010]>
    1111
    12   <chapter id="The-Foreign-Function-Interface">
    13     <title>The Foreign-Function Interface</title>
    14 
    15     <sect1 id="Specifying-And-Using-Foreign-Types">
    16       <title>Specifying And Using Foreign Types</title>
    17 
    18       <sect2 id="Overview-foreign-types">
    19         <title>Overview</title>
    20         <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>
    23         <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>
    27         <para>&CCL;'s foreign type system is "evolving" (a polite
    28         word 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>
    32         <para>Foreign type, record, and field names are
    33         case-sensitive; &CCL; uses some escaping conventions (see )
    34         to allow keywords to be used to denote these names.</para>
     12<chapter id="The-Foreign-Function-Interface">
     13  <title>The Foreign-Function Interface</title>
     14 
     15  <sect1 id="Specifying-And-Using-Foreign-Types">
     16    <title>Specifying And Using Foreign Types</title>
     17   
     18    <sect2 id="Overview-foreign-types">
     19      <title>Overview</title>
     20      <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>
     23      <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>
     27      <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>
    3535      </sect2>
    3636
     
    3939        <itemizedlist>
    4040          <listitem>
    41             <para>Some foreign types are builtin: keywords denote
    42             primitive,builtin types such as the IEEE-double-float type
    43             (denoted:DOUBLE-FLOAT), in much the same way as certain
    44             symbols(CONS, FIXNUM,etc.) define primitive CL
    45             types.</para>
    46           </listitem>
     41            <para>Some foreign types are builtin: keywords denote
     42            primitive,builtin types such as the IEEE-double-float type
     43            (denoted:DOUBLE-FLOAT), in much the same way as certain
     44            symbols(CONS, FIXNUM,etc.) define primitive CL
     45            types.</para>
     46          </listitem>
    4747          <listitem>
    48             <para>Constructors such as :SIGNED and :UNSIGNED can be
    49             used to denotesigned and unsigned integer subtypes
    50             (analogous to the CL typespecifiers SIGNED-BYTE and
    51             UNSIGNED-BYTE.) :SIGNED is shorthand for(:SIGNED 32) and
    52             :UNSIGNED is shorthand for (:UNSIGNED 32).</para>
    53           </listitem>
     48            <para>Constructors such as :SIGNED and :UNSIGNED can be
     49            used to denotesigned and unsigned integer subtypes
     50            (analogous to the CL typespecifiers SIGNED-BYTE and
     51            UNSIGNED-BYTE.) :SIGNED is shorthand for(:SIGNED 32) and
     52            :UNSIGNED is shorthand for (:UNSIGNED 32).</para>
     53          </listitem>
    5454          <listitem>
    55             <para>Aliases for other (perhaps more complicated) types
    56             can bedefined via CCL:DEF-FOREIGN-TYPE (sort of like
    57             CL:DEFTYPE or the Ctypedef facility). The type :CHAR is
    58             defined as an alias for (:SIGNED8) on some platforms, as
    59             (:UNSIGNED 8) on others.</para>
     55            <para>Aliases for other (perhaps more complicated) types
     56            can bedefined via CCL:DEF-FOREIGN-TYPE (sort of like
     57            CL:DEFTYPE or the Ctypedef facility). The type :CHAR is
     58            defined as an alias for (:SIGNED8) on some platforms, as
     59            (:UNSIGNED 8) on others.</para>
    6060          </listitem>
    6161          <listitem>
     
    13501350        <para>As one might assume, the database files in each of these
    13511351        subdirectories contain foreign type, constant, and function
    1352         definitions - as well as ObjC class and method info -that
     1352        definitions - as well as Objective-C class and method info -that
    13531353        correspond (roughly) to the information contained in the
    13541354        header files associated with a "-dev" package in a Linux
     
    17761776</programlisting>
    17771777      </sect2>
     1778    </sect1>
     1779
     1780    <sect1 id="Reading-Foreign-Names">
     1781      <title>Reading Foreign Names</title> <para>Clozure Common Lisp
     1782      provides several reader macros to make it more convenient to
     1783      handle foreign type, function, variable, and constant
     1784      names. Each of these reader macros reads symbols preserving the
     1785      case of the source text, and selects an appropriate package in
     1786      which to intern the resulting symbol. These reader macros are
     1787      especially useful when your Lisp code interacts extensively with
     1788      a foreign library&mdash;for example, when using Mac OS X's Cocoa
     1789      frameworks.</para>
     1790
     1791      <para>These reader macros include "#_" to read foreign function
     1792      names, "#&amp;" to read foreign variable names (note that in
     1793      earlier versions of OpenMCL the reader macro "#?" was used for
     1794      this same purpose), "#$" to read foreign constant names, "#/" to
     1795      read the names of foreign Objective-C methods, and "#>" to read
     1796      keywords that can be used as the names of types, records, and
     1797      accessors.</para>
     1798
     1799      <para>All of these reader macros preserve the case of the text
     1800      that they read; beyond that similarity, each performs some
     1801      additional work, unique to each reader macro, to create symbols
     1802      suitable for a particular use. For example, the function,
     1803      variable, and constant reader macros intern the resulting symbol
     1804      in the "OS" package of the running platform, but the reader
     1805      macro for Objective-C method names interns symbols in the
     1806      "NEXTSTEP-FUNCTIONS" package.</para>
     1807
     1808      <para>You are likely to see these reader macros used extensively
     1809      in Lisp code that works with foreign libraries; for example,
     1810      Clozure CL IDE code, which defines numerous Objective-C classes
     1811      and methods, uses these reader macros extensively.</para>
     1812
     1813      <para>For more detailed descriptions of each of these reader
     1814      macros, see the Foreign-Function-Interface Dictionary
     1815      section.</para>
    17781816    </sect1>
    17791817
     
    35533591      </refentry>
    35543592
    3555       <refentry id="rm_sharpsign-underscore">
    3556         <indexterm zone="rm_sharpsign-underscore">
    3557           <primary>#_</primary>
    3558         </indexterm>
    3559 
    3560         <refnamediv>
    3561           <refname>#_</refname>
    3562           <refpurpose></refpurpose>
    3563           <refclass>Reader Macro</refclass>
    3564         </refnamediv>
    3565 
    3566         <refsect1>
    3567           <title>Description</title>
    3568 
    3569           <para>Reads a symbol from the current input stream, with *PACKAGE*
     3593
     3594<refentry id="rm_sharpsign-underscore">
     3595  <indexterm zone="rm_sharpsign-underscore">
     3596        <primary>#_</primary>
     3597  </indexterm>
     3598
     3599  <refnamediv>
     3600        <refname>#_</refname>
     3601        <refpurpose></refpurpose>
     3602        <refclass>Reader Macro</refclass>
     3603  </refnamediv>
     3604
     3605  <refsect1>
     3606        <title>Description</title>
     3607
     3608        <para>Reads a symbol from the current input stream, with *PACKAGE*
    35703609          bound to the &#34;OS&#34; package and with readtable-case preserved.</para>
    3571          
    3572           <para>Does a lookup on that symbol in <link
    3573           linkend="The-Interface-Database">the &CCL; interface
    3574           database</link>, signalling an error if no foreign function
     3610       
     3611        <para>Does a lookup on that symbol in <link
     3612                                                 linkend="The-Interface-Database">the &CCL; interface
     3613            database</link>, signalling an error if no foreign function
    35753614          information can be found for the symbol in any active <link
    3576           linkend="Using-Interface-Directories">interface
    3577           directory</link>.</para>
    3578 
    3579           <para>Notes the foreign function information, including the foreign
     3615                                                                   linkend="Using-Interface-Directories">interface
     3616            directory</link>.</para>
     3617
     3618        <para>Notes the foreign function information, including the foreign
    35803619          function&#39;s return type, the number and type of the foreign
    35813620          function&#39;s required arguments, and an indication of whether or
     
    35833622          &#34;varargs&#34; mechanism in C).</para>
    35843623
    3585           <para>Defines a macroexpansion function on the symbol, which expand
     3624        <para>Defines a macroexpansion function on the symbol, which expand
    35863625          macro calls involving the symbol into EXTERNAL-CALL forms where
    35873626          foreign argument type specifiers for required arguments and the
    3588           return value specifer are provided from the information ind the
     3627          return value specifer are provided from the information in the
    35893628          database.</para>
    35903629
    3591           <para>Returns the symbol.</para>
    3592 
    3593           <para>The effect of these steps is that it&#39;s possible to call
     3630        <para>Returns the symbol.</para>
     3631
     3632        <para>The effect of these steps is that it&#39;s possible to call
    35943633          foreign functions that take fixed numbers of arguments by simply
    35953634          providing argument values, as in:</para>
    35963635
    3597           <programlisting format="linespecific">(#_isatty fd)
    3598 (#_read fd buf n)</programlisting>
    3599 
    3600           <para>and to call foreign functions that take variable numbers of
     3636        <programlisting format="linespecific">(#_isatty fd)
     3637      (#_read fd buf n)</programlisting>
     3638
     3639        <para>and to call foreign functions that take variable numbers of
    36013640          arguments by specifying the types of non-required args, as in:</para>
    36023641
    3603           <programlisting format="linespecific">(with-cstrs ((format-string &#34;the answer is: %d&#34;))
    3604   (#_printf format-string :int answer))</programlisting>
    3605         </refsect1>
    3606       </refentry>
    3607 
    3608       <refentry id="rm_sharpsign-questionmark">
    3609         <indexterm zone="rm_sharpsign-questionmark">
    3610           <primary>#?</primary>
    3611         </indexterm>
    3612 
    3613         <refnamediv>
    3614           <refname>#?</refname>
    3615           <refpurpose></refpurpose>
    3616           <refclass>Reader Macro</refclass>
    3617         </refnamediv>
    3618 
    3619         <refsect1>
    3620           <title>Description</title>
    3621 
    3622           <para>In &CCL; 0.14.2 and later, the #? reader macro can be used to
     3642        <programlisting format="linespecific">(with-cstrs ((format-string &#34;the answer is: %d&#34;))
     3643      (#_printf format-string :int answer))</programlisting>
     3644
     3645    <para>You can query whether a given name is defined in the
     3646      interface databases by appending the '?' character to the reader
     3647      macro; for example:</para>
     3648
     3649    <programlisting>
     3650      CL-USER&gt; #_?printf
     3651      T
     3652      CL-USER&gt; #_?foo
     3653      NIL
     3654    </programlisting>
     3655
     3656  </refsect1>
     3657</refentry>
     3658
     3659<refentry id="rm_sharpsign-ampersand">
     3660  <indexterm zone="rm_sharpsign-ampersand">
     3661        <primary>#&amp;</primary>
     3662  </indexterm>
     3663
     3664  <refnamediv>
     3665        <refname>#&amp;</refname>
     3666        <refpurpose></refpurpose>
     3667        <refclass>Reader Macro</refclass>
     3668  </refnamediv>
     3669
     3670  <refsect1>
     3671        <title>Description</title>
     3672
     3673        <para>In &CCL; 1.2 and later, the #&amp; reader macro can be used to
    36233674          access foreign variables; this functionality depends on the presence of
    36243675          &#34;vars.cdb&#34; files in the interface database. The current behavior
    3625           of the #? reader macro is to:</para>
    3626 
    3627           <para>Read a symbol from the current input stream, with *PACKAGE*
     3676          of the #&amp; reader macro is to:</para>
     3677
     3678        <para>Read a symbol from the current input stream, with *PACKAGE*
    36283679          bound to the &#34;OS&#34; package and with readtable-case preserved.</para>
    3629          
    3630           <para>Use that symbol&#39;s pname to access the &CCL; interface
     3680       
     3681        <para>Use that symbol&#39;s pname to access the &CCL; interface
    36313682          database, signalling an error if no appropriate foreign variable
    36323683          information can be found with that name in any active interface
    36333684          directory.</para>
    36343685
    3635           <para>Use type information recorded in the database to construct a
     3686        <para>Use type information recorded in the database to construct a
    36363687          form which can be used to access the foreign variable, and return
    36373688          that form.</para>
    36383689
    3639           <para>Please note that the set of foreign variables declared in header files
     3690        <para>Please note that the set of foreign variables declared in header files
    36403691          may or may not match the set of foreign variables exported from
    36413692          libraries (we&#39;re generally talking about C and Unix here ...). When
    3642           they do match, the form constructed by the #? reader macro manages the
     3693          they do match, the form constructed by the #&amp; reader macro manages the
    36433694          details of resolving and tracking changes to the foreign variable&#39;s
    36443695          address.</para>
    36453696
    3646           <para>Future extensions (via prefix arguments to the reader macro) may
     3697        <para>Future extensions (via prefix arguments to the reader macro) may
    36473698          offer additional behavior; it might be convenient (for instance) to be
    36483699          able to access the address of a foreign variable without dereferencing
    36493700          that address.</para>
    36503701
    3651           <para>Foreign variables in C code tend to be platform- and
     3702        <para>Foreign variables in C code tend to be platform- and
    36523703          packge-specific (the canonical example - &#34;errno&#34; - is typically
    36533704          not a variable when threads are involved. )</para>
    36543705
    3655           <para>In LinuxPPC, </para>
    3656 
    3657           <programlisting>? #?stderr</programlisting>
    3658 
    3659           <para>returns a pointer to the stdio error stream (&#34;stderr&#34; is a
     3706        <para>In LinuxPPC, </para>
     3707
     3708        <programlisting>? #&amp;stderr</programlisting>
     3709
     3710        <para>returns a pointer to the stdio error stream (&#34;stderr&#34; is a
    36603711          macro under OSX/Darwin).</para>
    36613712
    3662           <para>On both LinuxPPC and DarwinPPC, </para>
    3663 
    3664           <programlisting>? #?sys_errlist</programlisting>
    3665 
    3666           <para>returns a pointer to a C array of C error message strings.</para>
    3667         </refsect1>
    3668       </refentry>
     3713        <para>On both LinuxPPC and DarwinPPC, </para>
     3714
     3715        <programlisting>? #&amp;sys_errlist</programlisting>
     3716
     3717        <para>returns a pointer to a C array of C error message strings.</para>
     3718
     3719    <para>You can query whether a given name is defined in the
     3720      interface databases by appending the '?' character to the reader
     3721      macro; for example:</para>
     3722
     3723    <programlisting>
     3724      CL-USER&gt; #&amp;?sys_errlist
     3725      T
     3726      CL-USER&gt; #&amp;?foo
     3727      NIL
     3728    </programlisting>
     3729
     3730  </refsect1>
     3731</refentry>
     3732
     3733<refentry id="rm_sharpsign-dollarsign">
     3734  <indexterm zone="rm_sharpsign-dollarsign">
     3735    <primary>#$</primary>
     3736  </indexterm>
     3737 
     3738  <refnamediv>
     3739    <refname>#$</refname>
     3740    <refpurpose></refpurpose>
     3741    <refclass>Reader Macro</refclass>
     3742  </refnamediv>
     3743 
     3744  <refsect1>
     3745    <title>Description</title>
     3746   
     3747        <para>In &CCL; 0.14.2 and later, the #? reader macro can be used
     3748          to access foreign constants; this functionality depends on the
     3749          presence of &#34;constants.cdb&#34; files in the interface
     3750          database. The current behavior of the #$ reader macro is
     3751          to:</para>
     3752
     3753        <para>Read a symbol from the current input stream, with
     3754          *PACKAGE* bound to the &#34;OS&#34; package and with
     3755          readtable-case preserved.</para>
     3756       
     3757        <para>Use that symbol&#39;s pname to access the &CCL; interface
     3758          database, signalling an error if no appropriate foreign constant
     3759          information can be found with that name in any active interface
     3760          directory.</para>
     3761
     3762        <para>Use type information recorded in the database to construct a
     3763          form which can be used to access the foreign constant, and return
     3764          that form.</para>
     3765
     3766        <para>Please note that the set of foreign constants declared in
     3767          header files may or may not match the set of foreign constants
     3768          exported from libraries. When they do match, the form
     3769          constructed by the #$ reader macro manages the details of
     3770          resolving and tracking changes to the foreign constant's
     3771          address.</para>
     3772
     3773    <para>You can query whether a given name is defined in the
     3774      interface databases by appending the '?' character to the reader
     3775      macro; for example:</para>
     3776
     3777    <programlisting>
     3778      CL-USER&gt; #$?SO_KEEPALIVE
     3779      T
     3780      CL-USER&gt; #$?foo
     3781      NIL
     3782    </programlisting>
     3783
     3784  </refsect1>
     3785</refentry>
     3786
     3787<refentry id="rm_sharpsign-slash">
     3788  <indexterm zone="rm_sharpsign-slash">
     3789    <primary>#/</primary>
     3790  </indexterm>
     3791 
     3792  <refnamediv>
     3793    <refname>#/</refname>
     3794    <refpurpose></refpurpose>
     3795    <refclass>Reader Macro</refclass>
     3796  </refnamediv>
     3797 
     3798  <refsect1>
     3799    <title>Description</title>
     3800   
     3801        <para>In &CCL; 1.2 and later, the #/ reader macro can be used to
     3802          access foreign functions on the Darwin platform. The current
     3803          behavior of the #/ reader macro is to:</para>
     3804
     3805        <para>Read a symbol from the current input stream, with
     3806          *PACKAGE* bound to the "NEXTSTEP-FUNCTIONS" package, with
     3807          readtable-case preserved, and with any colons included.</para>
     3808
     3809    <para>Do limited sanity-checking on the resulting symbol; for
     3810      example, any name that contains at least one colon is required
     3811      also to end with a colon, to conform to Objective-C
     3812      method-naming conventions.</para>
     3813
     3814    <para>Export the resulting symbol from the "NEXTSTEP-FUNCTIONS"
     3815      package and return it.</para>
     3816
     3817    <para>For example, reading "#/alloc" interns and returns
     3818      NEXTSTEP-FUNCTIONS:|alloc|. Reading "#/initWithFrame:" interns
     3819      and returns NEXTSTEP-FUNCTIONS:|initWithFrame:|.</para>
     3820
     3821    <para>A symbol read using this macro can be used as an operand
     3822      in most places where an Objective-C message name can be used, such as
     3823      in the (OBJ:@SELECTOR ...) construct.</para>
     3824
     3825    <para>Please note: the reader macro is not rigorous about
     3826      enforcing Objective-C method-naming conventions. Despite the
     3827      simple checking done by the reader macro, it may still be
     3828      possible to use it to construct invalid names.</para>
     3829
     3830    <para>The act of interning a new symbol in the
     3831      NEXTSTEP-FUNCTIONS package triggers an interface database lookup
     3832      of Objective-C methods with the corresponding message name.  If any
     3833      such information is found, a special type of dispatching
     3834      function is created and initialized and the new symbol is given
     3835      the newly-created dispatching function as its function
     3836      definition.</para>
     3837
     3838    <para>The dispatching knows how to call declared Objective-C methods
     3839      defined on the message. In many cases, all methods have the same
     3840      foreign type signature, and the dispatching function merely
     3841      passes any arguments that it receives to a function that does an
     3842      Objective-C message send with the indicated foreign argument and return
     3843      types. In other cases, where different Objective-C messages have
     3844      different type signatures, the dispatching function tries to
     3845      choose a function that handles the right type signature based on
     3846      the class of the dispatching function's first argument.</para>
     3847       
     3848    <para>If new information about Objective-C methods is introduced
     3849      (e.g., by using additional interface files or as Objective-C
     3850      methods are defined from lisp), the dispatch function is
     3851      reinitialized to recognize newly-introduced foreign type
     3852      signatures.</para>
     3853
     3854    <para>The argument and result coercion that the bridge has
     3855      tradionally supported is supported by the new mechanism (e.g.,
     3856      :&lt;BOOL&gt; arguments can be specified as lisp booleans and :&lt;BOOL&gt;
     3857      results are returned as lisp boolean values, and an argument
     3858      value of NIL is coerced to a null pointer if the corresponding
     3859      argument type is :ID.</para>
     3860
     3861    <para>Some Objective-C methods accept variable numbers of
     3862      arguments; the foreign types of non-required arguments are
     3863      determined by the lisp types of those arguments (e.g., integers
     3864      are passed as integers, floats as floats, pointers as pointers,
     3865      record types by reference.)</para>
     3866
     3867    <para>Examples:</para>
     3868
     3869    <programlisting>
     3870      ;;; #/alloc is a known message.
     3871      ? #'#/alloc
     3872      #&lt;OBJC-DISPATCH-FUNCTION NEXTSTEP-FUNCTIONS:|alloc| #x300040E94EBF&gt;
     3873      ;;; Sadly, #/foo is not ...
     3874      ? #'#/foo
     3875      &gt; Error: Undefined function: NEXTSTEP-FUNCTIONS:|foo|
     3876
     3877      ;;; We can send an "init" message to a newly-allocated instance of
     3878      ;;; "NSObject" by:
     3879
     3880      (send (send ns:ns-object 'alloc) 'init)
     3881
     3882      ;;; or by
     3883
     3884      (#/init (#/alloc ns:ns-object))
     3885    </programlisting>
     3886
     3887    <para>Objective-C methods that "return" structures return them
     3888      as garbage-collectable pointers when called via dispatch
     3889      functions.  For example, if "my-window" is an NS:NS-WINDOW
     3890      instance, then</para>
     3891
     3892    <programlisting>
     3893      (#/frame my-window)
     3894    </programlisting>
     3895
     3896    <para>returns a garbage-collectable pointer to a structure that
     3897      describes that window's frame rectangle. This convention means
     3898      that there's no need to use SLET or special structure-returning
     3899      message send syntax; keep in mind, though, that #_malloc,
     3900      #_free, and the GC are all involved in the creation and eventual
     3901      destruction of structure-typed return values. In some programs
     3902      these operations may have an impact on performance.</para>
     3903
     3904  </refsect1>
     3905</refentry>
     3906
     3907<refentry id="rm_sharpsign-greaterthan">
     3908  <indexterm zone="rm_sharpsign-greaterthan">
     3909    <primary>#&gt;</primary>
     3910  </indexterm>
     3911 
     3912  <refnamediv>
     3913    <refname>#&gt;</refname>
     3914    <refpurpose></refpurpose>
     3915    <refclass>Reader Macro</refclass>
     3916  </refnamediv>
     3917 
     3918  <refsect1>
     3919    <title>Description</title>
     3920   
     3921    <para>In Clozure CL 1.2 and later, the #&gt; reader macro reads
     3922      the following text as a keyword, preserving the case of the
     3923      text. For example:</para>
     3924
     3925    <programlisting>
     3926      CL-USER&gt; #&gt;FooBar
     3927      :&lt;F&gt;OO&lt;B&gt;AR
     3928    </programlisting>
     3929
     3930    <para>The resulting keyword can be used as the name of foreign
     3931      types, records, and accessors.</para>
     3932   
     3933  </refsect1>
     3934</refentry>
     3935
    36693936
    36703937      <refentry id="f_use-interface-dir">
Note: See TracChangeset for help on using the changeset viewer.