Ignore:
Timestamp:
Apr 1, 2008, 5:07:25 PM (12 years ago)
Author:
mikel
Message:

additions to ObjC and ffi docs; many mechanical edits; some standardization of XML elements and formatting

File:
1 edited

Legend:

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

    r8903 r8981  
    6666          of <code>NS:NS-SIZE</code>, a pointer to
    6767          an <code>&lt;NSP&gt;oint</code> is recognized as an
    68           instsance of <code>NS:NS-POINT</code>, and a pointer to
     68          instance of <code>NS:NS-POINT</code>, and a pointer to
    6969          an <code>&lt;NSR&gt;ange</code> is recognized as an
    7070          instance of <code>NS:NS-RANGE</code>.</para>
     
    104104            are defined.  The accessors and setter functions typecheck
    105105            their arguments and the setters handle coercion to the
    106             approprate type of <code>CGFLOAT</code> where
     106            appropriate type of <code>CGFLOAT</code> where
    107107            applicable.</para>
    108108        </listitem>
     
    144144          <para>a macro is defined which, like <code>RLET</code>,
    145145            stack-allocates an instance of the foreign record type,
    146             optionally iniitializes that instance, and executes a body
     146            optionally initializes that instance, and executes a body
    147147            of code with a variable bound to that instance.</para>
    148148
     
    174174        <listitem>
    175175          <para>Constructors such as :SIGNED and :UNSIGNED can be
    176             used to denotesigned and unsigned integer subtypes
    177             (analogous to the CL typespecifiers SIGNED-BYTE and
     176            used to denote signed and unsigned integer subtypes
     177            (analogous to the CL type specifiers SIGNED-BYTE and
    178178            UNSIGNED-BYTE.) :SIGNED is shorthand for(:SIGNED 32) and
    179179            :UNSIGNED is shorthand for (:UNSIGNED 32).</para>
     
    181181        <listitem>
    182182          <para>Aliases for other (perhaps more complicated) types
    183             can bedefined via CCL:DEF-FOREIGN-TYPE (sort of like
    184             CL:DEFTYPE or the Ctypedef facility). The type :CHAR is
     183            can be defined via CCL:DEF-FOREIGN-TYPE (sort of like
     184            CL:DEFTYPE or the C typedef facility). The type :CHAR is
    185185            defined as an alias for (:SIGNED8) on some platforms, as
    186186            (:UNSIGNED 8) on others.</para>
     
    188188        <listitem>
    189189              <para>The construct (:STRUCT <emphasis>name</emphasis>)
    190                 can be used torefer to a named structure type; (:UNION
     190                can be used to refer to a named structure type; (:UNION
    191191                <emphasis>name</emphasis>)can be used to refer to a named
    192                 union type. It isn't necessary toenumerate a structure or
    193                 union type's fields in order to refer tothe type.</para>
     192                union type. It isn't necessary to enumerate a structure or
     193                union type's fields in order to refer to the type.</para>
    194194            </listitem>
    195195        <listitem>
    196196              <para>If <emphasis>X</emphasis> is a valid foreign type
    197197                reference,then (:* <emphasis>X</emphasis>) denotes the
    198                 foreign type "pointerto<emphasis> X</emphasis>". By
    199                 convention, (:* T) denotes ananonymous pointer type,
     198                foreign type "pointer to<emphasis> X</emphasis>". By
     199                convention, (:* T) denotes an anonymous pointer type,
    200200                vaguely equivalent to "void*" in C.</para>
    201201            </listitem>
     
    204204                is a foreign field name (keyword) and whose CADR is a
    205205                foreign type specifier, then (:STRUCT
    206                 <emphasis>name</emphasis> ,@fieldlist) is adefinition of
     206                <emphasis>name</emphasis> ,@fieldlist) is a definition of
    207207                the structure type <emphasis>name</emphasis>,
    208208                and (:UNION<emphasis> name</emphasis> ,@fieldlist) is a
    209                 definition of theunion type
     209                definition of the union type
    210210                <emphasis>name</emphasis>. Note that it's necessary
    211                 todefine a structure or union type in order to include
     211                to define a structure or union type in order to include
    212212                that type in a structure, union, or array, but only
    213                 necessary to "refer to" a strucure or union type in order
     213                necessary to "refer to" a structure or union type in order
    214214                to define a type alias or a pointer type.</para>
    215215            </listitem>
     
    217217              <para>If <emphasis>X</emphasis> is a defined foreign type
    218218                , then (:array <emphasis>X</emphasis> &amp;rest dims)
    219                 denotes the foreigntype "array of
    220                 <emphasis>X</emphasis>". Although multiplearray dimensions
     219                denotes the foreign type "array of
     220                <emphasis>X</emphasis>". Although multiple array dimensions
    221221                are allowed by the :array constructor,
    222222                only single-dimensioned arrays are (at all) well-supported
     
    246246      <para>There's no supported way to directly pass lisp data to
    247247        foreign functions: scalar lisp data must be coerced to an
    248         equivalent foreign representatation, and lisp arrays (notably
     248        equivalent foreign representation, and lisp arrays (notably
    249249        strings) must be copied to non-GCed memory.</para>
    250250
     
    362362              by value and how is very dependent on the Application
    363363              Binary Interface (ABI) of the platform; unless you're
    364               very familar with ABI detatils (some of which are quite
     364              very familiar with ABI details (some of which are quite
    365365              baroque), it's often easier to let higher-level constructs
    366366              deal with these details.</para>
     
    400400          <para><emphasis>Exactly</emphasis> how a C function that's
    401401            defined to return a foreign structure does so is dependent on
    402             the ABI (and on the size ad composition of the structure/union
     402            the ABI (and on the size and composition of the structure/union
    403403            in many cases.)</para>
    404404    </sect2>
     
    425425        <para>It's sometimes convenient to blur the distinction
    426426          between a MACPTR and the address it represents; it's
    427           sometimes necessary to maintain that distiction. It's
     427          sometimes necessary to maintain that distinction. It's
    428428          important to remember that a MACPTR is (generally) a
    429429          first-class Lisp object in the same sense that a CONS cell
     
    447447          <listitem>
    448448                <para>Creating a MACPTR with a specified address, usually
    449                   via thefunction CCL:%INT-TO-PTR.</para>
     449                  via the function CCL:%INT-TO-PTR.</para>
    450450              </listitem>
    451451          <listitem>
    452                 <para>Referencing the return valueof a foreign function
     452                <para>Referencing the return value of a foreign function
    453453                  call (see )that's specified to return an address.</para>
    454454              </listitem>
     
    483483          question of whether this code fragment exhibits a good way
    484484          to poll for external events (it doesn't), it's not hard to
    485           imagine that this loop could execute several millon times
     485          imagine that this loop could execute several million times
    486486          per second (producing several million MACPTRs per second.)
    487487          Clearly, the "naive" approach is impractical in many
     
    752752                <listitem>
    753753                      <para>References and returns an unsigned integer composed from the
    754                         width bits found bit-offsetbits from the address encapsulated by
     754                        width bits found bit-offset bits from the address encapsulated by
    755755                        ptr. (The least significant bit of the result is the value of
    756756                        (%get-bit ptr (1- (+ bit-offset width))). Can be used with SETF.</para>
     
    13111311
    13121312              <para>WITH-ENCODED-CSTRS does not automatically prepend
    1313                 bte-order marks to its output; the size of the terminating
     1313                byte-order marks to its output; the size of the terminating
    13141314                #\NUL character depends on the number of octets per code unit
    13151315                in the encoding.</para>
     
    14801480      <itemizedlist>
    14811481        <listitem>
    1482               <para>&CCL; now preserves the case of external symbols
    1483                 in itsdatabase files. See for information about case in
    1484                 foreign symbol names.</para>
     1482              <para>&CCL; now preserves the case of external symbols in
     1483                its database
     1484                files. See <link linkend="Case-sensitivity-of-foreign-names-in-CCL">Case-sensitivity
     1485                of foreign names in &CCL;</link> for information about
     1486                case in foreign symbol names.</para>
    14851487            </listitem>
    14861488            <listitem>
     
    15211523        headers/gnome/C/populate.sh
    15221524        headers/gnome/constants.cdb
    1523         headers/gnome/functions.cb
     1525        headers/gnome/functions.cdb
    15241526        headers/gnome/records.cdb
    15251527        headers/gnome/objc-classes.cdb
     
    15561558        distribution.  "libc" corresponds pretty closely to the
    15571559        interfaces associated with "glibc/libc6" header files, "gl"
    1558         corresponds to an "openGL+GLUT" developmnent package, "gtk"
     1560        corresponds to an "openGL+GLUT" development package, "gtk"
    15591561        and "gnome" contain interface information from the GTK+1.2 and
    15601562        GNOME libraries, respectively.</para>
     
    16821684        started, an attempt is made to reopen all libraries that were
    16831685        open when the image was saved, and an attempt is made to
    1684         resolve all entrypoints that had been referenced when the
     1686        resolve all entry points that had been referenced when the
    16851687        image was saved. Either of these attempts can fail "quietly",
    16861688        leaving some entry points in an unresolved state.</para>
     
    16931695        several names; the library's soname is often the most
    16941696        appropriate identifier.</para>
    1695       <para>sonames are often less version-specific than other names
     1697      <para>so names are often less version-specific than other names
    16961698        for libraries; a program that refers to a library by the name
    16971699        "libc.so.6" is more portable than one which refers to
     
    17271729          <itemizedlist>
    17281730        <listitem>
    1729               <para>"dylibs" (which often have the extension".dylib")
    1730                 are primarily intended to be linked against atcompile/link
     1731              <para>"dylibs" (which often have the extension".dylib") are
     1732                primarily intended to be linked against at compile/link
    17311733                time. They can be loaded dynamically,<emphasis>but can't
    1732                   be unloaded</emphasis>. Accordingly,OPEN-SHARED-LIBRARY
     1734                be unloaded</emphasis>. Accordingly,OPEN-SHARED-LIBRARY
    17331735                can be used to open a .dylib-style library;calling
    1734                 CLOSE-SHARED-LIBRARY on the result of such a callproduces
    1735                 a warning, and has no other effect.It appears that (due to
    1736                 an OS bug) attempts to open .dylibshared-libraries that
    1737                 are already open can cause memory corruptionunless the
    1738                 full pathname of the .dylib file is specified on thefirst
    1739                 and all subsequent calls.</para>
     1736                CLOSE-SHARED-LIBRARY on the result of such a call produces
     1737                a warning, and has no other effect. It appears that (due
     1738                to an OS bug) attempts to open .dylib shared-libraries
     1739                that are already open can cause memory corruption unless
     1740                the full pathname of the .dylib file is specified on the
     1741                first and all subsequent calls.</para>
    17401742            </listitem>
    17411743        <listitem>
     
    17551757    <title>The Interface Translator</title>
    17561758
    1757     <sect2 id="Inteface-translator-overview">
     1759    <sect2 id="Interface-translator-overview">
    17581760          <title>Overview</title>
    17591761          <para>&CCL; uses an interface translation system based on the FFIGEN
     
    18271829              <para>Ensure that the FFIGEN program is installed. See
    18281830                the"README" file in the source or binary archive for
    1829                 specificinstallation instructions.This example assumes
     1831                specific installation instructions.This example assumes
    18301832                LinuxPPC; for 32-bit DarwinPPC,
    18311833                substitute"ccl:darwin-headers;" for "ccl:headers;".  For
     
    18371839                "ccl:headers;<emphasis>subdir</emphasis>;C;populate.sh"shell
    18381840                script. When you're confident that the files
    1839                 andpreprocessor options match your environment, cd to
     1841                and preprocessor options match your environment, cd to
    18401842                the"ccl:headers;<emphasis>subdir</emphasis>;C;" directory
    1841                 andinvoke ./populate.sh. Repeat this step until you're
    1842                 able tocleanly translate all files refrenced in the shell
     1843                and invoke ./populate.sh. Repeat this step until you're
     1844                able to cleanly translate all files referenced in the shell
    18431845                script.</para>
    18441846            </listitem>
     
    18731875        many users (and implementors) would prefer not to deal with
    18741876        case-related issues. The fact that some information in the
    1875         interface databases was incomplete or inaccessable because of
     1877        interface databases was incomplete or inaccessible because of
    18761878        this policy made it clearer that the policy was untenable. I
    18771879        can't claim that the approach described here is aesthetically
     
    19391941        <listitem>
    19401942              <para>Any alphabetic characters in the symbol's pname
    1941                 thataren't enclosed in angle brackets are treated as
     1943                that aren't enclosed in angle brackets are treated as
    19421944                lower-case,regardless of the value of READTABLE-CASE and
    19431945                regardless of the case in which they were written.</para>
     
    19451947        <listitem>
    19461948              <para>Alphabetic characters that appear within angle
    1947                 brackets aremapped to upper-case, again regardless of how
    1948                 they were written orinterned.</para>
     1949                brackets are mapped to upper-case, again regardless of how
     1950                they were written or interned.</para>
    19491951            </listitem>
    19501952      </itemizedlist>
     
    26522654      new array, just keeps the same one and reverses what's in it.
    26532655      Finally, the C function passes control back to &CCL;.  Since
    2654       the allocated array memory has been directly modifed, &CCL;
     2656      the allocated array memory has been directly modified, &CCL;
    26552657      reflects those changes directly in the array as well.</para>
    26562658    <para>There is one final bit of housekeeping to deal with.
     
    27132715      &CCL;'s nonstandard "termination" mechanism, which is
    27142716      essentially the same as what Java and other languages call
    2715       "finialization".</para>
     2717      "finalization".</para>
    27162718    <para>Termination is a way of asking the garbage collector to
    27172719      let you know when it's about to destroy an object which isn't
     
    27622764    <para>If it makes sense to say that the foreign object should
    27632765      live as long as there's Lisp code that references it (through
    2764       the encapsulating obect) and no longer, this is one way of doing
     2766      the encapsulating object) and no longer, this is one way of doing
    27652767      that.</para>
    27662768    <para>Now we've covered passing basic types back and forth with
     
    28912893
    28922894            <para>Foreign variables in C code tend to be platform- and
    2893               packge-specific (the canonical example - &#34;errno&#34; - is typically
     2895              package-specific (the canonical example - &#34;errno&#34; - is typically
    28942896              not a variable when threads are involved. )</para>
    28952897
     
    30453047
    30463048        <para>The argument and result coercion that the bridge has
    3047           tradionally supported is supported by the new mechanism (e.g.,
     3049          traditionally supported is supported by the new mechanism (e.g.,
    30483050          :&lt;BOOL&gt; arguments can be specified as lisp booleans and :&lt;BOOL&gt;
    30493051          results are returned as lisp boolean values, and an argument
     
    37503752
    37513753        <para>If the argument to <code>CCL:FREE</code> is a gcable
    3752         pointer (for example, an object reurned
     3754        pointer (for example, an object returned
    37533755        by <code>MAKE-GCABLE-RECORD</code>)
    37543756        then <code>CCL:FREE</code> informs the garbage collector that
     
    39193921
    39203922            <para>
    3921               Expands into code which allocates and initalizes
     3923              Expands into code which allocates and initializes
    39223924              an instance of the type
    39233925              denoted by <varname>typespec</varname>, on the foreign
     
    39743976              that would mean that any stand-alone application using it would
    39753977              have to include a copy of the interface database
    3976               (see <xref linkend="The-Interface-Database"/>), which is undesireable
     3978              (see <xref linkend="The-Interface-Database"/>), which is undesirable
    39773979              because it's large.
    39783980            </para>
     
    43044306              bound to <link
    43054307                          linkend="Referencing-and-Using-Foreign-Memory-Addresses">a
    4306                 MACPTR</link> encapuslating the address of a stack-allocated
     4308                MACPTR</link> encapsulating the address of a stack-allocated
    43074309              foreign memory block, allocated and initialized from
    43084310              typespec and initforms as ccl:make-record.</para>
Note: See TracChangeset for help on using the changeset viewer.