Changeset 8894


Ignore:
Timestamp:
Mar 26, 2008, 2:45:10 PM (11 years ago)
Author:
mikel
Message:

tidied up lots of minor conflicts; added to save-application documentation

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

Legend:

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

    r8822 r8894  
    385385
    386386      <sect3 id="Stack-allocation-of---and-destructive-operations-on---MACPTRs-">
    387         <title>Stack allocation of - and destructive operations on - MACPTRs.</title>
     387        <title>Stack allocation of&mdash;and destructive operations on&mdash;MACPTRs.</title>
    388388            <para>If certain conditions held in the environment in which
    389               GET-NEXT-EVENT ran - namely, if it was guaranteed that
     389              GET-NEXT-EVENT ran&mdash;namely, if it was guaranteed that
    390390              neither NULL-EVENT-P nor HANDLE-EVENT cached or otherwise
    391               retained their arguments (the "event" pointer) - there'd be
     391              retained their arguments (the "event" pointer)&mdash;there'd be
    392392              a few alternatives to the naive approach. One of those
    393393              approaches would be to use the primitive function
     
    425425          loop:</para>
    426426        <programlisting>
    427           (defun get-next-event ()
    428           (loop
    429           (let* ((event (%null-ptr))) ; (%NULL-PTR) is shorthand for (%INT-TO-PTR 0)
    430           (declare (dynamic-extent event))
    431           (%setf-macptr event (#_get_next_window_system_event))
    432           (unless (null-event-p event)
    433           (handle-event event)))))
     427(defun get-next-event ()
     428  (loop
     429     (let* ((event (%null-ptr))) ; (%NULL-PTR) is shorthand for (%INT-TO-PTR 0)
     430       (declare (dynamic-extent event))
     431       (%setf-macptr event (#_get_next_window_system_event))
     432       (unless (null-event-p event)
     433         (handle-event event)))))
    434434        </programlisting>
    435435        <para>The idiom of binding one or more variables to
     
    488488
    489489      <sect3 id="Caveats-">
    490             <title>Caveats.</title>
     490            <title>Caveats</title>
    491491        <para>Reading from, writing to, allocating, and freeing
    492492          foreign memory are all potentially dangerous operations;
     
    23282328      offers more protection than direct stack allocation.</para>
    23292329    <para>The big disadvantage to allocating data on the heap is
    2330       that it must be explicitly deallocated - you need to "free" it
     2330      that it must be explicitly deallocated&mdash;you need to "free" it
    23312331      when you're done with it.  Ordinarily, in Lisp, you wouldn't
    23322332      allocate memory yourself, and the garbage collector would know
     
    23482348      data manually, you can pass it to foreign code and know that no
    23492349      matter what that code needs to do with it, it will be able to,
    2350       until you deallocated it.  Of course, you'd better be sure it's
     2350      until you deallocate it.  Of course, you'd better be sure it's
    23512351      done before you do.  Otherwise, your program will be unstable
    23522352      and might crash sometime in the future, and you'll have trouble
     
    26762676   
    26772677    <!-- ====================================  -->
     2678    <refentry id="rm_sharpsign-underscore">
     2679      <indexterm zone="rm_sharpsign-underscore">
     2680            <primary>#_</primary>
     2681      </indexterm>
     2682
     2683      <refnamediv>
     2684            <refname>#_</refname>
     2685            <refpurpose></refpurpose>
     2686            <refclass>Reader Macro</refclass>
     2687      </refnamediv>
     2688
     2689      <refsect1>
     2690            <title>Description</title>
     2691
     2692            <para>Reads a symbol from the current input stream, with *PACKAGE*
     2693              bound to the &#34;OS&#34; package and with readtable-case preserved.</para>
     2694           
     2695            <para>Does a lookup on that symbol in <link
     2696                                                     linkend="The-Interface-Database">the &CCL; interface
     2697                database</link>, signalling an error if no foreign function
     2698              information can be found for the symbol in any active <link
     2699                                                                       linkend="Using-Interface-Directories">interface
     2700                directory</link>.</para>
     2701
     2702            <para>Notes the foreign function information, including the foreign
     2703              function&#39;s return type, the number and type of the foreign
     2704              function&#39;s required arguments, and an indication of whether or
     2705              not the function accepts additional arguments (via e.g., the
     2706              &#34;varargs&#34; mechanism in C).</para>
     2707
     2708            <para>Defines a macroexpansion function on the symbol, which expand
     2709              macro calls involving the symbol into EXTERNAL-CALL forms where
     2710              foreign argument type specifiers for required arguments and the
     2711              return value specifer are provided from the information in the
     2712              database.</para>
     2713
     2714            <para>Returns the symbol.</para>
     2715
     2716            <para>The effect of these steps is that it&#39;s possible to call
     2717              foreign functions that take fixed numbers of arguments by simply
     2718              providing argument values, as in:</para>
     2719
     2720            <programlisting format="linespecific">(#_isatty fd)
     2721          (#_read fd buf n)</programlisting>
     2722
     2723            <para>and to call foreign functions that take variable numbers of
     2724              arguments by specifying the types of non-required args, as in:</para>
     2725
     2726            <programlisting format="linespecific">(with-cstrs ((format-string &#34;the answer is: %d&#34;))
     2727          (#_printf format-string :int answer))</programlisting>
     2728
     2729        <para>You can query whether a given name is defined in the
     2730          interface databases by appending the '?' character to the reader
     2731          macro; for example:</para>
     2732
     2733        <programlisting>
     2734          CL-USER&gt; #_?printf
     2735          T
     2736          CL-USER&gt; #_?foo
     2737          NIL
     2738        </programlisting>
     2739
     2740      </refsect1>
     2741    </refentry>
     2742
     2743    <!-- ====================================  -->
     2744    <refentry id="rm_sharpsign-ampersand">
     2745      <indexterm zone="rm_sharpsign-ampersand">
     2746            <primary>#&amp;</primary>
     2747      </indexterm>
     2748
     2749      <refnamediv>
     2750            <refname>#&amp;</refname>
     2751            <refpurpose></refpurpose>
     2752            <refclass>Reader Macro</refclass>
     2753      </refnamediv>
     2754
     2755      <refsect1>
     2756            <title>Description</title>
     2757
     2758            <para>In &CCL; 1.2 and later, the #&amp; reader macro can be used to
     2759              access foreign variables; this functionality depends on the presence of
     2760              &#34;vars.cdb&#34; files in the interface database. The current behavior
     2761              of the #&amp; reader macro is to:</para>
     2762
     2763            <para>Read a symbol from the current input stream, with *PACKAGE*
     2764              bound to the &#34;OS&#34; package and with readtable-case preserved.</para>
     2765           
     2766            <para>Use that symbol&#39;s pname to access the &CCL; interface
     2767              database, signalling an error if no appropriate foreign variable
     2768              information can be found with that name in any active interface
     2769              directory.</para>
     2770
     2771            <para>Use type information recorded in the database to construct a
     2772              form which can be used to access the foreign variable, and return
     2773              that form.</para>
     2774
     2775            <para>Please note that the set of foreign variables declared in header files
     2776              may or may not match the set of foreign variables exported from
     2777              libraries (we&#39;re generally talking about C and Unix here ...). When
     2778              they do match, the form constructed by the #&amp; reader macro manages the
     2779              details of resolving and tracking changes to the foreign variable&#39;s
     2780              address.</para>
     2781
     2782            <para>Future extensions (via prefix arguments to the reader macro) may
     2783              offer additional behavior; it might be convenient (for instance) to be
     2784              able to access the address of a foreign variable without dereferencing
     2785              that address.</para>
     2786
     2787            <para>Foreign variables in C code tend to be platform- and
     2788              packge-specific (the canonical example - &#34;errno&#34; - is typically
     2789              not a variable when threads are involved. )</para>
     2790
     2791            <para>In LinuxPPC, </para>
     2792
     2793            <programlisting>? #&amp;stderr</programlisting>
     2794
     2795            <para>returns a pointer to the stdio error stream (&#34;stderr&#34; is a
     2796              macro under OSX/Darwin).</para>
     2797
     2798            <para>On both LinuxPPC and DarwinPPC, </para>
     2799
     2800            <programlisting>? #&amp;sys_errlist</programlisting>
     2801
     2802            <para>returns a pointer to a C array of C error message strings.</para>
     2803
     2804        <para>You can query whether a given name is defined in the
     2805          interface databases by appending the '?' character to the reader
     2806          macro; for example:</para>
     2807
     2808        <programlisting>
     2809          CL-USER&gt; #&amp;?sys_errlist
     2810          T
     2811          CL-USER&gt; #&amp;?foo
     2812          NIL
     2813        </programlisting>
     2814
     2815      </refsect1>
     2816    </refentry>
     2817
     2818    <!-- ====================================  -->
     2819    <refentry id="rm_sharpsign-dollarsign">
     2820      <indexterm zone="rm_sharpsign-dollarsign">
     2821        <primary>#$</primary>
     2822      </indexterm>
     2823     
     2824      <refnamediv>
     2825        <refname>#$</refname>
     2826        <refpurpose></refpurpose>
     2827        <refclass>Reader Macro</refclass>
     2828      </refnamediv>
     2829     
     2830      <refsect1>
     2831        <title>Description</title>
     2832       
     2833            <para>In &CCL; 0.14.2 and later, the #? reader macro can be used
     2834              to access foreign constants; this functionality depends on the
     2835              presence of &#34;constants.cdb&#34; files in the interface
     2836              database. The current behavior of the #$ reader macro is
     2837              to:</para>
     2838
     2839            <para>Read a symbol from the current input stream, with
     2840              *PACKAGE* bound to the &#34;OS&#34; package and with
     2841              readtable-case preserved.</para>
     2842           
     2843            <para>Use that symbol&#39;s pname to access the &CCL; interface
     2844              database, signalling an error if no appropriate foreign constant
     2845              information can be found with that name in any active interface
     2846              directory.</para>
     2847
     2848            <para>Use type information recorded in the database to construct a
     2849              form which can be used to access the foreign constant, and return
     2850              that form.</para>
     2851
     2852            <para>Please note that the set of foreign constants declared in
     2853              header files may or may not match the set of foreign constants
     2854              exported from libraries. When they do match, the form
     2855              constructed by the #$ reader macro manages the details of
     2856              resolving and tracking changes to the foreign constant's
     2857              address.</para>
     2858
     2859        <para>You can query whether a given name is defined in the
     2860          interface databases by appending the '?' character to the reader
     2861          macro; for example:</para>
     2862
     2863        <programlisting>
     2864          CL-USER&gt; #$?SO_KEEPALIVE
     2865          T
     2866          CL-USER&gt; #$?foo
     2867          NIL
     2868        </programlisting>
     2869
     2870      </refsect1>
     2871    </refentry>
     2872
     2873    <!-- ====================================  -->
     2874    <refentry id="rm_sharpsign-slash">
     2875      <indexterm zone="rm_sharpsign-slash">
     2876        <primary>#/</primary>
     2877      </indexterm>
     2878     
     2879      <refnamediv>
     2880        <refname>#/</refname>
     2881        <refpurpose></refpurpose>
     2882        <refclass>Reader Macro</refclass>
     2883      </refnamediv>
     2884     
     2885      <refsect1>
     2886        <title>Description</title>
     2887       
     2888            <para>In &CCL; 1.2 and later, the #/ reader macro can be used to
     2889              access foreign functions on the Darwin platform. The current
     2890              behavior of the #/ reader macro is to:</para>
     2891
     2892            <para>Read a symbol from the current input stream, with
     2893              *PACKAGE* bound to the "NEXTSTEP-FUNCTIONS" package, with
     2894              readtable-case preserved, and with any colons included.</para>
     2895
     2896        <para>Do limited sanity-checking on the resulting symbol; for
     2897          example, any name that contains at least one colon is required
     2898          also to end with a colon, to conform to Objective-C
     2899          method-naming conventions.</para>
     2900
     2901        <para>Export the resulting symbol from the "NEXTSTEP-FUNCTIONS"
     2902          package and return it.</para>
     2903
     2904        <para>For example, reading "#/alloc" interns and returns
     2905          NEXTSTEP-FUNCTIONS:|alloc|. Reading "#/initWithFrame:" interns
     2906          and returns NEXTSTEP-FUNCTIONS:|initWithFrame:|.</para>
     2907
     2908        <para>A symbol read using this macro can be used as an operand
     2909          in most places where an Objective-C message name can be used, such as
     2910          in the (OBJ:@SELECTOR ...) construct.</para>
     2911
     2912        <para>Please note: the reader macro is not rigorous about
     2913          enforcing Objective-C method-naming conventions. Despite the
     2914          simple checking done by the reader macro, it may still be
     2915          possible to use it to construct invalid names.</para>
     2916
     2917        <para>The act of interning a new symbol in the
     2918          NEXTSTEP-FUNCTIONS package triggers an interface database lookup
     2919          of Objective-C methods with the corresponding message name.  If any
     2920          such information is found, a special type of dispatching
     2921          function is created and initialized and the new symbol is given
     2922          the newly-created dispatching function as its function
     2923          definition.</para>
     2924
     2925        <para>The dispatching knows how to call declared Objective-C methods
     2926          defined on the message. In many cases, all methods have the same
     2927          foreign type signature, and the dispatching function merely
     2928          passes any arguments that it receives to a function that does an
     2929          Objective-C message send with the indicated foreign argument and return
     2930          types. In other cases, where different Objective-C messages have
     2931          different type signatures, the dispatching function tries to
     2932          choose a function that handles the right type signature based on
     2933          the class of the dispatching function's first argument.</para>
     2934           
     2935        <para>If new information about Objective-C methods is introduced
     2936          (e.g., by using additional interface files or as Objective-C
     2937          methods are defined from lisp), the dispatch function is
     2938          reinitialized to recognize newly-introduced foreign type
     2939          signatures.</para>
     2940
     2941        <para>The argument and result coercion that the bridge has
     2942          tradionally supported is supported by the new mechanism (e.g.,
     2943          :&lt;BOOL&gt; arguments can be specified as lisp booleans and :&lt;BOOL&gt;
     2944          results are returned as lisp boolean values, and an argument
     2945          value of NIL is coerced to a null pointer if the corresponding
     2946          argument type is :ID.</para>
     2947
     2948        <para>Some Objective-C methods accept variable numbers of
     2949          arguments; the foreign types of non-required arguments are
     2950          determined by the lisp types of those arguments (e.g., integers
     2951          are passed as integers, floats as floats, pointers as pointers,
     2952          record types by reference.)</para>
     2953
     2954        <para>Examples:</para>
     2955
     2956        <programlisting>
     2957          ;;; #/alloc is a known message.
     2958          ? #'#/alloc
     2959          #&lt;OBJC-DISPATCH-FUNCTION NEXTSTEP-FUNCTIONS:|alloc| #x300040E94EBF&gt;
     2960          ;;; Sadly, #/foo is not ...
     2961          ? #'#/foo
     2962          &gt; Error: Undefined function: NEXTSTEP-FUNCTIONS:|foo|
     2963
     2964          ;;; We can send an "init" message to a newly-allocated instance of
     2965          ;;; "NSObject" by:
     2966
     2967          (send (send ns:ns-object 'alloc) 'init)
     2968
     2969          ;;; or by
     2970
     2971          (#/init (#/alloc ns:ns-object))
     2972        </programlisting>
     2973
     2974        <para>Objective-C methods that "return" structures return them
     2975          as garbage-collectable pointers when called via dispatch
     2976          functions.  For example, if "my-window" is an NS:NS-WINDOW
     2977          instance, then</para>
     2978
     2979        <programlisting>
     2980          (#/frame my-window)
     2981        </programlisting>
     2982
     2983        <para>returns a garbage-collectable pointer to a structure that
     2984          describes that window's frame rectangle. This convention means
     2985          that there's no need to use SLET or special structure-returning
     2986          message send syntax; keep in mind, though, that #_malloc,
     2987          #_free, and the GC are all involved in the creation and eventual
     2988          destruction of structure-typed return values. In some programs
     2989          these operations may have an impact on performance.</para>
     2990
     2991      </refsect1>
     2992    </refentry>
     2993
     2994    <!-- ====================================  -->
     2995    <refentry id="rm_sharpsign-greaterthan">
     2996      <indexterm zone="rm_sharpsign-greaterthan">
     2997        <primary>#&gt;</primary>
     2998      </indexterm>
     2999     
     3000      <refnamediv>
     3001        <refname>#&gt;</refname>
     3002        <refpurpose></refpurpose>
     3003        <refclass>Reader Macro</refclass>
     3004      </refnamediv>
     3005     
     3006      <refsect1>
     3007        <title>Description</title>
     3008       
     3009        <para>In Clozure CL 1.2 and later, the #&gt; reader macro reads
     3010          the following text as a keyword, preserving the case of the
     3011          text. For example:</para>
     3012
     3013        <programlisting>
     3014          CL-USER&gt; #&gt;FooBar
     3015          :&lt;F&gt;OO&lt;B&gt;AR
     3016        </programlisting>
     3017
     3018        <para>The resulting keyword can be used as the name of foreign
     3019          types, records, and accessors.</para>
     3020       
     3021      </refsect1>
     3022    </refentry>
     3023
     3024    <!-- ====================================  -->
     3025    <refentry id="f_close-shared-library">
     3026          <indexterm zone="f_close-shared-library">
     3027            <primary>close-shared-library</primary>
     3028          </indexterm>
     3029
     3030          <refnamediv>
     3031            <refname>CLOSE-SHARED-LIBRARY</refname>
     3032            <refpurpose>Stops using a shared library, informing the operating
     3033              system that it can be unloaded if appropriate.</refpurpose>
     3034            <refclass>Function</refclass>
     3035          </refnamediv>
     3036
     3037          <refsynopsisdiv>
     3038            <synopsis>
     3039              <function>close-shared-library</function> library &key;
     3040              completely</synopsis>
     3041          </refsynopsisdiv>
     3042
     3043          <refsect1>
     3044            <title>Values</title>
     3045
     3046            <variablelist>
     3047              <varlistentry>
     3048                <term>library</term>
     3049
     3050                <listitem>
     3051                      <para>either an object of type SHLIB, or a string which
     3052                        designates one by its so-name.</para>
     3053                </listitem>
     3054              </varlistentry>
     3055
     3056              <varlistentry>
     3057                <term>completely</term>
     3058
     3059                <listitem>
     3060                      <para>a boolean.  The default is T.</para>
     3061                </listitem>
     3062              </varlistentry>
     3063            </variablelist>
     3064          </refsect1>
     3065
     3066          <refsect1>
     3067            <title>Description</title>
     3068
     3069            <para>If <varname>completely</varname> is T, sets the
     3070              reference count of <varname>library</varname> to 0.  Otherwise,
     3071              decrements it by 1.  In either case, if the reference count
     3072              becomes 0, <function>close-shared-library</function>
     3073              frees all memory resources consumed <varname>library</varname>
     3074              and
     3075              causes any EXTERNAL-ENTRY-POINTs known to be defined by it to
     3076              become unresolved.</para>
     3077          </refsect1>
     3078    </refentry>
     3079
     3080    <!-- ====================================  -->
     3081    <refentry id="m_defcallback">
     3082          <indexterm zone="m_defcallback">
     3083            <primary>defcallback</primary>
     3084          </indexterm>
     3085
     3086          <refnamediv>
     3087            <refname>DEFCALLBACK</refname>
     3088            <refpurpose></refpurpose>
     3089            <refclass>Macro</refclass>
     3090          </refnamediv>
     3091
     3092          <refsynopsisdiv>
     3093            <synopsis>
     3094              <function>defcallback</function> name
     3095              ({arg-type-specifier var}* &optional; result-type-specifier)
     3096              &body; body
     3097            </synopsis>
     3098          </refsynopsisdiv>
     3099
     3100          <refsect1>
     3101            <title>Values</title>
     3102
     3103            <variablelist>
     3104              <varlistentry>
     3105                <term>name</term>
     3106
     3107                <listitem>
     3108                      <para>A symbol which can be made into a special variable</para>
     3109                </listitem>
     3110              </varlistentry>
     3111
     3112              <varlistentry>
     3113                <term>arg-type-specifer</term>
     3114
     3115                <listitem>
     3116                      <para>One of the foreign argument-type keywords,
     3117                        described above, or an equivalent <link
     3118                                                             linkend="Specifying-And-Using-Foreign-Types">foreign
     3119                          type specifier</link>.  In addition, if the keyword
     3120                        :WITHOUT-INTERRUPTS is specified, the callback will be
     3121                        executed with lisp interrupts disabled if the
     3122                        corresponding var is non-NIL. If :WITHOUT-INTERRUPTS
     3123                        is specified more than once, the rightmost instance
     3124                        wins.</para>
     3125                </listitem>
     3126              </varlistentry>
     3127
     3128              <varlistentry>
     3129                <term>var</term>
     3130
     3131                <listitem>
     3132                      <para>A symbol (lisp variable), which will be bound to a
     3133                        value of the specified type.</para>
     3134                </listitem>
     3135              </varlistentry>
     3136
     3137              <varlistentry>
     3138                <term>body</term>
     3139
     3140                <listitem>
     3141                      <para>A sequence of lisp forms, which should return a value
     3142                        which can be coerced to the specified result-type.</para>
     3143                </listitem>
     3144              </varlistentry>
     3145            </variablelist>
     3146          </refsect1>
     3147
     3148          <refsect1>
     3149            <title>Description</title>
     3150
     3151            <para>Proclaims <varname>name</varname>
     3152              to be a special variable; sets its value to a
     3153              MACPTR which, when called by foreign code, calls a lisp function
     3154              which expects foreign arguments of the specified types and which
     3155              returns a foreign value of the specified result type. Any argument
     3156              variables which correspond to foreign arguments of type :ADDRESS
     3157              are bound to stack-allocated MACPTRs.</para>
     3158           
     3159            <para>If <varname>name</varname>
     3160              is already a callback function pointer, its value is
     3161              not changed; instead, it&#39;s arranged
     3162              that an
     3163              updated version of the lisp callback function will be called.
     3164              This feature allows for callback functions to be redefined
     3165              incrementally, just like Lisp functions are.</para>
     3166
     3167            <para><function>defcallback</function>
     3168              returns the callback pointer, e.g., the
     3169              value of <varname>name</varname>.</para>
     3170          </refsect1>
     3171    </refentry>
     3172
     3173    <!-- ====================================  -->
    26783174    <refentry id="m_def-foreign-type">
    26793175          <indexterm zone="m_def-foreign-type">
     
    27393235    </refentry>
    27403236
    2741    
     3237    <!-- ====================================  -->
     3238    <refentry id="m_external">
     3239          <indexterm zone="m_external">
     3240            <primary>external</primary>
     3241          </indexterm>
     3242         
     3243          <refnamediv>
     3244            <refname>EXTERNAL</refname>
     3245            <refpurpose>Resolves a reference to an external symbol which
     3246              is defined in a shared library.</refpurpose>
     3247            <refclass>Macro</refclass>
     3248          </refnamediv>
     3249
     3250          <refsynopsisdiv>
     3251            <synopsis>
     3252              <function>external</function> name => entry
     3253            </synopsis>
     3254          </refsynopsisdiv>
     3255
     3256          <refsect1>
     3257            <title>Values</title>
     3258
     3259            <variablelist>
     3260              <varlistentry>
     3261                <term>name</term>
     3262                <listitem>
     3263                      <para>
     3264                        a simple-string which names an external symbol.
     3265                        Case-sensitive.
     3266                      </para>
     3267                </listitem>
     3268              </varlistentry>
     3269              <varlistentry>
     3270                <term>entry</term>
     3271                <listitem>
     3272                      <para>
     3273                        an object of type EXTERNAL-ENTRY-POINT which maintains
     3274                        the address of the foreign symbol named by
     3275                        <varname>name</varname>.
     3276                      </para>
     3277                </listitem>
     3278              </varlistentry>
     3279            </variablelist>
     3280          </refsect1>
     3281
     3282          <refsect1>
     3283            <title>Description</title>
     3284
     3285            <para>If there is already an EXTERNAL-ENTRY-POINT for
     3286              the symbol named by <varname>name</varname>, finds it and
     3287              returns it.  If not, creates one and returns it.</para>
     3288
     3289            <para>Tries to resolve the entry point to a memory address,
     3290              and identify the containing library.</para>
     3291
     3292            <para>Be aware that under Darwin, external functions which
     3293              are callable from C have underscores prepended to their names,
     3294              as in "_fopen".</para>
     3295          </refsect1>
     3296    </refentry>
     3297
     3298    <!-- ====================================  -->
     3299    <refentry id="m_external-call">
     3300          <indexterm zone="m_external-call">
     3301            <primary>external-call</primary>
     3302          </indexterm>
     3303
     3304          <refnamediv>
     3305            <refname>EXTERNAL-CALL</refname>
     3306            <refpurpose></refpurpose>
     3307            <refclass>Macro</refclass>
     3308          </refnamediv>
     3309
     3310          <refsynopsisdiv>
     3311            <synopsis>
     3312              <function>external-call</function> name
     3313              {arg-type-specifier arg}* &optional; result-type-specifier
     3314            </synopsis>
     3315          </refsynopsisdiv>
     3316
     3317          <refsect1>
     3318            <title>Values</title>
     3319
     3320            <variablelist>
     3321              <varlistentry>
     3322                <term>name</term>
     3323
     3324                <listitem>
     3325                      <para>A lisp string. See external, above.</para>
     3326                </listitem>
     3327              </varlistentry>
     3328
     3329              <varlistentry>
     3330                <term>arg-type-specifer</term>
     3331
     3332                <listitem>
     3333                      <para>One of the foreign argument-type keywords, described
     3334                        above, or an equivalent <link linkend="Specifying-And-Using-Foreign-Types">foreign
     3335                          type specifier</link>.</para>
     3336                </listitem>
     3337              </varlistentry>
     3338
     3339              <varlistentry>
     3340                <term>arg</term>
     3341
     3342                <listitem>
     3343                      <para>A lisp value of type indicated by the corresponding
     3344                        arg-type-specifier</para>
     3345                </listitem>
     3346              </varlistentry>
     3347
     3348              <varlistentry>
     3349                <term>result-type-specifier</term>
     3350
     3351                <listitem>
     3352                      <para>One of the foreign argument-type keywords, described
     3353                        above, or an equivalent <link linkend="Specifying-And-Using-Foreign-Types">foreign
     3354                          type specifier</link>.</para>
     3355                </listitem>
     3356              </varlistentry>
     3357            </variablelist>
     3358          </refsect1>
     3359
     3360          <refsect1>
     3361            <title>Description</title>
     3362
     3363            <para>Calls the foreign function at the address obtained by
     3364              resolving the external-entry-point associated with name, passing
     3365              the values of each arg as a foreign argument of type indicated by
     3366              the corresponding arg-type-specifier. Returns the foreign function
     3367              result (coerced to a Lisp object of type indicated by
     3368              result-type-specifier), or NIL if result-type-specifer is :VOID or
     3369              NIL</para>
     3370          </refsect1>
     3371    </refentry>
     3372
     3373    <!-- ====================================  -->
     3374    <refentry id="f_Pff-call">
     3375          <indexterm zone="f_Pff-call">
     3376            <primary>%ff-call</primary>
     3377          </indexterm>
     3378
     3379          <refnamediv>
     3380            <refname>%FF-CALL</refname>
     3381            <refpurpose></refpurpose>
     3382            <refclass>Function</refclass>
     3383          </refnamediv>
     3384
     3385          <refsynopsisdiv>
     3386            <synopsis>
     3387              <function>%ff-call</function> entrypoint
     3388              {arg-type-keyword arg}* &optional; result-type-keyword
     3389            </synopsis>
     3390          </refsynopsisdiv>
     3391
     3392          <refsect1>
     3393            <title>Values</title>
     3394
     3395            <variablelist>
     3396              <varlistentry>
     3397                <term>entrypoint</term>
     3398               
     3399                <listitem>
     3400                      <para>A fixnum or MACPTR</para>
     3401                </listitem>
     3402              </varlistentry>
     3403
     3404              <varlistentry>
     3405                <term>arg-type-keyword</term>
     3406
     3407                <listitem>
     3408                      <para>One of the foreign argument-type keywords, described
     3409                        above</para>
     3410                </listitem>
     3411              </varlistentry>
     3412
     3413              <varlistentry>
     3414                <term>arg</term>
     3415
     3416                <listitem>
     3417                      <para>A lisp value of type indicated by the corresponding
     3418                        arg-type-keyword</para>
     3419                </listitem>
     3420              </varlistentry>
     3421
     3422              <varlistentry>
     3423                <term>result-type-keyword</term>
     3424
     3425                <listitem>
     3426                      <para>One of the foreign argument-type keywords, described
     3427                        above</para>
     3428                </listitem>
     3429              </varlistentry>
     3430            </variablelist>
     3431          </refsect1>
     3432
     3433          <refsect1>
     3434            <title>Description</title>
     3435
     3436            <para>Calls the foreign function at address entrypoint passing the
     3437              values of each arg as a foreign argument of type indicated by the
     3438              corresponding arg-type-keyword. Returns the foreign function
     3439              result (coerced to a Lisp object of type indicated by
     3440              result-type-keyword), or NIL if result-type-keyword is :VOID or
     3441              NIL</para>
     3442          </refsect1>
     3443    </refentry>
     3444
     3445    <!-- ====================================  -->
     3446    <refentry id="m_ff-call">
     3447          <indexterm zone="m_ff-call">
     3448            <primary>ff-call</primary>
     3449          </indexterm>
     3450
     3451          <refnamediv>
     3452            <refname>FF-CALL</refname>
     3453            <refpurpose></refpurpose>
     3454            <refclass>Macro</refclass>
     3455          </refnamediv>
     3456
     3457          <refsynopsisdiv>
     3458            <synopsis>
     3459              <function>ff-call</function> entrypoint
     3460              {arg-type-specifier arg}* &optional; result-type-specifier
     3461            </synopsis>
     3462          </refsynopsisdiv>
     3463
     3464          <refsect1>
     3465            <title>Values</title>
     3466
     3467            <variablelist>
     3468              <varlistentry>
     3469                <term>entrypoint</term>
     3470
     3471                <listitem>
     3472                      <para>A fixnum or MACPTR</para>
     3473                </listitem>
     3474              </varlistentry>
     3475
     3476              <varlistentry>
     3477                <term>arg-type-specifer</term>
     3478
     3479                <listitem>
     3480                      <para>One of the foreign argument-type keywords, described
     3481                        above, or an equivalent <link linkend="Specifying-And-Using-Foreign-Types">foreign
     3482                          type specifier</link>.</para>
     3483                </listitem>
     3484              </varlistentry>
     3485
     3486              <varlistentry>
     3487                <term>arg</term>
     3488
     3489                <listitem>
     3490                      <para>A lisp value of type indicated by the corresponding
     3491                        arg-type-specifier</para>
     3492                </listitem>
     3493              </varlistentry>
     3494
     3495              <varlistentry>
     3496                <term>result-type-specifier</term>
     3497
     3498                <listitem>
     3499                      <para>One of the foreign argument-type keywords, described
     3500                        above, or an equivalent <link linkend="Specifying-And-Using-Foreign-Types">foreign
     3501                          type specifier</link>.</para>
     3502                </listitem>
     3503              </varlistentry>
     3504            </variablelist>
     3505          </refsect1>
     3506
     3507          <refsect1>
     3508            <title>Description</title>
     3509
     3510            <para>Calls the foreign function at address entrypoint passing the
     3511              values of each arg as a foreign argument of type indicated by the
     3512              corresponding arg-type-specifier. Returns the foreign function
     3513              result (coerced to a Lisp object of type indicated by
     3514              result-type-specifier), or NIL if result-type-specifer is :VOID or
     3515              NIL</para>
     3516          </refsect1>
     3517    </refentry>
     3518
     3519    <!-- ====================================  -->
     3520    <refentry id="f_foreign-symbol-address">
     3521          <indexterm zone="f_foreign-symbol-address">
     3522            <primary>foreign-symbol-address</primary>
     3523          </indexterm>
     3524
     3525          <refnamediv>
     3526            <refname>FOREIGN-SYMBOL-ADDRESS</refname>
     3527            <refpurpose></refpurpose>
     3528            <refclass>Function</refclass>
     3529          </refnamediv>
     3530
     3531          <refsynopsisdiv>
     3532            <synopsis>
     3533              <function>foreign-symbol-address</function> name
     3534            </synopsis>
     3535          </refsynopsisdiv>
     3536
     3537          <refsect1>
     3538            <title>Values</title>
     3539
     3540            <variablelist>
     3541              <varlistentry>
     3542                <term>name</term>
     3543
     3544                <listitem>
     3545                      <para>A lisp string.</para>
     3546                </listitem>
     3547              </varlistentry>
     3548            </variablelist>
     3549          </refsect1>
     3550
     3551          <refsect1>
     3552            <title>Description</title>
     3553
     3554            <para>Tries to resolve the address of the foreign symbol
     3555              name. If successful, returns that address encapsulated in
     3556              <link
     3557                 linkend="Referencing-and-Using-Foreign-Memory-Addresses">a
     3558                MACPTR</link>, else returns NIL.</para>
     3559          </refsect1>
     3560    </refentry>
     3561
     3562    <!-- ====================================  -->
     3563    <refentry id="f_foreign-symbol-entry">
     3564          <indexterm zone="f_foreign-symbol-entry">
     3565            <primary>foreign-symbol-entry</primary>
     3566          </indexterm>
     3567
     3568          <refnamediv>
     3569            <refname>FOREIGN-SYMBOL-ENTRY</refname>
     3570            <refpurpose></refpurpose>
     3571            <refclass>Function</refclass>
     3572          </refnamediv>
     3573
     3574          <refsynopsisdiv>
     3575            <synopsis>
     3576              <function>foreign-symbol-entry</function> name
     3577            </synopsis>
     3578          </refsynopsisdiv>
     3579
     3580          <refsect1>
     3581            <title>Values</title>
     3582
     3583            <variablelist>
     3584              <varlistentry>
     3585                <term>name</term>
     3586
     3587                <listitem>
     3588                      <para>A lisp string.</para>
     3589                </listitem>
     3590              </varlistentry>
     3591            </variablelist>
     3592          </refsect1>
     3593
     3594          <refsect1>
     3595            <title>Description</title>
     3596
     3597            <para>Tries to resolve the address of the foreign symbol name. If
     3598              successful, returns a fixnum representation of that address, else
     3599              returns NIL.</para>
     3600          </refsect1>
     3601    </refentry>
     3602
     3603    <!-- ====================================  -->
     3604    <refentry id="f_free">
     3605      <indexterm zone="f_free">
     3606        <primary>free</primary>
     3607      </indexterm>
     3608     
     3609      <refnamediv>
     3610        <refname>FREE</refname>
     3611        <refpurpose></refpurpose>
     3612        <refclass>Function</refclass>
     3613      </refnamediv>
     3614     
     3615          <refsynopsisdiv>
     3616            <synopsis>
     3617              <function>free</function> ptr
     3618            </synopsis>
     3619          </refsynopsisdiv>
     3620
     3621          <refsect1>
     3622            <title>Values</title>
     3623
     3624            <variablelist>
     3625              <varlistentry>
     3626                <term>ptr</term>
     3627
     3628                <listitem>
     3629                      <para>A <code>MACPTR</code> that points to a block of
     3630                      foreign, heap-allocated memory.</para>
     3631                </listitem>
     3632              </varlistentry>
     3633            </variablelist>
     3634          </refsect1>
     3635      <refsect1>
     3636        <title>Description</title>
     3637       
     3638        <para>In Clozure CL 1.2 and later, the <code>CCL:FREE</code>
     3639          function invokes the foreign <code>free</code> function from
     3640          the platform's standard C library to deallocate a block of
     3641          foreign memory.</para>
     3642
     3643        <para>Previous versions of &CCL; implemented this function,
     3644          but it was not exported.</para>
     3645
     3646        <para>If the argument to <code>CCL:FREE</code> is a gcable
     3647        pointer (for example, an object reurned
     3648        by <code>MAKE-GCABLE-RECORD</code>)
     3649        then <code>CCL:FREE</code> informs the garbage collector that
     3650        the foreign memory has been deallocated before calling the
     3651        foreign <code>free</code> function.</para>
     3652       
     3653      </refsect1>
     3654    </refentry>
     3655
     3656    <!-- ====================================  -->
     3657    <refentry id="m_makegcable--record">
     3658      <indexterm zone="m_make-record">
     3659            <primary>make-gcable-record</primary>
     3660      </indexterm>
     3661
     3662      <refnamediv>
     3663            <refname>MAKE-GCABLE-RECORD</refname>
     3664            <refpurpose></refpurpose>
     3665            <refclass>Macro</refclass>
     3666      </refnamediv>
     3667
     3668      <refsynopsisdiv>
     3669            <synopsis>
     3670              <function>make-gcable-record</function> typespec
     3671              &rest; initforms => result
     3672            </synopsis>
     3673      </refsynopsisdiv>
     3674
     3675      <refsect1>
     3676            <title>Values</title>
     3677
     3678            <variablelist>
     3679              <varlistentry>
     3680                <term>typespec</term>
     3681
     3682                <listitem>
     3683                      <para>A foreign type specifier, or a keyword which is used
     3684                        as the name of a foreign struct or union.</para>
     3685                </listitem>
     3686              </varlistentry>
     3687
     3688              <varlistentry>
     3689                <term>initforms</term>
     3690
     3691                <listitem>
     3692                      <para>If the type denoted by <varname>typespec</varname>
     3693                        is scalar, a single value appropriate for that type;
     3694                        otherwise, a list of alternating field names and
     3695                        values appropriate for the types of those fields.</para>
     3696                </listitem>
     3697              </varlistentry>
     3698
     3699              <varlistentry>
     3700                <term>result</term>
     3701
     3702                <listitem>
     3703                      <para>
     3704                        A <type>macptr</type> which encapsulates the address of a
     3705                        newly-allocated record on the foreign heap. The foreign
     3706                        object returned by <function>make-gcable-record</function>
     3707                        is freed when the garbage collector determines that
     3708                        the <code>MACPTR</code> object that describes it is
     3709                        unreachable.</para>
     3710                </listitem>
     3711              </varlistentry>
     3712            </variablelist>
     3713      </refsect1>
     3714
     3715      <refsect1>
     3716            <title>Description</title>
     3717
     3718            <para>
     3719              Allocates a block of foreign memory suitable to hold the foreign
     3720              type described by <code>typespec</code>, in the same manner
     3721              as <link linkend="anchor_make-record">MAKE-RECORD</link>. In
     3722              addition, <code>MAKE-GCABLE-RECORD</code> marks the
     3723              returned object gcable; in other words, it informs the garbage
     3724              collector that it may reclaim the object when it becomes
     3725              unreachable.
     3726            </para>
     3727
     3728        <para>In all other respects, <code>MAKE-GCABLE-RECORD</code> works
     3729          the same way
     3730          as <link linkend="anchor_make-record">MAKE-RECORD</link></para>
     3731
     3732        <para> When using gcable pointers, it's important to remember the
     3733          distinction between a <code>MACPTR</code> object (which is a
     3734          lisp object, more or less like any other) and the block of
     3735          foreign memory that the <code>MACPTR</code> object points to.
     3736          If a gcable <code>MACPTR</code> object is the only thing in the
     3737          world (lisp world or foreign world) that references the
     3738          underlying block of foreign memory, then freeing the foreign
     3739          memory when it becomes impossible to reference it is convenient
     3740          and sane.  If other lisp <code>MACPTR</code>s reference the
     3741          underlying block of foreign memory or if the address of that
     3742          foreign memory is passed to and retained by foreign code, having
     3743          the GC free the memory may have unpleasant consequences if those
     3744          other references are used.</para>
     3745
     3746        <para>Take care, therefore, not to create a gcable record unless
     3747          you are sure that the returned <code>MACPTR</code> will be the
     3748          only reference to the allocated memory that will ever be
     3749          used.</para>
     3750      </refsect1>
     3751
     3752    </refentry>
     3753
     3754
    27423755    <!-- ====================================  -->
    27433756    <refentry id="m_make-record">
     
    28073820              <function>malloc</function>, and the user of
    28083821              <function>make-record</function> must explicitly call
    2809               the C function <function>free</function> to deallocate the
     3822              the function <function>CCL:FREE</function> to deallocate the
    28103823              record, when it is no longer needed.
    28113824            </para>
     
    28593872              because it's large.
    28603873            </para>
    2861           </refsect1>
    2862     </refentry>
    2863 
    2864     <!-- ====================================  -->
    2865     <refentry id="m_makegcable--record">
    2866       <indexterm zone="m_make-record">
    2867             <primary>make-gcable-record</primary>
    2868       </indexterm>
    2869 
    2870       <refnamediv>
    2871             <refname>MAKE-GCABLE-RECORD</refname>
    2872             <refpurpose></refpurpose>
    2873             <refclass>Macro</refclass>
    2874       </refnamediv>
    2875 
    2876       <refsynopsisdiv>
    2877             <synopsis>
    2878               <function>make-gcable-record</function> typespec
    2879               &rest; initforms => result
    2880             </synopsis>
    2881       </refsynopsisdiv>
    2882 
    2883       <refsect1>
    2884             <title>Values</title>
    2885 
    2886             <variablelist>
    2887               <varlistentry>
    2888                 <term>typespec</term>
    2889 
    2890                 <listitem>
    2891                       <para>A foreign type specifier, or a keyword which is used
    2892                         as the name of a foreign struct or union.</para>
    2893                 </listitem>
    2894               </varlistentry>
    2895 
    2896               <varlistentry>
    2897                 <term>initforms</term>
    2898 
    2899                 <listitem>
    2900                       <para>If the type denoted by <varname>typespec</varname>
    2901                         is scalar, a single value appropriate for that type;
    2902                         otherwise, a list of alternating field names and
    2903                         values appropriate for the types of those fields.</para>
    2904                 </listitem>
    2905               </varlistentry>
    2906 
    2907               <varlistentry>
    2908                 <term>result</term>
    2909 
    2910                 <listitem>
    2911                       <para>
    2912                         A <type>macptr</type> which encapsulates the address of a
    2913                         newly-allocated record on the foreign heap. The foreign
    2914                         object returned by <function>make-gcable-record</function>
    2915                         is freed when the garbage collector determines that
    2916                         the <code>MACPTR</code> object that describes it is
    2917                         unreachable.</para>
    2918                 </listitem>
    2919               </varlistentry>
    2920             </variablelist>
    2921       </refsect1>
    2922 
    2923       <refsect1>
    2924             <title>Description</title>
    2925 
    2926             <para>
    2927               Allocates a block of foreign memory suitable to hold the foreign
    2928               type described by <code>typespec</code>, in the same manner
    2929               as <link linkend="anchor_make-record">MAKE-RECORD</link>. In
    2930               addition, <code>MAKE-GCABLE-RECORD</code> marks the
    2931               returned object gcable; in other words, it informs the garbage
    2932               collector that it may reclaim the object when it becomes
    2933               unreachable.
    2934             </para>
    2935 
    2936         <para>In all other respects, <code>MAKE-GCABLE-RECORD</code> works
    2937           the same way
    2938           as <link linkend="anchor_make-record">MAKE-RECORD</link></para>
    2939 
    2940         <para> When using gcable pointers, it's important to remember the
    2941           distinction between a <code>MACPTR</code> object (which is a
    2942           lisp object, more or less like any other) and the block of
    2943           foreign memory that the <code>MACPTR</code> object points to.
    2944           If a gcable <code>MACPTR</code> object is the only thing in the
    2945           world (lisp world or foreign world) that references the
    2946           underlying block of foreign memory, then freeing the foreign
    2947           memory when it becomes impossible to reference it is convenient
    2948           and sane.  If other lisp <code>MACPTR</code>s reference the
    2949           underlying block of foreign memory or if the address of that
    2950           foreign memory is passed to and retained by foreign code, having
    2951           the GC free the memory may have unpleasant consequences if those
    2952           other references are used.</para>
    2953 
    2954         <para>Take care, therefore, not to create a gcable record unless
    2955           you are sure that the returned <code>MACPTR</code> will be the
    2956           only reference to the allocated memory that will ever be
    2957           used.</para>
    2958       </refsect1>
    2959 
    2960     </refentry>
    2961 
    2962 
    2963 
    2964     <!-- ====================================  -->
    2965     <refentry id="m_rlet">
    2966           <indexterm zone="m_rlet">
    2967             <primary>rlet</primary>
    2968           </indexterm>
    2969 
    2970           <refnamediv>
    2971             <refname>RLET</refname>
    2972             <refpurpose></refpurpose>
    2973             <refclass>Macro</refclass>
    2974           </refnamediv>
    2975 
    2976           <refsynopsisdiv>
    2977             <synopsis>
    2978               <function>rlet</function> (var typespec &rest; initforms)*
    2979               &body; body
    2980             </synopsis>
    2981           </refsynopsisdiv>
    2982 
    2983           <refsect1>
    2984             <title>Values</title>
    2985 
    2986             <variablelist>
    2987               <varlistentry>
    2988                 <term>var</term>
    2989 
    2990                 <listitem>
    2991                       <para>A symbol (a lisp variable)</para>
    2992                 </listitem>
    2993               </varlistentry>
    2994 
    2995               <varlistentry>
    2996                 <term>typespec</term>
    2997 
    2998                 <listitem>
    2999                       <para>A foreign type specifier or foreign record name.</para>
    3000                 </listitem>
    3001               </varlistentry>
    3002 
    3003           <varlistentry>
    3004                 <term>initforms</term>
    3005 
    3006                 <listitem>
    3007                       <para>As described above, for
    3008                         <xref linkend="m_make-record"/></para>
    3009                 </listitem>
    3010               </varlistentry>
    3011             </variablelist>
    3012           </refsect1>
    3013 
    3014           <refsect1>
    3015             <title>Description</title>
    3016 
    3017             <para>Executes <varname>body</varname>
    3018               in an environment in which each var is bound
    3019               to <link linkend="Referencing-and-Using-Foreign-Memory-Addresses">a MACPTR</link> encapsulating the
    3020               address of a stack-allocated foreign memory block, allocated and
    3021               initialized from typespec and initforms as per
    3022               <xref linkend="m_make-record"/>.
    3023               Returns whatever value(s) <varname>body</varname>
    3024               returns.</para>
    3025            
    3026             <para>Record fields that aren&#39;t explicitly initialized have
    3027               unspecified contents.</para>
    3028           </refsect1>
    3029     </refentry>
    3030 
    3031     <!-- ====================================  -->
    3032     <refentry id="m_rletz">
    3033           <indexterm zone="m_rletz">
    3034             <primary>rletz</primary>
    3035           </indexterm>
    3036 
    3037           <refnamediv>
    3038             <refname>RLETZ</refname>
    3039             <refpurpose></refpurpose>
    3040             <refclass>Macro</refclass>
    3041           </refnamediv>
    3042 
    3043           <refsynopsisdiv>
    3044             <synopsis>
    3045               <function>rletz</function> (var typespec &rest; initforms)*
    3046               &body; body
    3047             </synopsis>
    3048           </refsynopsisdiv>
    3049 
    3050           <refsect1>
    3051             <title>Values</title>
    3052 
    3053             <variablelist>
    3054               <varlistentry>
    3055                 <term>var</term>
    3056 
    3057                 <listitem>
    3058                       <para>A symbol (a lisp variable)</para>
    3059                 </listitem>
    3060               </varlistentry>
    3061 
    3062               <varlistentry>
    3063                 <term>typespec</term>
    3064 
    3065                 <listitem>
    3066                       <para>A foreign type specifier or foreign record name.</para>
    3067                 </listitem>
    3068               </varlistentry>
    3069 
    3070               <varlistentry>
    3071                 <term>initforms</term>
    3072 
    3073                 <listitem>
    3074                       <para>As described above, for ccl:make-record</para>
    3075                 </listitem>
    3076               </varlistentry>
    3077             </variablelist>
    3078           </refsect1>
    3079 
    3080           <refsect1>
    3081             <title>Description</title>
    3082 
    3083             <para>Executes body in an environment in which each var is
    3084               bound to <link
    3085                           linkend="Referencing-and-Using-Foreign-Memory-Addresses">a
    3086                 MACPTR</link> encapuslating the address of a stack-allocated
    3087               foreign memory block, allocated and initialized from
    3088               typespec and initforms as ccl:make-record.</para>
    3089            
    3090             <para>Returns whatever value(s) body returns.</para>
    3091 
    3092             <para>Unlike rlet, record fields that aren&#39;t explicitly
    3093               initialized are set to binary 0.</para>
    3094           </refsect1>
    3095     </refentry>
    3096 
    3097     <!-- ====================================  -->
    3098     <refentry id="m_pref">
    3099           <indexterm zone="m_pref">
    3100             <primary>pref</primary>
    3101           </indexterm>
    3102 
    3103           <refnamediv>
    3104             <refname>PREF</refname>
    3105             <refpurpose></refpurpose>
    3106             <refclass>Macro</refclass>
    3107           </refnamediv>
    3108 
    3109           <refsynopsisdiv>
    3110             <synopsis>
    3111               <function>pref</function> ptr accessor-form
    3112             </synopsis>
    3113 
    3114           </refsynopsisdiv>
    3115 
    3116           <refsect1>
    3117             <title>Values</title>
    3118 
    3119             <variablelist>
    3120               <varlistentry>
    3121                 <term>ptr</term>
    3122 
    3123                 <listitem>
    3124                       <para><link linkend="Referencing-and-Using-Foreign-Memory-Addresses">a MACPTR</link>.</para>
    3125                 </listitem>
    3126               </varlistentry>
    3127 
    3128               <varlistentry>
    3129                 <term>accessor-form</term>
    3130 
    3131                 <listitem>
    3132                       <para>a keyword which names a foreign type or record, as
    3133                         described in <xref linkend="Foreign-type--record--and-field-names"/>.
    3134                       </para>
    3135                 </listitem>
    3136               </varlistentry>
    3137             </variablelist>
    3138           </refsect1>
    3139 
    3140           <refsect1>
    3141             <title>Description</title>
    3142 
    3143             <para>References an instance of a foreign type (or a component of
    3144               a foreign type) accessible via ptr.</para>
    3145            
    3146             <para>Expands into code which references the indicated scalar type
    3147               or component, or returns a pointer to a composite type.</para>
    3148            
    3149             <para>PREF can be used with SETF.</para>
    3150            
    3151             <para>RREF is a deprecated alternative to PREF. It accepts a
    3152               :STORAGE keyword and rather loudly ignores it.</para>
    31533874          </refsect1>
    31543875    </refentry>
     
    32533974          </refsect1>
    32543975    </refentry>
    3255 
     3976   
    32563977    <!-- ====================================  -->
    3257     <refentry id="f_close-shared-library">
    3258           <indexterm zone="f_close-shared-library">
    3259             <primary>close-shared-library</primary>
     3978    <refentry id="m_pref">
     3979          <indexterm zone="m_pref">
     3980            <primary>pref</primary>
    32603981          </indexterm>
    32613982
    32623983          <refnamediv>
    3263             <refname>CLOSE-SHARED-LIBRARY</refname>
    3264             <refpurpose>Stops using a shared library, informing the operating
    3265               system that it can be unloaded if appropriate.</refpurpose>
    3266             <refclass>Function</refclass>
    3267           </refnamediv>
    3268 
    3269           <refsynopsisdiv>
    3270             <synopsis>
    3271               <function>close-shared-library</function> library &key;
    3272               completely</synopsis>
    3273           </refsynopsisdiv>
    3274 
    3275           <refsect1>
    3276             <title>Values</title>
    3277 
    3278             <variablelist>
    3279               <varlistentry>
    3280                 <term>library</term>
    3281 
    3282                 <listitem>
    3283                       <para>either an object of type SHLIB, or a string which
    3284                         designates one by its so-name.</para>
    3285                 </listitem>
    3286               </varlistentry>
    3287 
    3288               <varlistentry>
    3289                 <term>completely</term>
    3290 
    3291                 <listitem>
    3292                       <para>a boolean.  The default is T.</para>
    3293                 </listitem>
    3294               </varlistentry>
    3295             </variablelist>
    3296           </refsect1>
    3297 
    3298           <refsect1>
    3299             <title>Description</title>
    3300 
    3301             <para>If <varname>completely</varname> is T, sets the
    3302               reference count of <varname>library</varname> to 0.  Otherwise,
    3303               decrements it by 1.  In either case, if the reference count
    3304               becomes 0, <function>close-shared-library</function>
    3305               frees all memory resources consumed <varname>library</varname>
    3306               and
    3307               causes any EXTERNAL-ENTRY-POINTs known to be defined by it to
    3308               become unresolved.</para>
    3309           </refsect1>
    3310     </refentry>
    3311 
    3312     <!-- ====================================  -->
    3313     <refentry id="m_external">
    3314           <indexterm zone="m_external">
    3315             <primary>external</primary>
    3316           </indexterm>
    3317          
    3318           <refnamediv>
    3319             <refname>EXTERNAL</refname>
    3320             <refpurpose>Resolves a reference to an external symbol which
    3321               is defined in a shared library.</refpurpose>
    3322             <refclass>Macro</refclass>
    3323           </refnamediv>
    3324 
    3325           <refsynopsisdiv>
    3326             <synopsis>
    3327               <function>external</function> name => entry
    3328             </synopsis>
    3329           </refsynopsisdiv>
    3330 
    3331           <refsect1>
    3332             <title>Values</title>
    3333 
    3334             <variablelist>
    3335               <varlistentry>
    3336                 <term>name</term>
    3337                 <listitem>
    3338                       <para>
    3339                         a simple-string which names an external symbol.
    3340                         Case-sensitive.
    3341                       </para>
    3342                 </listitem>
    3343               </varlistentry>
    3344               <varlistentry>
    3345                 <term>entry</term>
    3346                 <listitem>
    3347                       <para>
    3348                         an object of type EXTERNAL-ENTRY-POINT which maintains
    3349                         the address of the foreign symbol named by
    3350                         <varname>name</varname>.
    3351                       </para>
    3352                 </listitem>
    3353               </varlistentry>
    3354             </variablelist>
    3355           </refsect1>
    3356 
    3357           <refsect1>
    3358             <title>Description</title>
    3359 
    3360             <para>If there is already an EXTERNAL-ENTRY-POINT for
    3361               the symbol named by <varname>name</varname>, finds it and
    3362               returns it.  If not, creates one and returns it.</para>
    3363 
    3364             <para>Tries to resolve the entry point to a memory address,
    3365               and identify the containing library.</para>
    3366 
    3367             <para>Be aware that under Darwin, external functions which
    3368               are callable from C have underscores prepended to their names,
    3369               as in "_fopen".</para>
    3370           </refsect1>
    3371     </refentry>
    3372 
    3373     <!-- ====================================  -->
    3374     <refentry id="f_Pff-call">
    3375           <indexterm zone="f_Pff-call">
    3376             <primary>%ff-call</primary>
    3377           </indexterm>
    3378 
    3379           <refnamediv>
    3380             <refname>%FF-CALL</refname>
    3381             <refpurpose></refpurpose>
    3382             <refclass>Function</refclass>
    3383           </refnamediv>
    3384 
    3385           <refsynopsisdiv>
    3386             <synopsis>
    3387               <function>%ff-call</function> entrypoint
    3388               {arg-type-keyword arg}* &optional; result-type-keyword
    3389             </synopsis>
    3390           </refsynopsisdiv>
    3391 
    3392           <refsect1>
    3393             <title>Values</title>
    3394 
    3395             <variablelist>
    3396               <varlistentry>
    3397                 <term>entrypoint</term>
    3398                
    3399                 <listitem>
    3400                       <para>A fixnum or MACPTR</para>
    3401                 </listitem>
    3402               </varlistentry>
    3403 
    3404               <varlistentry>
    3405                 <term>arg-type-keyword</term>
    3406 
    3407                 <listitem>
    3408                       <para>One of the foreign argument-type keywords, described
    3409                         above</para>
    3410                 </listitem>
    3411               </varlistentry>
    3412 
    3413               <varlistentry>
    3414                 <term>arg</term>
    3415 
    3416                 <listitem>
    3417                       <para>A lisp value of type indicated by the corresponding
    3418                         arg-type-keyword</para>
    3419                 </listitem>
    3420               </varlistentry>
    3421 
    3422               <varlistentry>
    3423                 <term>result-type-keyword</term>
    3424 
    3425                 <listitem>
    3426                       <para>One of the foreign argument-type keywords, described
    3427                         above</para>
    3428                 </listitem>
    3429               </varlistentry>
    3430             </variablelist>
    3431           </refsect1>
    3432 
    3433           <refsect1>
    3434             <title>Description</title>
    3435 
    3436             <para>Calls the foreign function at address entrypoint passing the
    3437               values of each arg as a foreign argument of type indicated by the
    3438               corresponding arg-type-keyword. Returns the foreign function
    3439               result (coerced to a Lisp object of type indicated by
    3440               result-type-keyword), or NIL if result-type-keyword is :VOID or
    3441               NIL</para>
    3442           </refsect1>
    3443     </refentry>
    3444 
    3445     <!-- ====================================  -->
    3446     <refentry id="m_ff-call">
    3447           <indexterm zone="m_ff-call">
    3448             <primary>ff-call</primary>
    3449           </indexterm>
    3450 
    3451           <refnamediv>
    3452             <refname>FF-CALL</refname>
     3984            <refname>PREF</refname>
    34533985            <refpurpose></refpurpose>
    34543986            <refclass>Macro</refclass>
     
    34573989          <refsynopsisdiv>
    34583990            <synopsis>
    3459               <function>ff-call</function> entrypoint
    3460               {arg-type-specifier arg}* &optional; result-type-specifier
     3991              <function>pref</function> ptr accessor-form
    34613992            </synopsis>
     3993
    34623994          </refsynopsisdiv>
    34633995
     
    34673999            <variablelist>
    34684000              <varlistentry>
    3469                 <term>entrypoint</term>
    3470 
    3471                 <listitem>
    3472                       <para>A fixnum or MACPTR</para>
    3473                 </listitem>
    3474               </varlistentry>
    3475 
    3476               <varlistentry>
    3477                 <term>arg-type-specifer</term>
    3478 
    3479                 <listitem>
    3480                       <para>One of the foreign argument-type keywords, described
    3481                         above, or an equivalent <link linkend="Specifying-And-Using-Foreign-Types">foreign
    3482                           type specifier</link>.</para>
    3483                 </listitem>
    3484               </varlistentry>
    3485 
    3486               <varlistentry>
    3487                 <term>arg</term>
    3488 
    3489                 <listitem>
    3490                       <para>A lisp value of type indicated by the corresponding
    3491                         arg-type-specifier</para>
    3492                 </listitem>
    3493               </varlistentry>
    3494 
    3495               <varlistentry>
    3496                 <term>result-type-specifier</term>
    3497 
    3498                 <listitem>
    3499                       <para>One of the foreign argument-type keywords, described
    3500                         above, or an equivalent <link linkend="Specifying-And-Using-Foreign-Types">foreign
    3501                           type specifier</link>.</para>
     4001                <term>ptr</term>
     4002
     4003                <listitem>
     4004                      <para><link linkend="Referencing-and-Using-Foreign-Memory-Addresses">a MACPTR</link>.</para>
     4005                </listitem>
     4006              </varlistentry>
     4007
     4008              <varlistentry>
     4009                <term>accessor-form</term>
     4010
     4011                <listitem>
     4012                      <para>a keyword which names a foreign type or record, as
     4013                        described in <xref linkend="Foreign-type--record--and-field-names"/>.
     4014                      </para>
    35024015                </listitem>
    35034016              </varlistentry>
     
    35084021            <title>Description</title>
    35094022
    3510             <para>Calls the foreign function at address entrypoint passing the
    3511               values of each arg as a foreign argument of type indicated by the
    3512               corresponding arg-type-specifier. Returns the foreign function
    3513               result (coerced to a Lisp object of type indicated by
    3514               result-type-specifier), or NIL if result-type-specifer is :VOID or
    3515               NIL</para>
     4023            <para>References an instance of a foreign type (or a component of
     4024              a foreign type) accessible via ptr.</para>
     4025           
     4026            <para>Expands into code which references the indicated scalar type
     4027              or component, or returns a pointer to a composite type.</para>
     4028           
     4029            <para>PREF can be used with SETF.</para>
     4030           
     4031            <para>RREF is a deprecated alternative to PREF. It accepts a
     4032              :STORAGE keyword and rather loudly ignores it.</para>
    35164033          </refsect1>
    35174034    </refentry>
     
    35604077
    35614078    <!-- ====================================  -->
    3562     <refentry id="m_external-call">
    3563           <indexterm zone="m_external-call">
    3564             <primary>external-call</primary>
     4079    <refentry id="m_rlet">
     4080          <indexterm zone="m_rlet">
     4081            <primary>rlet</primary>
    35654082          </indexterm>
    35664083
    35674084          <refnamediv>
    3568             <refname>EXTERNAL-CALL</refname>
     4085            <refname>RLET</refname>
    35694086            <refpurpose></refpurpose>
    35704087            <refclass>Macro</refclass>
     
    35734090          <refsynopsisdiv>
    35744091            <synopsis>
    3575               <function>external-call</function> name
    3576               {arg-type-specifier arg}* &optional; result-type-specifier
     4092              <function>rlet</function> (var typespec &rest; initforms)*
     4093              &body; body
    35774094            </synopsis>
    35784095          </refsynopsisdiv>
     
    35834100            <variablelist>
    35844101              <varlistentry>
    3585                 <term>name</term>
    3586 
    3587                 <listitem>
    3588                       <para>A lisp string. See external, above.</para>
    3589                 </listitem>
    3590               </varlistentry>
    3591 
    3592               <varlistentry>
    3593                 <term>arg-type-specifer</term>
    3594 
    3595                 <listitem>
    3596                       <para>One of the foreign argument-type keywords, described
    3597                         above, or an equivalent <link linkend="Specifying-And-Using-Foreign-Types">foreign
    3598                           type specifier</link>.</para>
    3599                 </listitem>
    3600               </varlistentry>
    3601 
    3602               <varlistentry>
    3603                 <term>arg</term>
    3604 
    3605                 <listitem>
    3606                       <para>A lisp value of type indicated by the corresponding
    3607                         arg-type-specifier</para>
    3608                 </listitem>
    3609               </varlistentry>
    3610 
    3611               <varlistentry>
    3612                 <term>result-type-specifier</term>
    3613 
    3614                 <listitem>
    3615                       <para>One of the foreign argument-type keywords, described
    3616                         above, or an equivalent <link linkend="Specifying-And-Using-Foreign-Types">foreign
    3617                           type specifier</link>.</para>
     4102                <term>var</term>
     4103
     4104                <listitem>
     4105                      <para>A symbol (a lisp variable)</para>
     4106                </listitem>
     4107              </varlistentry>
     4108
     4109              <varlistentry>
     4110                <term>typespec</term>
     4111
     4112                <listitem>
     4113                      <para>A foreign type specifier or foreign record name.</para>
     4114                </listitem>
     4115              </varlistentry>
     4116
     4117          <varlistentry>
     4118                <term>initforms</term>
     4119
     4120                <listitem>
     4121                      <para>As described above, for
     4122                        <xref linkend="m_make-record"/></para>
    36184123                </listitem>
    36194124              </varlistentry>
     
    36244129            <title>Description</title>
    36254130
    3626             <para>Calls the foreign function at the address obtained by
    3627               resolving the external-entry-point associated with name, passing
    3628               the values of each arg as a foreign argument of type indicated by
    3629               the corresponding arg-type-specifier. Returns the foreign function
    3630               result (coerced to a Lisp object of type indicated by
    3631               result-type-specifier), or NIL if result-type-specifer is :VOID or
    3632               NIL</para>
     4131            <para>Executes <varname>body</varname>
     4132              in an environment in which each var is bound
     4133              to <link linkend="Referencing-and-Using-Foreign-Memory-Addresses">a MACPTR</link> encapsulating the
     4134              address of a stack-allocated foreign memory block, allocated and
     4135              initialized from typespec and initforms as per
     4136              <xref linkend="m_make-record"/>.
     4137              Returns whatever value(s) <varname>body</varname>
     4138              returns.</para>
     4139           
     4140            <para>Record fields that aren&#39;t explicitly initialized have
     4141              unspecified contents.</para>
    36334142          </refsect1>
    36344143    </refentry>
    36354144
    36364145    <!-- ====================================  -->
    3637     <refentry id="f_foreign-symbol-entry">
    3638           <indexterm zone="f_foreign-symbol-entry">
    3639             <primary>foreign-symbol-entry</primary>
     4146    <refentry id="m_rletz">
     4147          <indexterm zone="m_rletz">
     4148            <primary>rletz</primary>
    36404149          </indexterm>
    36414150
    36424151          <refnamediv>
    3643             <refname>FOREIGN-SYMBOL-ENTRY</refname>
     4152            <refname>RLETZ</refname>
     4153            <refpurpose></refpurpose>
     4154            <refclass>Macro</refclass>
     4155          </refnamediv>
     4156
     4157          <refsynopsisdiv>
     4158            <synopsis>
     4159              <function>rletz</function> (var typespec &rest; initforms)*
     4160              &body; body
     4161            </synopsis>
     4162          </refsynopsisdiv>
     4163
     4164          <refsect1>
     4165            <title>Values</title>
     4166
     4167            <variablelist>
     4168              <varlistentry>
     4169                <term>var</term>
     4170
     4171                <listitem>
     4172                      <para>A symbol (a lisp variable)</para>
     4173                </listitem>
     4174              </varlistentry>
     4175
     4176              <varlistentry>
     4177                <term>typespec</term>
     4178
     4179                <listitem>
     4180                      <para>A foreign type specifier or foreign record name.</para>
     4181                </listitem>
     4182              </varlistentry>
     4183
     4184              <varlistentry>
     4185                <term>initforms</term>
     4186
     4187                <listitem>
     4188                      <para>As described above, for ccl:make-record</para>
     4189                </listitem>
     4190              </varlistentry>
     4191            </variablelist>
     4192          </refsect1>
     4193
     4194          <refsect1>
     4195            <title>Description</title>
     4196
     4197            <para>Executes body in an environment in which each var is
     4198              bound to <link
     4199                          linkend="Referencing-and-Using-Foreign-Memory-Addresses">a
     4200                MACPTR</link> encapuslating the address of a stack-allocated
     4201              foreign memory block, allocated and initialized from
     4202              typespec and initforms as ccl:make-record.</para>
     4203           
     4204            <para>Returns whatever value(s) body returns.</para>
     4205
     4206            <para>Unlike rlet, record fields that aren&#39;t explicitly
     4207              initialized are set to binary 0.</para>
     4208          </refsect1>
     4209    </refentry>
     4210
     4211    <!-- ====================================  -->
     4212    <refentry id="f_terminate-when-unreachable">
     4213          <indexterm zone="f_terminate-when-unreachable">
     4214            <primary>terminate-when-unreachable</primary>
     4215          </indexterm>
     4216
     4217          <refnamediv>
     4218            <refname>TERMINATE-WHEN-UNREACHABLE</refname>
    36444219            <refpurpose></refpurpose>
    36454220            <refclass>Function</refclass>
     
    36484223          <refsynopsisdiv>
    36494224            <synopsis>
    3650               <function>foreign-symbol-entry</function> name
     4225              <function>terminate-when-unreachable</function> object
    36514226            </synopsis>
    36524227          </refsynopsisdiv>
     
    36574232            <variablelist>
    36584233              <varlistentry>
    3659                 <term>name</term>
    3660 
    3661                 <listitem>
    3662                       <para>A lisp string.</para>
     4234                <term>object</term>
     4235
     4236                <listitem>
     4237                      <para>A CLOS object of a class for which there exists
     4238                        a method of the generic function
     4239                        <function>ccl:terminate</function>.
     4240                      </para>
    36634241                </listitem>
    36644242              </varlistentry>
     
    36694247            <title>Description</title>
    36704248
    3671             <para>Tries to resolve the address of the foreign symbol name. If
    3672               successful, returns a fixnum representation of that address, else
    3673               returns NIL.</para>
     4249            <para>
     4250              The "termination" mechanism is a way to have the garbage
     4251              collector run a function right before an object is about to
     4252              become garbage.  It is very similar to the "finalization"
     4253              mechanism which Java has.  It is not standard Common Lisp,
     4254              although other Lisp implementations have similar features.
     4255              It is useful when there is some sort of special cleanup,
     4256              deallocation, or releasing of resources which needs to happen
     4257              when a certain object is no longer being used.
     4258            </para>
     4259
     4260            <para>
     4261              When the garbage collector discovers that an object is no
     4262              longer referred to anywhere in the program, it deallocates
     4263              that object, freeing its memory.  However, if
     4264              <function>ccl:terminate-when-unreachable</function> has been
     4265              called on the object at any time, the garbage collector first
     4266              invokes the generic function <function>ccl:terminate</function>,
     4267              passing it the object as a parameter.
     4268            </para>
     4269
     4270            <para>
     4271              Therefore, to make termination do something useful, you need to
     4272              define a method on <function>ccl:terminate</function>.
     4273            </para>
     4274
     4275            <para>
     4276              Because calling
     4277              <function>ccl:terminate-when-unreachable</function> only
     4278              affects a single object, rather than all objects of its
     4279              class, you
     4280              may wish to put a call to it in the
     4281              <function>initialize-instance</function> method of a
     4282              class.  Of course, this is only appropriate if you do in fact
     4283              want to use termination for all objects of a given class.
     4284            </para>
    36744285          </refsect1>
     4286
     4287          <refsect1>
     4288            <title>Example</title>
     4289
     4290        <programlisting format="linespecific">
     4291          (defclass resource-wrapper ()
     4292            ((resource :accessor resource)))
     4293
     4294          (defmethod initialize-instance :after ((x resource-wrapper) &amp;rest initargs)
     4295             (ccl:terminate-when-unreachable x))
     4296
     4297          (defmethod ccl:terminate ((x resource-wrapper))
     4298             (when (resource x)
     4299                (deallocate (resource x))))</programlisting>
     4300          </refsect1>
     4301
     4302          <refsect1>
     4303            <title>See Also</title>
     4304
     4305            <simplelist type="inline">
     4306              <member><xref linkend="Tutorial--Allocating-Foreign-Data-on-the-Lisp-Heap"/></member>
     4307            </simplelist>
     4308          </refsect1>
     4309
    36754310    </refentry>
    36764311
    3677     <!-- ====================================  -->
    3678     <refentry id="f_foreign-symbol-address">
    3679           <indexterm zone="f_foreign-symbol-address">
    3680             <primary>foreign-symbol-address</primary>
     4312     <!-- ====================================  -->
     4313    <refentry id="f_unuse-interface-dir">
     4314          <indexterm zone="f_unuse-interface-dir">
     4315            <primary>unuse-interface-dir</primary>
    36814316          </indexterm>
    36824317
    36834318          <refnamediv>
    3684             <refname>FOREIGN-SYMBOL-ADDRESS</refname>
     4319            <refname>UNUSE-INTERFACE-DIR</refname>
    36854320            <refpurpose></refpurpose>
    36864321            <refclass>Function</refclass>
     
    36894324          <refsynopsisdiv>
    36904325            <synopsis>
    3691               <function>foreign-symbol-address</function> name
     4326              <function>unuse-interface-dir</function> dir-id
    36924327            </synopsis>
    36934328          </refsynopsisdiv>
     
    36984333            <variablelist>
    36994334              <varlistentry>
    3700                 <term>name</term>
    3701 
    3702                 <listitem>
    3703                       <para>A lisp string.</para>
     4335                <term>dir-id</term>
     4336
     4337                <listitem>
     4338                      <para>A keyword whose pname, mapped to lower case, names a
     4339                        subdirectory of &#34;ccl:headers;&#34; (or
     4340                        "ccl:darwin-headers;")</para>
    37044341                </listitem>
    37054342              </varlistentry>
     
    37104347            <title>Description</title>
    37114348
    3712             <para>Tries to resolve the address of the foreign symbol
    3713               name. If successful, returns that address encapsulated in
    3714               <link
    3715                  linkend="Referencing-and-Using-Foreign-Memory-Addresses">a
    3716                 MACPTR</link>, else returns NIL.</para>
     4349            <para>Tells &CCL; to remove the interface directory denoted by
     4350              dir-id from the list of interface directories which are
     4351              consulted for
     4352              foreign type and function information. Returns T if the directory
     4353              was on the search list, NIL otherwise.</para>
    37174354          </refsect1>
    37184355    </refentry>
    37194356
    3720     <!-- ====================================  -->
    3721     <refentry id="m_defcallback">
    3722           <indexterm zone="m_defcallback">
    3723             <primary>defcallback</primary>
    3724           </indexterm>
    3725 
    3726           <refnamediv>
    3727             <refname>DEFCALLBACK</refname>
    3728             <refpurpose></refpurpose>
    3729             <refclass>Macro</refclass>
    3730           </refnamediv>
    3731 
    3732           <refsynopsisdiv>
    3733             <synopsis>
    3734               <function>defcallback</function> name
    3735               ({arg-type-specifier var}* &optional; result-type-specifier)
    3736               &body; body
    3737             </synopsis>
    3738           </refsynopsisdiv>
    3739 
    3740           <refsect1>
    3741             <title>Values</title>
    3742 
    3743             <variablelist>
    3744               <varlistentry>
    3745                 <term>name</term>
    3746 
    3747                 <listitem>
    3748                       <para>A symbol which can be made into a special variable</para>
    3749                 </listitem>
    3750               </varlistentry>
    3751 
    3752               <varlistentry>
    3753                 <term>arg-type-specifer</term>
    3754 
    3755                 <listitem>
    3756                       <para>One of the foreign argument-type keywords,
    3757                         described above, or an equivalent <link
    3758                                                              linkend="Specifying-And-Using-Foreign-Types">foreign
    3759                           type specifier</link>.  In addition, if the keyword
    3760                         :WITHOUT-INTERRUPTS is specified, the callback will be
    3761                         executed with lisp interrupts disabled if the
    3762                         corresponding var is non-NIL. If :WITHOUT-INTERRUPTS
    3763                         is specified more than once, the rightmost instance
    3764                         wins.</para>
    3765                 </listitem>
    3766               </varlistentry>
    3767 
    3768               <varlistentry>
    3769                 <term>var</term>
    3770 
    3771                 <listitem>
    3772                       <para>A symbol (lisp variable), which will be bound to a
    3773                         value of the specified type.</para>
    3774                 </listitem>
    3775               </varlistentry>
    3776 
    3777               <varlistentry>
    3778                 <term>body</term>
    3779 
    3780                 <listitem>
    3781                       <para>A sequence of lisp forms, which should return a value
    3782                         which can be coerced to the specified result-type.</para>
    3783                 </listitem>
    3784               </varlistentry>
    3785             </variablelist>
    3786           </refsect1>
    3787 
    3788           <refsect1>
    3789             <title>Description</title>
    3790 
    3791             <para>Proclaims <varname>name</varname>
    3792               to be a special variable; sets its value to a
    3793               MACPTR which, when called by foreign code, calls a lisp function
    3794               which expects foreign arguments of the specified types and which
    3795               returns a foreign value of the specified result type. Any argument
    3796               variables which correspond to foreign arguments of type :ADDRESS
    3797               are bound to stack-allocated MACPTRs.</para>
    3798            
    3799             <para>If <varname>name</varname>
    3800               is already a callback function pointer, its value is
    3801               not changed; instead, it&#39;s arranged
    3802               that an
    3803               updated version of the lisp callback function will be called.
    3804               This feature allows for callback functions to be redefined
    3805               incrementally, just like Lisp functions are.</para>
    3806 
    3807             <para><function>defcallback</function>
    3808               returns the callback pointer, e.g., the
    3809               value of <varname>name</varname>.</para>
    3810           </refsect1>
    3811     </refentry>
    3812 
    3813 
    3814     <!-- ====================================  -->
    3815     <refentry id="rm_sharpsign-underscore">
    3816       <indexterm zone="rm_sharpsign-underscore">
    3817             <primary>#_</primary>
    3818       </indexterm>
    3819 
    3820       <refnamediv>
    3821             <refname>#_</refname>
    3822             <refpurpose></refpurpose>
    3823             <refclass>Reader Macro</refclass>
    3824       </refnamediv>
    3825 
    3826       <refsect1>
    3827             <title>Description</title>
    3828 
    3829             <para>Reads a symbol from the current input stream, with *PACKAGE*
    3830               bound to the &#34;OS&#34; package and with readtable-case preserved.</para>
    3831            
    3832             <para>Does a lookup on that symbol in <link
    3833                                                      linkend="The-Interface-Database">the &CCL; interface
    3834                 database</link>, signalling an error if no foreign function
    3835               information can be found for the symbol in any active <link
    3836                                                                        linkend="Using-Interface-Directories">interface
    3837                 directory</link>.</para>
    3838 
    3839             <para>Notes the foreign function information, including the foreign
    3840               function&#39;s return type, the number and type of the foreign
    3841               function&#39;s required arguments, and an indication of whether or
    3842               not the function accepts additional arguments (via e.g., the
    3843               &#34;varargs&#34; mechanism in C).</para>
    3844 
    3845             <para>Defines a macroexpansion function on the symbol, which expand
    3846               macro calls involving the symbol into EXTERNAL-CALL forms where
    3847               foreign argument type specifiers for required arguments and the
    3848               return value specifer are provided from the information in the
    3849               database.</para>
    3850 
    3851             <para>Returns the symbol.</para>
    3852 
    3853             <para>The effect of these steps is that it&#39;s possible to call
    3854               foreign functions that take fixed numbers of arguments by simply
    3855               providing argument values, as in:</para>
    3856 
    3857             <programlisting format="linespecific">(#_isatty fd)
    3858           (#_read fd buf n)</programlisting>
    3859 
    3860             <para>and to call foreign functions that take variable numbers of
    3861               arguments by specifying the types of non-required args, as in:</para>
    3862 
    3863             <programlisting format="linespecific">(with-cstrs ((format-string &#34;the answer is: %d&#34;))
    3864           (#_printf format-string :int answer))</programlisting>
    3865 
    3866         <para>You can query whether a given name is defined in the
    3867           interface databases by appending the '?' character to the reader
    3868           macro; for example:</para>
    3869 
    3870         <programlisting>
    3871           CL-USER&gt; #_?printf
    3872           T
    3873           CL-USER&gt; #_?foo
    3874           NIL
    3875         </programlisting>
    3876 
    3877       </refsect1>
    3878     </refentry>
    3879 
    3880     <!-- ====================================  -->
    3881     <refentry id="rm_sharpsign-ampersand">
    3882       <indexterm zone="rm_sharpsign-ampersand">
    3883             <primary>#&amp;</primary>
    3884       </indexterm>
    3885 
    3886       <refnamediv>
    3887             <refname>#&amp;</refname>
    3888             <refpurpose></refpurpose>
    3889             <refclass>Reader Macro</refclass>
    3890       </refnamediv>
    3891 
    3892       <refsect1>
    3893             <title>Description</title>
    3894 
    3895             <para>In &CCL; 1.2 and later, the #&amp; reader macro can be used to
    3896               access foreign variables; this functionality depends on the presence of
    3897               &#34;vars.cdb&#34; files in the interface database. The current behavior
    3898               of the #&amp; reader macro is to:</para>
    3899 
    3900             <para>Read a symbol from the current input stream, with *PACKAGE*
    3901               bound to the &#34;OS&#34; package and with readtable-case preserved.</para>
    3902            
    3903             <para>Use that symbol&#39;s pname to access the &CCL; interface
    3904               database, signalling an error if no appropriate foreign variable
    3905               information can be found with that name in any active interface
    3906               directory.</para>
    3907 
    3908             <para>Use type information recorded in the database to construct a
    3909               form which can be used to access the foreign variable, and return
    3910               that form.</para>
    3911 
    3912             <para>Please note that the set of foreign variables declared in header files
    3913               may or may not match the set of foreign variables exported from
    3914               libraries (we&#39;re generally talking about C and Unix here ...). When
    3915               they do match, the form constructed by the #&amp; reader macro manages the
    3916               details of resolving and tracking changes to the foreign variable&#39;s
    3917               address.</para>
    3918 
    3919             <para>Future extensions (via prefix arguments to the reader macro) may
    3920               offer additional behavior; it might be convenient (for instance) to be
    3921               able to access the address of a foreign variable without dereferencing
    3922               that address.</para>
    3923 
    3924             <para>Foreign variables in C code tend to be platform- and
    3925               packge-specific (the canonical example - &#34;errno&#34; - is typically
    3926               not a variable when threads are involved. )</para>
    3927 
    3928             <para>In LinuxPPC, </para>
    3929 
    3930             <programlisting>? #&amp;stderr</programlisting>
    3931 
    3932             <para>returns a pointer to the stdio error stream (&#34;stderr&#34; is a
    3933               macro under OSX/Darwin).</para>
    3934 
    3935             <para>On both LinuxPPC and DarwinPPC, </para>
    3936 
    3937             <programlisting>? #&amp;sys_errlist</programlisting>
    3938 
    3939             <para>returns a pointer to a C array of C error message strings.</para>
    3940 
    3941         <para>You can query whether a given name is defined in the
    3942           interface databases by appending the '?' character to the reader
    3943           macro; for example:</para>
    3944 
    3945         <programlisting>
    3946           CL-USER&gt; #&amp;?sys_errlist
    3947           T
    3948           CL-USER&gt; #&amp;?foo
    3949           NIL
    3950         </programlisting>
    3951 
    3952       </refsect1>
    3953     </refentry>
    3954 
    3955     <!-- ====================================  -->
    3956     <refentry id="rm_sharpsign-dollarsign">
    3957       <indexterm zone="rm_sharpsign-dollarsign">
    3958         <primary>#$</primary>
    3959       </indexterm>
    3960      
    3961       <refnamediv>
    3962         <refname>#$</refname>
    3963         <refpurpose></refpurpose>
    3964         <refclass>Reader Macro</refclass>
    3965       </refnamediv>
    3966      
    3967       <refsect1>
    3968         <title>Description</title>
    3969        
    3970             <para>In &CCL; 0.14.2 and later, the #? reader macro can be used
    3971               to access foreign constants; this functionality depends on the
    3972               presence of &#34;constants.cdb&#34; files in the interface
    3973               database. The current behavior of the #$ reader macro is
    3974               to:</para>
    3975 
    3976             <para>Read a symbol from the current input stream, with
    3977               *PACKAGE* bound to the &#34;OS&#34; package and with
    3978               readtable-case preserved.</para>
    3979            
    3980             <para>Use that symbol&#39;s pname to access the &CCL; interface
    3981               database, signalling an error if no appropriate foreign constant
    3982               information can be found with that name in any active interface
    3983               directory.</para>
    3984 
    3985             <para>Use type information recorded in the database to construct a
    3986               form which can be used to access the foreign constant, and return
    3987               that form.</para>
    3988 
    3989             <para>Please note that the set of foreign constants declared in
    3990               header files may or may not match the set of foreign constants
    3991               exported from libraries. When they do match, the form
    3992               constructed by the #$ reader macro manages the details of
    3993               resolving and tracking changes to the foreign constant's
    3994               address.</para>
    3995 
    3996         <para>You can query whether a given name is defined in the
    3997           interface databases by appending the '?' character to the reader
    3998           macro; for example:</para>
    3999 
    4000         <programlisting>
    4001           CL-USER&gt; #$?SO_KEEPALIVE
    4002           T
    4003           CL-USER&gt; #$?foo
    4004           NIL
    4005         </programlisting>
    4006 
    4007       </refsect1>
    4008     </refentry>
    4009 
    4010     <!-- ====================================  -->
    4011     <refentry id="rm_sharpsign-slash">
    4012       <indexterm zone="rm_sharpsign-slash">
    4013         <primary>#/</primary>
    4014       </indexterm>
    4015      
    4016       <refnamediv>
    4017         <refname>#/</refname>
    4018         <refpurpose></refpurpose>
    4019         <refclass>Reader Macro</refclass>
    4020       </refnamediv>
    4021      
    4022       <refsect1>
    4023         <title>Description</title>
    4024        
    4025             <para>In &CCL; 1.2 and later, the #/ reader macro can be used to
    4026               access foreign functions on the Darwin platform. The current
    4027               behavior of the #/ reader macro is to:</para>
    4028 
    4029             <para>Read a symbol from the current input stream, with
    4030               *PACKAGE* bound to the "NEXTSTEP-FUNCTIONS" package, with
    4031               readtable-case preserved, and with any colons included.</para>
    4032 
    4033         <para>Do limited sanity-checking on the resulting symbol; for
    4034           example, any name that contains at least one colon is required
    4035           also to end with a colon, to conform to Objective-C
    4036           method-naming conventions.</para>
    4037 
    4038         <para>Export the resulting symbol from the "NEXTSTEP-FUNCTIONS"
    4039           package and return it.</para>
    4040 
    4041         <para>For example, reading "#/alloc" interns and returns
    4042           NEXTSTEP-FUNCTIONS:|alloc|. Reading "#/initWithFrame:" interns
    4043           and returns NEXTSTEP-FUNCTIONS:|initWithFrame:|.</para>
    4044 
    4045         <para>A symbol read using this macro can be used as an operand
    4046           in most places where an Objective-C message name can be used, such as
    4047           in the (OBJ:@SELECTOR ...) construct.</para>
    4048 
    4049         <para>Please note: the reader macro is not rigorous about
    4050           enforcing Objective-C method-naming conventions. Despite the
    4051           simple checking done by the reader macro, it may still be
    4052           possible to use it to construct invalid names.</para>
    4053 
    4054         <para>The act of interning a new symbol in the
    4055           NEXTSTEP-FUNCTIONS package triggers an interface database lookup
    4056           of Objective-C methods with the corresponding message name.  If any
    4057           such information is found, a special type of dispatching
    4058           function is created and initialized and the new symbol is given
    4059           the newly-created dispatching function as its function
    4060           definition.</para>
    4061 
    4062         <para>The dispatching knows how to call declared Objective-C methods
    4063           defined on the message. In many cases, all methods have the same
    4064           foreign type signature, and the dispatching function merely
    4065           passes any arguments that it receives to a function that does an
    4066           Objective-C message send with the indicated foreign argument and return
    4067           types. In other cases, where different Objective-C messages have
    4068           different type signatures, the dispatching function tries to
    4069           choose a function that handles the right type signature based on
    4070           the class of the dispatching function's first argument.</para>
    4071            
    4072         <para>If new information about Objective-C methods is introduced
    4073           (e.g., by using additional interface files or as Objective-C
    4074           methods are defined from lisp), the dispatch function is
    4075           reinitialized to recognize newly-introduced foreign type
    4076           signatures.</para>
    4077 
    4078         <para>The argument and result coercion that the bridge has
    4079           tradionally supported is supported by the new mechanism (e.g.,
    4080           :&lt;BOOL&gt; arguments can be specified as lisp booleans and :&lt;BOOL&gt;
    4081           results are returned as lisp boolean values, and an argument
    4082           value of NIL is coerced to a null pointer if the corresponding
    4083           argument type is :ID.</para>
    4084 
    4085         <para>Some Objective-C methods accept variable numbers of
    4086           arguments; the foreign types of non-required arguments are
    4087           determined by the lisp types of those arguments (e.g., integers
    4088           are passed as integers, floats as floats, pointers as pointers,
    4089           record types by reference.)</para>
    4090 
    4091         <para>Examples:</para>
    4092 
    4093         <programlisting>
    4094           ;;; #/alloc is a known message.
    4095           ? #'#/alloc
    4096           #&lt;OBJC-DISPATCH-FUNCTION NEXTSTEP-FUNCTIONS:|alloc| #x300040E94EBF&gt;
    4097           ;;; Sadly, #/foo is not ...
    4098           ? #'#/foo
    4099           &gt; Error: Undefined function: NEXTSTEP-FUNCTIONS:|foo|
    4100 
    4101           ;;; We can send an "init" message to a newly-allocated instance of
    4102           ;;; "NSObject" by:
    4103 
    4104           (send (send ns:ns-object 'alloc) 'init)
    4105 
    4106           ;;; or by
    4107 
    4108           (#/init (#/alloc ns:ns-object))
    4109         </programlisting>
    4110 
    4111         <para>Objective-C methods that "return" structures return them
    4112           as garbage-collectable pointers when called via dispatch
    4113           functions.  For example, if "my-window" is an NS:NS-WINDOW
    4114           instance, then</para>
    4115 
    4116         <programlisting>
    4117           (#/frame my-window)
    4118         </programlisting>
    4119 
    4120         <para>returns a garbage-collectable pointer to a structure that
    4121           describes that window's frame rectangle. This convention means
    4122           that there's no need to use SLET or special structure-returning
    4123           message send syntax; keep in mind, though, that #_malloc,
    4124           #_free, and the GC are all involved in the creation and eventual
    4125           destruction of structure-typed return values. In some programs
    4126           these operations may have an impact on performance.</para>
    4127 
    4128       </refsect1>
    4129     </refentry>
    4130 
    4131     <!-- ====================================  -->
    4132     <refentry id="rm_sharpsign-greaterthan">
    4133       <indexterm zone="rm_sharpsign-greaterthan">
    4134         <primary>#&gt;</primary>
    4135       </indexterm>
    4136      
    4137       <refnamediv>
    4138         <refname>#&gt;</refname>
    4139         <refpurpose></refpurpose>
    4140         <refclass>Reader Macro</refclass>
    4141       </refnamediv>
    4142      
    4143       <refsect1>
    4144         <title>Description</title>
    4145        
    4146         <para>In &CCL; 1.2 and later, the #&gt; reader macro reads
    4147           the following text as a keyword, preserving the case of the
    4148           text. For example:</para>
    4149 
    4150         <programlisting>
    4151           CL-USER&gt; #&gt;FooBar
    4152           :&lt;F&gt;OO&lt;B&gt;AR
    4153         </programlisting>
    4154 
    4155         <para>The resulting keyword can be used as the name of foreign
    4156           types, records, and accessors.</para>
    4157        
    4158       </refsect1>
    4159     </refentry>
    4160 
    4161 
    4162     <!-- ====================================  -->
     4357   <!-- ====================================  -->
    41634358    <refentry id="f_use-interface-dir">
    41644359          <indexterm zone="f_use-interface-dir">
     
    42434438    </refentry>
    42444439
    4245     <!-- ====================================  -->
    4246     <refentry id="f_unuse-interface-dir">
    4247           <indexterm zone="f_unuse-interface-dir">
    4248             <primary>unuse-interface-dir</primary>
    4249           </indexterm>
    4250 
    4251           <refnamediv>
    4252             <refname>UNUSE-INTERFACE-DIR</refname>
    4253             <refpurpose></refpurpose>
    4254             <refclass>Function</refclass>
    4255           </refnamediv>
    4256 
    4257           <refsynopsisdiv>
    4258             <synopsis>
    4259               <function>unuse-interface-dir</function> dir-id
    4260             </synopsis>
    4261           </refsynopsisdiv>
    4262 
    4263           <refsect1>
    4264             <title>Values</title>
    4265 
    4266             <variablelist>
    4267               <varlistentry>
    4268                 <term>dir-id</term>
    4269 
    4270                 <listitem>
    4271                       <para>A keyword whose pname, mapped to lower case, names a
    4272                         subdirectory of &#34;ccl:headers;&#34; (or
    4273                         "ccl:darwin-headers;")</para>
    4274                 </listitem>
    4275               </varlistentry>
    4276             </variablelist>
    4277           </refsect1>
    4278 
    4279           <refsect1>
    4280             <title>Description</title>
    4281 
    4282             <para>Tells &CCL; to remove the interface directory denoted by
    4283               dir-id from the list of interface directories which are
    4284               consulted for
    4285               foreign type and function information. Returns T if the directory
    4286               was on the search list, NIL otherwise.</para>
    4287           </refsect1>
    4288     </refentry>
    4289 
    4290     <!-- ====================================  -->
    4291     <refentry id="f_terminate-when-unreachable">
    4292           <indexterm zone="f_terminate-when-unreachable">
    4293             <primary>terminate-when-unreachable</primary>
    4294           </indexterm>
    4295 
    4296           <refnamediv>
    4297             <refname>TERMINATE-WHEN-UNREACHABLE</refname>
    4298             <refpurpose></refpurpose>
    4299             <refclass>Function</refclass>
    4300           </refnamediv>
    4301 
    4302           <refsynopsisdiv>
    4303             <synopsis>
    4304               <function>terminate-when-unreachable</function> object
    4305             </synopsis>
    4306           </refsynopsisdiv>
    4307 
    4308           <refsect1>
    4309             <title>Values</title>
    4310 
    4311             <variablelist>
    4312               <varlistentry>
    4313                 <term>object</term>
    4314 
    4315                 <listitem>
    4316                       <para>A CLOS object of a class for which there exists
    4317                         a method of the generic function
    4318                         <function>ccl:terminate</function>.
    4319                       </para>
    4320                 </listitem>
    4321               </varlistentry>
    4322             </variablelist>
    4323           </refsect1>
    4324 
    4325           <refsect1>
    4326             <title>Description</title>
    4327 
    4328             <para>
    4329               The "termination" mechanism is a way to have the garbage
    4330               collector run a function right before an object is about to
    4331               become garbage.  It is very similar to the "finalization"
    4332               mechanism which Java has.  It is not standard Common Lisp,
    4333               although other Lisp implementations have similar features.
    4334               It is useful when there is some sort of special cleanup,
    4335               deallocation, or releasing of resources which needs to happen
    4336               when a certain object is no longer being used.
    4337             </para>
    4338 
    4339             <para>
    4340               When the garbage collector discovers that an object is no
    4341               longer referred to anywhere in the program, it deallocates
    4342               that object, freeing its memory.  However, if
    4343               <function>ccl:terminate-when-unreachable</function> has been
    4344               called on the object at any time, the garbage collector first
    4345               invokes the generic function <function>ccl:terminate</function>,
    4346               passing it the object as a parameter.
    4347             </para>
    4348 
    4349             <para>
    4350               Therefore, to make termination do something useful, you need to
    4351               define a method on <function>ccl:terminate</function>.
    4352             </para>
    4353 
    4354             <para>
    4355               Because calling
    4356               <function>ccl:terminate-when-unreachable</function> only
    4357               affects a single object, rather than all objects of its
    4358               class, you
    4359               may wish to put a call to it in the
    4360               <function>initialize-instance</function> method of a
    4361               class.  Of course, this is only appropriate if you do in fact
    4362               want to use termination for all objects of a given class.
    4363             </para>
    4364           </refsect1>
    4365 
    4366           <refsect1>
    4367             <title>Example</title>
    4368 
    4369         <programlisting format="linespecific">
    4370           (defclass resource-wrapper ()
    4371             ((resource :accessor resource)))
    4372 
    4373           (defmethod initialize-instance :after ((x resource-wrapper) &amp;rest initargs)
    4374              (ccl:terminate-when-unreachable x))
    4375 
    4376           (defmethod ccl:terminate ((x resource-wrapper))
    4377              (when (resource x)
    4378                 (deallocate (resource x))))</programlisting>
    4379           </refsect1>
    4380 
    4381           <refsect1>
    4382             <title>See Also</title>
    4383 
    4384             <simplelist type="inline">
    4385               <member><xref linkend="Tutorial--Allocating-Foreign-Data-on-the-Lisp-Heap"/></member>
    4386             </simplelist>
    4387           </refsect1>
    4388 
    4389     </refentry>
    4390 
    43914440  </sect1>
    43924441</chapter>
  • trunk/source/doc/src/glossary.xml

    r8820 r8894  
    123123        </glossentry>
    124124   
     125        <glossentry id="lisp_image">
     126          <glossterm>image</glossterm>
     127
     128          <glossdef>
     129
     130                <para>The in-memory state of a running Lisp system, containing
     131                functions, data structures, variables, and so on. Also, a file
     132                containing archived versions of these data in a format that
     133                can be loaded and reconstituted by the
     134                Lisp <glossterm linkend="lisp_image">kernel</glossterm>. A
     135                working &CCL; system consists of the kernel and
     136                an <glossterm linkend="lisp_image">image</glossterm>.</para>
     137
     138          </glossdef>
     139
     140        </glossentry>
     141   
    125142        <glossentry id="InterfaceBuilder">
    126143          <glossterm>InterfaceBuilder</glossterm>
     
    132149                elements for <glossterm linkend="Cocoa">Cocoa</glossterm>
    133150                applications.</para>
     151
     152          </glossdef>
     153
     154        </glossentry>
     155   
     156  </glossdiv>
     157
     158  <glossdiv id="K">
     159        <!-- ******************** K ********************  -->
     160        <title>K</title>
     161
     162        <glossentry id="lisp_kernel">
     163          <glossterm>kernel</glossterm>
     164
     165          <glossdef>
     166
     167                <para>The binary executable program that implements the lowest
     168                levels of the Lisp system. A working &CCL; system consists of
     169                the kernel and
     170                an <glossterm linkend="lisp_image">image</glossterm>.</para>
    134171
    135172          </glossdef>
     
    284321        <title>T</title>
    285322
     323        <glossentry id="toplevel_function">
     324          <glossterm>toplevel function</glossterm>
     325
     326          <glossdef>
     327
     328                <para>The function executed by Lisp automatically once its
     329                startup is complete. &CCL;'s default toplevel is the
     330                interactive <glossterm linkend="REPL">read-eval-print
     331                loop</glossterm> that you normally use to interact with
     332                Lisp. You can, however, replace the toplevel with a function
     333                of your own design, changing &CCL; from a Lisp development
     334                system into some tool of your making.</para>
     335
     336          </glossdef>
     337
     338        </glossentry>
     339   
    286340        <glossentry id="type-specifier">
    287341          <glossterm>type-specifier</glossterm>
  • trunk/source/doc/src/ide.xml

    r8822 r8894  
    194194
    195195  <sect1><title>The Application Builder</title>
    196    
     196    <anchor id="application_builder"/>
    197197    <para>One important feature of the IDE currently has no Cocoa user
    198198      interface: the application builder. The application builder
  • trunk/source/doc/src/objc-bridge.xml

    r8820 r8894  
    11<?xml version="1.0" encoding="utf-8"?>
    22<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
    3 <!ENTITY rest "<varname>&amp;rest</varname>">
    4 <!ENTITY key "<varname>&amp;key</varname>">
    5 <!ENTITY optional "<varname>&amp;optional</varname>">
    6 <!ENTITY body "<varname>&amp;body</varname>">
    7 <!ENTITY aux "<varname>&amp;aux</varname>">
    8 <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    9 <!ENTITY CCL "Clozure CL">
    10 ]>
    11   <chapter id="The-Objective-C-Bridge">
    12     <title>The Objective-C Bridge</title>
    13 
    14     <para>OS X APIs use a language called "Objective C", which is
    15     built on C.  The Objective-C bridge makes it possible to work with
    16     ObjC objects and classes from Lisp, and to define classes in Lisp
    17     which can be used by ObjC.</para>
    18     <para>The ultimate purpose of the ObjC and Cocoa bridges is to
    19     make Cocoa as easy as possible to use from &CCL;, in order to
    20     support the development of GUI applications and IDEs.  The
     3          <!ENTITY rest "<varname>&amp;rest</varname>">
     4          <!ENTITY key "<varname>&amp;key</varname>">
     5          <!ENTITY optional "<varname>&amp;optional</varname>">
     6          <!ENTITY body "<varname>&amp;body</varname>">
     7          <!ENTITY aux "<varname>&amp;aux</varname>">
     8          <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
     9          <!ENTITY CCL "Clozure CL">
     10          ]>
     11<chapter id="The-Objective-C-Bridge">
     12  <title>The Objective-C Bridge</title>
     13
     14  <para>Mac OS X APIs use a language called Objective-C, which is
     15    approximately C with some object-oriented extensions modeled on
     16    Smalltalk.  The Objective-C bridge makes it possible to work with
     17    Objective-C objects and classes from Lisp, and to define classes
     18    in Lisp which can be used by Objective-C.</para>
     19  <para>The ultimate purpose of the Objective-C and Cocoa bridges is
     20    to make Cocoa (the standard user-interface framework on Mac OS X)
     21    as easy as possible to use from &CCL;, in order to support the
     22    development of GUI applications and IDEs on Mac OS X (and on any
     23    platform that supports Objective-C, such as GNUStep).  The
    2124    eventual goal, which is much closer than it used to be, is
    22     complete integration of Cocoa into CLOS (whatever that
    23     means).</para>
    24     <para>The current release provides Lisp-like syntax and naming
    25     conventions for the basic ObjC operations, with automatic type
     25    complete integration of Cocoa into CLOS.</para>
     26  <para>The current release provides Lisp-like syntax and naming
     27    conventions for the basic Objective-C operations, with automatic type
    2628    processing and messages checked for validity at compile-time.  It
    2729    also provides some convenience facilities for working with
    2830    Cocoa.</para>
    2931
    30     <sect1 id="Using-Objective-C-Classes">
    31       <title>Using Objective-C Classes</title>
    32 
    33       <para>The class of most "standard" CLOS classes is the class
    34       named STANDARD-CLASS. In the Objective-C object model, each
    35       class is an instance of a (usually unique) metaclass, which is
    36       itself an instance of a "base" metaclass (often the metaclass of
    37       the class named "NSObject".) So, the Objective-C class named
    38       "NSWindow" and the ObjC class "NSArray" are (sole) instances of
     32  <sect1 id="Using-Objective-C-Classes">
     33    <title>Using Objective-C Classes</title>
     34
     35    <para>The class of most standard CLOS classes is named
     36      STANDARD-CLASS. In the Objective-C object model, each class is
     37      an instance of a (usually unique) metaclass, which is itself an
     38      instance of a "base" metaclass (often the metaclass of the class
     39      named "NSObject".) So, the Objective-C class named "NSWindow"
     40      and the Objective-C class "NSArray" are (sole) instances of
    3941      their distinct metaclasses whose names are also "NSWindow" and
    4042      "NSArray", respectively. (In the Objective-C world, it's much
    4143      more common and useful to specialize class behavior such as
    4244      instance allocation.)</para>
    43       <para>When foreign libraries containing Objective-C classes are first
    44 loaded, the classes they contain are identified. The foreign class
    45 name, such as "NSWindow", is mapped to an external symbol in the
    46 "NS" package via the bridge's translation rules, such as NS:NS-WINDOW.
    47 A similar transformation happens to the
    48 metaclass name, with a "+" prepended, yielding something like
    49 NS:+NS-WINDOW.</para>
    50       <para>These classes are integrated into CLOS such that the
    51 metaclass is an instance of the class OBJC:OBJC-METACLASS and
    52 the class
    53 is an instance of the metaclass. SLOT-DESCRIPTION metaobjects are
    54 created for each instance variable, and the class and metaclass go
    55 through something very similar to the "standard" CLOS class
    56 initialization protocol (with a difference being that these classes
    57 have already been allocated.)</para>
    58       <para>Performing all this initialization, which is done when you
    59 (require "COCOA"), currently takes several
    60 seconds; it could conceivably be sped up some, but it's never likely
    61 to be fast.</para>
    62       <para>When the process is complete, CLOS is aware of several hundred
    63 new ObjC classes and their metaclasses. &CCL;'s runtime system can
    64 reliably recognize MACPTRs to ObjC classes as being CLASS objects, and
    65 can (fairly reliably but heuristically) recognize instances of those
    66 classes (though there are complicating factors here; see below.)
    67 SLOT-VALUE can be used to access (and, with care, set) instance
    68 variables in ObjC instances. To see this, do:</para>
    69       <programlisting>
    70 ? (require "COCOA")
    71 </programlisting>
    72       <para>and, after waiting a bit longer for a Cocoa listener window to
    73 appear, activate that Cocoa listener and do:</para>
    74       <programlisting>? (describe (ccl::send ccl::*NSApp* 'key-window))
    75 </programlisting>
    76       <para>This sends a message asking for the key window, which is the window
    77 that has the input focus (often the frontmost), and then describes
    78 it. As we can see, NS:NS-WINDOWs have lots of interesting slots.</para>
    79     </sect1>
    80 
    81     <sect1 id="Instantiating-Objective-C-Objects">
    82       <title>Instantiating Objective-C Objects</title>
    83       <para>Making an instance of an ObjC class (whether the class in
     45    <para>When &CCL; first loads foreign libraries containing
     46      Objective-C classes, it identifies the classes they contain. The
     47      foreign class name, such as "NSWindow", is mapped to an external
     48      symbol in the "NS" package via the bridge's translation rules,
     49      such as NS:NS-WINDOW.  A similar transformation happens to the
     50      metaclass name, with a "+" prepended, yielding something like
     51      NS:+NS-WINDOW.</para>
     52    <para>These classes are integrated into CLOS such that the
     53      metaclass is an instance of the class OBJC:OBJC-METACLASS and
     54      the class
     55      is an instance of the metaclass. SLOT-DESCRIPTION metaobjects are
     56      created for each instance variable, and the class and metaclass go
     57      through something very similar to the "standard" CLOS class
     58      initialization protocol (with a difference being that these classes
     59      have already been allocated.)</para>
     60    <para>Performing all this initialization, which is done when you
     61      (require "COCOA"), currently takes several
     62      seconds; it could conceivably be sped up some, but it's never likely
     63      to be fast.</para>
     64    <para>When the process is complete, CLOS is aware of several hundred
     65      new Objective-C classes and their metaclasses. &CCL;'s runtime system can
     66      reliably recognize MACPTRs to Objective-C classes as being CLASS objects, and
     67      can (fairly reliably but heuristically) recognize instances of those
     68      classes (though there are complicating factors here; see below.)
     69      SLOT-VALUE can be used to access (and, with care, set) instance
     70      variables in Objective-C instances. To see this, do:</para>
     71    <programlisting>
     72      ? (require "COCOA")
     73    </programlisting>
     74    <para>and, after waiting a bit longer for a Cocoa listener window to
     75      appear, activate that Cocoa listener and do:</para>
     76    <programlisting>? (describe (ccl::send ccl::*NSApp* 'key-window))
     77    </programlisting>
     78    <para>This sends a message asking for the key window, which is the window
     79      that has the input focus (often the frontmost), and then describes
     80      it. As we can see, NS:NS-WINDOWs have lots of interesting slots.</para>
     81  </sect1>
     82
     83  <sect1 id="Instantiating-Objective-C-Objects">
     84    <title>Instantiating Objective-C Objects</title>
     85    <para>Making an instance of an Objective-C class (whether the class in
    8486      question is predefined or defined by the application) involves
    8587      calling MAKE-INSTANCE with the class and a set of initargs as
     
    8789      initializing (with INITIALIZE-INSTANCE) an object allocated with
    8890      ALLOCATE-INSTANCE.</para>
    89       <para>For example, you can create an ns:ns-number like this:</para>
    90       <programlisting>
    91 ? (make-instance 'ns:ns-number :init-with-int 42)
    92 #&lt;NS-CF-NUMBER 42 (#x85962210)>
    93 </programlisting>
    94       <para>It's worth looking at how this would be done if you were
     91    <para>For example, you can create an ns:ns-number like this:</para>
     92    <programlisting>
     93      ? (make-instance 'ns:ns-number :init-with-int 42)
     94      #&lt;NS-CF-NUMBER 42 (#x85962210)>
     95    </programlisting>
     96    <para>It's worth looking at how this would be done if you were
    9597      writing in Objective C:</para>
    96       <programlisting>
    97 [[NSNumber alloc] initWithInt: 42]
    98       </programlisting>
    99       <para>Allocating an instance of an ObjC class involves sending the
    100 class an "alloc" message, and then using those initargs that
    101 <emphasis>don't</emphasis> correspond to slot initags as the
    102 "init" message to be sent to the newly-allocated instance.  So, the
    103 example above could have been done more verbosely as:</para>
    104       <programlisting>
    105 ? (defvar *n* (ccl::send (find-class 'ns:ns-number) 'alloc))
    106 *N*
    107 
    108 ? (setq *n* (ccl::send *n* :init-with-int 42))
    109 #&lt;NS-CF-NUMBER 42 (#x16D340)>
    110 </programlisting>
    111       <para>That setq is important; this is a case where init
    112 decides to replace the object and return the new one, instead
    113 of modifying the existing one.
    114 In fact, if you leave out the setq and
    115 then try to view the value of *N*, &CCL; will freeze.  There's
    116 little reason to ever do it this way; this is just to show
    117 what's going on.</para>
    118       <para>You've seen that an ObjC initialization method doesn't have to
    119 return the same object it was passed.  In fact, it doesn't have
    120 to return any object at all; in this case, the initialization fails
    121 and make-instance returns nil.</para>
    122       <para>In some special cases, such as loading an ns:ns-window-controller
    123 from a .nib file, it may be necessary for you to pass the
    124 instance itself as one of the parameters to the initialization
    125 method.  It goes like this:</para>
    126       <programlisting>
    127 ? (defvar *controller*
    128           (make-instance 'ns:ns-window-controller))
    129 *CONTROLLER*
    130 
    131 ? (setq *controller*
    132         (ccl::send *controller*
    133                    :init-with-window-nib-name #@"DataWindow"
    134                    :owner *controller*))
    135 #&lt;NS-WINDOW-CONTROLLER &lt;NSWindowController: 0x1fb520> (#x1FB520)>
    136 </programlisting>
    137       <para>This example calls (make-instance) with no initargs.  When you
    138 do this, the object is only allocated, and not initialized.  It
    139 then sends the "init" message to do the initialization by hand.</para>
    140     </sect1>
    141 
    142     <sect1 id="Calling-Objective-C-Methods">
    143       <title>Calling Objective-C Methods</title>
    144       <para>In Objective-C, methods are called "messages", and there's
     98    <programlisting>
     99      [[NSNumber alloc] initWithInt: 42]
     100    </programlisting>
     101    <para>Allocating an instance of an Objective-C class involves sending the
     102      class an "alloc" message, and then using those initargs that
     103      <emphasis>don't</emphasis> correspond to slot initags as the
     104      "init" message to be sent to the newly-allocated instance.  So, the
     105      example above could have been done more verbosely as:</para>
     106    <programlisting>
     107      ? (defvar *n* (ccl::send (find-class 'ns:ns-number) 'alloc))
     108      *N*
     109
     110      ? (setq *n* (ccl::send *n* :init-with-int 42))
     111      #&lt;NS-CF-NUMBER 42 (#x16D340)>
     112    </programlisting>
     113    <para>That setq is important; this is a case where init
     114      decides to replace the object and return the new one, instead
     115      of modifying the existing one.
     116      In fact, if you leave out the setq and
     117      then try to view the value of *N*, &CCL; will freeze.  There's
     118      little reason to ever do it this way; this is just to show
     119      what's going on.</para>
     120    <para>You've seen that an Objective-C initialization method doesn't have to
     121      return the same object it was passed.  In fact, it doesn't have
     122      to return any object at all; in this case, the initialization fails
     123      and make-instance returns nil.</para>
     124    <para>In some special cases, such as loading an ns:ns-window-controller
     125      from a .nib file, it may be necessary for you to pass the
     126      instance itself as one of the parameters to the initialization
     127      method.  It goes like this:</para>
     128    <programlisting>
     129      ? (defvar *controller*
     130      (make-instance 'ns:ns-window-controller))
     131      *CONTROLLER*
     132
     133      ? (setq *controller*
     134      (ccl::send *controller*
     135      :init-with-window-nib-name #@"DataWindow"
     136      :owner *controller*))
     137      #&lt;NS-WINDOW-CONTROLLER &lt;NSWindowController: 0x1fb520> (#x1FB520)>
     138    </programlisting>
     139    <para>This example calls (make-instance) with no initargs.  When you
     140      do this, the object is only allocated, and not initialized.  It
     141      then sends the "init" message to do the initialization by hand.</para>
     142  </sect1>
     143
     144  <sect1 id="Calling-Objective-C-Methods">
     145    <title>Calling Objective-C Methods</title>
     146    <para>In Objective-C, methods are called "messages", and there's
    145147      a special syntax to send a message to an object:</para>
    146       <programlisting>
    147 [w alphaValue]
    148 [w setAlphaValue: 0.5]
    149 [v mouse: p inRect: r]
    150       </programlisting>
    151       <para>The first line sends the method "alphaValue" to the object
     148    <programlisting>
     149      [w alphaValue]
     150      [w setAlphaValue: 0.5]
     151      [v mouse: p inRect: r]
     152    </programlisting>
     153    <para>The first line sends the method "alphaValue" to the object
    152154      <literal>w</literal>, with no parameters.  The second line sends
    153155      the method "setAlphaValue", with the parameter 0.5.  The third
     
    155157      with the parameters <literal>p</literal> and
    156158      <literal>r</literal>.</para>
    157       <para>In Lisp, these same three lines are:</para>
    158       <programlisting>
    159 (send w 'alpha-value)
    160 (send w :set-alpha-value 0.5)
    161 (send v :mouse p :in-rect r)
    162 </programlisting>
    163       <para>Notice that when a method has no parameters, its name is an ordinary
    164 symbol (it doesn't matter what package the symbol is in, as
    165 only its name is checked).  When a method has parameters,
    166 each part of its name is a keyword, and the keywords alternate
    167 with the values.</para>
    168       <para>These two lines break those rules, and both  will
    169 result in error messages:</para>
    170       <programlisting>
    171 (send w :alpha-value)
    172 (send w 'set-alpha-value 0.5)
    173 </programlisting>
    174       <para>Instead of (send), you can also invoke (send-super), with the
    175 same interface.  It has roughly the same purpose as CLOS's
    176 (call-next-method); when you use (send-super), the message is
    177 handled by the superclass.  This can be used to get at the
    178 original implementation of a method when it is shadowed by a
    179 method in your subclass.</para>
    180 
    181       <sect2 id="Type-Coercion-for-ObjC-Method-Calls">
    182         <title>Type Coercion for ObjC Method Calls</title>
    183         <para>&CCL;'s FFI handles many common conversions between
     159    <para>In Lisp, these same three lines are:</para>
     160    <programlisting>
     161      (send w 'alpha-value)
     162      (send w :set-alpha-value 0.5)
     163      (send v :mouse p :in-rect r)
     164    </programlisting>
     165    <para>Notice that when a method has no parameters, its name is an ordinary
     166      symbol (it doesn't matter what package the symbol is in, as
     167      only its name is checked).  When a method has parameters,
     168      each part of its name is a keyword, and the keywords alternate
     169      with the values.</para>
     170    <para>These two lines break those rules, and both  will
     171      result in error messages:</para>
     172    <programlisting>
     173      (send w :alpha-value)
     174      (send w 'set-alpha-value 0.5)
     175    </programlisting>
     176    <para>Instead of (send), you can also invoke (send-super), with the
     177      same interface.  It has roughly the same purpose as CLOS's
     178      (call-next-method); when you use (send-super), the message is
     179      handled by the superclass.  This can be used to get at the
     180      original implementation of a method when it is shadowed by a
     181      method in your subclass.</para>
     182
     183    <sect2 id="Type-Coercion-for-ObjC-Method-Calls">
     184          <title>Type Coercion for Objective-C Method Calls</title>
     185      <para>&CCL;'s FFI handles many common conversions between
    184186        Lisp and foreign data, such as unboxing floating-point args
    185187        and boxing floating-point results.  The bridge adds a few more
    186188        automatic conversions:</para>
    187         <para>NIL is equivalent to (%NULL-PTR) for any message
     189      <para>NIL is equivalent to (%NULL-PTR) for any message
    188190        argument that requires a pointer.</para>
    189         <para>T/NIL are equivalent to #$YES/#$NO for any boolean argument.</para>
    190         <para>A #$YES/#$NO returned by any method that returns BOOL
     191      <para>T/NIL are equivalent to #$YES/#$NO for any boolean argument.</para>
     192      <para>A #$YES/#$NO returned by any method that returns BOOL
    191193        will be automatically converted to T/NIL.</para>
    192       </sect2>
    193 
    194       <sect2 id="Methods-which-Return-Structures">
    195         <title>Methods which Return Structures</title>
    196         <para>Some Cocoa methods return small structures, such as
     194    </sect2>
     195
     196    <sect2 id="Methods-which-Return-Structures">
     197          <title>Methods which Return Structures</title>
     198      <para>Some Cocoa methods return small structures, such as
    197199        those used to represent points, rects, sizes and ranges. When
    198200        writing in Objective C, the compiler hides the implementation
    199201        details.  Unfortunately, in Lisp we must be slightly more
    200202        aware of them.</para>
    201         <para>Methods which return structures are called in a special
     203      <para>Methods which return structures are called in a special
    202204        way; the caller allocates space for the result, and passes a
    203205        pointer to it as an extra argument to the method.  This is
    204206        called a Structure Return, or STRET.  Don't look at me; I
    205207        don't name these things.</para>
    206         <para>Here's a simple use of this in Objective C.  The first line
    207         sends the "bounds" message to v1, which returns a rectangle.
    208         The second line sends the "setBounds" message to v2, passing
    209         that same rectangle as a parameter.</para>
    210         <programlisting>
    211 NSRect r = [v1 bounds];
    212 [v2 setBounds r];
    213         </programlisting>
    214         <para>In Lisp, we must explicitly allocate the memory, which
     208      <para>Here's a simple use of this in Objective C.  The first line
     209            sends the "bounds" message to v1, which returns a rectangle.
     210            The second line sends the "setBounds" message to v2, passing
     211            that same rectangle as a parameter.</para>
     212      <programlisting>
     213        NSRect r = [v1 bounds];
     214        [v2 setBounds r];
     215          </programlisting>
     216      <para>In Lisp, we must explicitly allocate the memory, which
    215217        is done most easily and safely with <xref linkend="m_rlet"/>.
    216218        We do it like this:</para>
    217         <programlisting>
    218 (rlet ((r :&lt;NSR>ect))
    219   (send/stret r v1 'bounds)
    220   (send v2 :set-bounds r))
    221 </programlisting>
    222         <para>The rlet allocates the storage (but doesn't initialize
     219      <programlisting>
     220        (rlet ((r :&lt;NSR>ect))
     221        (send/stret r v1 'bounds)
     222        (send v2 :set-bounds r))
     223      </programlisting>
     224      <para>The rlet allocates the storage (but doesn't initialize
    223225        it), and makes sure that it will be deallocated when we're
    224226        done.  It binds the variable r to refer to it.  The call to
     
    229231        because there's nothing complicated about passing a structure
    230232        as a parameter.</para>
    231         <para>In order to make STRETs easier to use, the bridge
    232         provides two conveniences.</para>
    233         <para>First, you can use the macros <literal>slet</literal>
     233          <para>In order to make STRETs easier to use, the bridge
     234            provides two conveniences.</para>
     235      <para>First, you can use the macros <literal>slet</literal>
    234236        and <literal>slet*</literal> to allocate and initialize local
    235237        variables to foreign structures in one step.  The example
    236238        above could have been written more tersely as:</para>
    237         <programlisting>
    238 (slet ((r (send v1 'bounds)))
    239   (send v2 :set-bounds r))
    240         </programlisting>
    241         <para>Second, when one call to <literal>send</literal> is made
    242 inside another, the inner one has an implicit
    243 <literal>slet</literal> around it.  So, one could in fact
    244 just write:</para>
    245         <programlisting>
    246 (send v1 :set-bounds (send v2 'bounds))
    247 </programlisting>
    248         <para>There are also several psuedo-functions provided for convenience
    249 by the ObjC compiler, to make objects of specific types. The
    250 following are currently supported by the bridge: NS-MAKE-POINT,
    251 NS-MAKE-RANGE, NS-MAKE-RECT, and NS-MAKE-SIZE.</para>
    252         <para>These pseudo-functions can be used within an SLET initform:</para>
    253         <programlisting>
    254 (slet ((p (ns-make-point 100.0 200.0)))
    255   (send w :set-frame-origin p))
    256 </programlisting>
    257         <para>Or within a call to <literal>send</literal>:</para>
    258         <programlisting>
    259 (send w :set-origin (ns-make-point 100.0 200.0))
    260 </programlisting>
    261         <para>However, since these aren't real functions, a call like the
    262 following won't work:</para>
    263         <programlisting>
    264 (setq p (ns-make-point 100.0 200.0))
    265 </programlisting>
    266         <para>To extract fields from these objects, there are also some
    267 convenience macros: NS-MAX-RANGE, NS-MIN-X,
    268 NS-MIN-Y, NS-MAX-X, NS-MAX-Y, NS-MID-X, NS-MID-Y,
    269 NS-HEIGHT, and NS-WIDTH.</para>
    270         <para>Note that there is also a <literal>send-super/stret</literal>
    271 for use within methods.  Like <literal>send-super</literal>,
    272 it ignores any shadowing methods in a subclass, and calls the
    273 version of a method which belongs to its superclass.</para>
    274       </sect2>
    275 
    276       <sect2 id="Variable-Arity-Messages">
    277         <title>Variable-Arity Messages</title>
    278         <para>
    279 There are a few messages in Cocoa which take variable numbers
    280 of arguments. Perhaps the most common examples involve
    281 formatted strings:</para>
    282         <programlisting>
    283 [NSClass stringWithFormat: "%f %f" x y]
    284 </programlisting>
    285         <para>In Lisp, this would be written:</para>
    286         <programlisting>
    287 (send (find-class 'ns:ns-string)
    288       :string-with-format #@"%f %f"
    289       (:double-float x :double-float y))
    290 </programlisting>
    291         <para>Note that it's necessary to specify the foreign types of the
    292 variables (in this example, :double-float), because the
    293 compiler has no general way of knowing these types.  (You
    294 might think that it could parse the format string, but this
    295 would only work for format strings which are not determined
    296 at runtime.)</para>
    297         <para>Because the ObjC runtime system does not provide any information
    298 on which messages are variable arity, they must be explicitly
    299 declared. The standard variable arity messages in Cocoa are
    300 predeclared by the bridge.  If you need to declare a new
    301 variable arity message, use
    302 (DEFINE-VARIABLE-ARITY-MESSAGE "myVariableArityMessage:").</para>
    303       </sect2>
    304 
    305       <sect2 id="Optimization">
    306         <title>Optimization</title>
    307         <para>The bridge works fairly hard to optimize message sends,
     239      <programlisting>
     240        (slet ((r (send v1 'bounds)))
     241        (send v2 :set-bounds r))
     242          </programlisting>
     243      <para>Second, when one call to <literal>send</literal> is made
     244        inside another, the inner one has an implicit
     245        <literal>slet</literal> around it.  So, one could in fact
     246        just write:</para>
     247      <programlisting>
     248        (send v1 :set-bounds (send v2 'bounds))
     249      </programlisting>
     250      <para>There are also several psuedo-functions provided for convenience
     251        by the Objective-C compiler, to make objects of specific types. The
     252        following are currently supported by the bridge: NS-MAKE-POINT,
     253        NS-MAKE-RANGE, NS-MAKE-RECT, and NS-MAKE-SIZE.</para>
     254      <para>These pseudo-functions can be used within an SLET initform:</para>
     255      <programlisting>
     256        (slet ((p (ns-make-point 100.0 200.0)))
     257        (send w :set-frame-origin p))
     258      </programlisting>
     259      <para>Or within a call to <literal>send</literal>:</para>
     260      <programlisting>
     261        (send w :set-origin (ns-make-point 100.0 200.0))
     262      </programlisting>
     263      <para>However, since these aren't real functions, a call like the
     264        following won't work:</para>
     265      <programlisting>
     266        (setq p (ns-make-point 100.0 200.0))
     267      </programlisting>
     268      <para>To extract fields from these objects, there are also some
     269        convenience macros: NS-MAX-RANGE, NS-MIN-X,
     270        NS-MIN-Y, NS-MAX-X, NS-MAX-Y, NS-MID-X, NS-MID-Y,
     271        NS-HEIGHT, and NS-WIDTH.</para>
     272      <para>Note that there is also a <literal>send-super/stret</literal>
     273        for use within methods.  Like <literal>send-super</literal>,
     274        it ignores any shadowing methods in a subclass, and calls the
     275        version of a method which belongs to its superclass.</para>
     276    </sect2>
     277
     278    <sect2 id="Variable-Arity-Messages">
     279          <title>Variable-Arity Messages</title>
     280      <para>
     281        There are a few messages in Cocoa which take variable numbers
     282        of arguments. Perhaps the most common examples involve
     283        formatted strings:</para>
     284      <programlisting>
     285        [NSClass stringWithFormat: "%f %f" x y]
     286      </programlisting>
     287      <para>In Lisp, this would be written:</para>
     288      <programlisting>
     289        (send (find-class 'ns:ns-string)
     290        :string-with-format #@"%f %f"
     291        (:double-float x :double-float y))
     292      </programlisting>
     293      <para>Note that it's necessary to specify the foreign types of the
     294        variables (in this example, :double-float), because the
     295        compiler has no general way of knowing these types.  (You
     296        might think that it could parse the format string, but this
     297        would only work for format strings which are not determined
     298        at runtime.)</para>
     299      <para>Because the Objective-C runtime system does not provide any information
     300        on which messages are variable arity, they must be explicitly
     301        declared. The standard variable arity messages in Cocoa are
     302        predeclared by the bridge.  If you need to declare a new
     303        variable arity message, use
     304        (DEFINE-VARIABLE-ARITY-MESSAGE "myVariableArityMessage:").</para>
     305    </sect2>
     306
     307    <sect2 id="Optimization">
     308          <title>Optimization</title>
     309      <para>The bridge works fairly hard to optimize message sends,
    308310        when it has enough information to do so.  There are two cases
    309311        when it does.  In either, a message send should be nearly as
    310312        efficient as when writing in Objective C.</para>
    311         <para>The first case is when both the message and the
     313      <para>The first case is when both the message and the
    312314        receiver's class are known at compile-time. In general, the
    313315        only way the receiver's class is known is if you declare it,
    314316        which you can do with either a DECLARE or a THE form.  For
    315317        example:</para>
    316         <programlisting>
    317 (send (the ns:ns-window w) 'center)
    318         </programlisting>
    319         <para>Note that there is no way in ObjC to name the class of a
     318      <programlisting>
     319        (send (the ns:ns-window w) 'center)
     320          </programlisting>
     321      <para>Note that there is no way in Objective-C to name the class of a
    320322        class.  Thus the bridge provides a declaration, @METACLASS.
    321323        The type of an instance of "NSColor" is ns:ns-color.  The type
    322324        of the <emphasis>class</emphasis> "NSColor" is (@metaclass
    323325        ns:ns-color):</para>
    324         <programlisting>
    325 (let ((c (find-class 'ns:ns-color)))
    326   (declare ((ccl::@metaclass ns:ns-color) c))
    327   (send c 'white-color))
    328 </programlisting>
    329         <para>The other case that alllows optimization is when only
     326      <programlisting>
     327        (let ((c (find-class 'ns:ns-color)))
     328        (declare ((ccl::@metaclass ns:ns-color) c))
     329        (send c 'white-color))
     330      </programlisting>
     331      <para>The other case that alllows optimization is when only
    330332        the message is known at compile-time, but its type signature
    331333        is unique. Of the more-than-6000 messages currently provided
    332334        by Cocoa, only about 50 of them have nonunique type
    333335        signatures.</para>
    334         <para>An example of a message with a type signature that is
     336      <para>An example of a message with a type signature that is
    335337        not unique is SET.  It returns VOID for NSColor, but ID for
    336338        NSSet.  In order to optimize sends of messages with nonunique
    337339        type signatures, the class of the receiver must be declared at
    338340        compile-time.</para>
    339         <para>If the type signature is nonunique or the message is
     341      <para>If the type signature is nonunique or the message is
    340342        unknown at compile-time, then a slower runtime call must be
    341343        used.</para>
    342         <para>When the receiver's class is unknown, the bridge's
     344      <para>When the receiver's class is unknown, the bridge's
    343345        ability to optimize relies on a type-signature table which it
    344346        maintains.  When first loaded, the bridge initializes this
    345         table by scanning every method of every ObjC class.  When new
     347        table by scanning every method of every Objective-C class.  When new
    346348        methods are defined later, the table must be updated.  This
    347349        happens automatically when you define methods in Lisp.  After
    348350        any other major change, such as loading an external framework,
    349351        you should rebuild the table:</para>
    350         <programlisting>
    351 ? (update-type-signatures)
    352 </programlisting>
    353         <para>Because <literal>send</literal> and its relatives
     352      <programlisting>
     353        ? (update-type-signatures)
     354      </programlisting>
     355      <para>Because <literal>send</literal> and its relatives
    354356        <literal>send-super</literal>, <literal>send/stret</literal>,
    355357        and <literal>send-super/stret</literal> are macros, they
     
    357359        <literal>apply</literal>ed, or passed as arguments to
    358360        functions.</para>
    359         <para>To work around this, there are function equivalents to
     361      <para>To work around this, there are function equivalents to
    360362        them: <literal>%send</literal>,
    361363        <literal>%send-super</literal>,
     
    364366        functions should be used only when the macros will not do,
    365367        because they are unable to optimize.</para>
    366       </sect2>
    367     </sect1>
    368 
    369     <sect1 id="Defining-Objective-C-Classes">
    370       <title>Defining Objective-C Classes</title>
    371       <para>You can define your own foreign classes, which can then be
     368    </sect2>
     369  </sect1>
     370
     371  <sect1 id="Defining-Objective-C-Classes">
     372    <title>Defining Objective-C Classes</title>
     373    <para>You can define your own foreign classes, which can then be
    372374      passed to foreign functions; the methods which you implement in
    373375      Lisp will be made available to the foreign code as
    374376      callbacks.</para>
    375       <para>You can also define subclasses of existing classes,
     377    <para>You can also define subclasses of existing classes,
    376378      implementing your subclass in Lisp even though the parent class
    377379      was in Objective C.  One such subclass is CCL::NS-LISP-STRING.
    378380      It is also particularly useful to make subclasses of
    379381      NS-WINDOW-CONTROLLER.</para>
    380       <para>We can use the MOP to define new Objective-C classes, but
     382    <para>We can use the MOP to define new Objective-C classes, but
    381383      we have to do something a little funny: the :METACLASS that we'd
    382384      want to use in a DEFCLASS option generally doesn't exist until
    383       we've created the class (recall that ObjC classes have, for the
     385      we've created the class (recall that Objective-C classes have, for the
    384386      sake of argument, unique and private metaclasses.) We can sort
    385       of sleaze our way around this by specifying a known ObjC
     387      of sleaze our way around this by specifying a known Objective-C
    386388      metaclass object name as the value of the DEFCLASS :METACLASS
    387389      object; the metaclass of the root class NS:NS-OBJECT,
     
    389391      NS:NS-WINDOW (that, for simplicity's sake, doesn't define any
    390392      new slots), we could do:</para>
    391       <programlisting>
    392 (defclass example-window (ns:ns-window)
    393   ()
    394   (:metaclass ns:+ns-object))
    395 </programlisting>
    396       <para>That'll create a new ObjC class named EXAMPLE-WINDOW whose
     393    <programlisting>
     394      (defclass example-window (ns:ns-window)
     395      ()
     396      (:metaclass ns:+ns-object))
     397    </programlisting>
     398    <para>That'll create a new Objective-C class named EXAMPLE-WINDOW whose
    397399      metaclass is the class named +EXAMPLE-WINDOW. The class will be
    398400      an object of type OBJC:OBJC-CLASS, and the metaclass will be of
     
    400402      NS-WINDOW.</para>
    401403
    402       <sect2 id="Defining-classes-with-foreign-slots">
    403         <title>Defining classes with foreign slots</title>
    404         <para>If a slot specification in an Objective-C class
     404    <sect2 id="Defining-classes-with-foreign-slots">
     405          <title>Defining classes with foreign slots</title>
     406      <para>If a slot specification in an Objective-C class
    405407        definition contains the keyword :FOREIGN-TYPE, the slot will
    406         be a "foreign slot" (i.e. an ObjC instance variable). Be aware
    407         that it is an error to redefine an ObjC class so that its
     408        be a "foreign slot" (i.e. an Objective-C instance variable). Be aware
     409        that it is an error to redefine an Objective-C class so that its
    408410        foreign slots change in any way, and &CCL; doesn't do
    409411        anything consistent when you try to.</para>
    410         <para>The value of the :FOREIGN-TYPE initarg should be a
     412      <para>The value of the :FOREIGN-TYPE initarg should be a
    411413        foreign type specifier. For example, if we wanted (for some
    412414        reason) to define a subclass of NS:NS-WINDOW that kept track
     
    414416        instance variable to keep that information in), we could
    415417        say:</para>
    416         <programlisting>
    417 (defclass key-event-counting-window (ns:ns-window)
    418   ((key-event-count :foreign-type :int
    419                     :initform 0
    420                     :accessor window-key-event-count))
    421   (:metaclass ns:+ns-object))
    422 </programlisting>
    423         <para>Foreign slots are always SLOT-BOUNDP, and the initform
     418      <programlisting>
     419        (defclass key-event-counting-window (ns:ns-window)
     420        ((key-event-count :foreign-type :int
     421        :initform 0
     422        :accessor window-key-event-count))
     423        (:metaclass ns:+ns-object))
     424      </programlisting>
     425      <para>Foreign slots are always SLOT-BOUNDP, and the initform
    424426        above is redundant: foreign slots are initialized to binary
    425427        0.</para>
    426       </sect2>
    427 
    428       <sect2 id="Defining-classes-with-Lisp-slots">
    429         <title>Defining classes with Lisp slots</title>
    430         <para>A slot specification in an ObjC class definition that
     428    </sect2>
     429
     430    <sect2 id="Defining-classes-with-Lisp-slots">
     431          <title>Defining classes with Lisp slots</title>
     432      <para>A slot specification in an Objective-C class definition that
    431433        doesn't contain the :FOREIGN-TYPE initarg defines a
    432434        pretty-much normal lisp slot that'll happen to be associated
    433435        with "an instance of a foreign class". For instance:</para>
    434         <programlisting>
    435 (defclass hemlock-buffer-string (ns:ns-string)
    436   ((hemlock-buffer :type hi::hemlock-buffer
    437                    :initform hi::%make-hemlock-buffer
    438                    :accessor string-hemlock-buffer))
    439   (:metaclass ns:+ns-object))
    440         </programlisting>
    441         <para>As one might expect, this has memory-management
     436      <programlisting>
     437        (defclass hemlock-buffer-string (ns:ns-string)
     438        ((hemlock-buffer :type hi::hemlock-buffer
     439        :initform hi::%make-hemlock-buffer
     440        :accessor string-hemlock-buffer))
     441        (:metaclass ns:+ns-object))
     442          </programlisting>
     443      <para>As one might expect, this has memory-management
    442444        implications: we have to maintain an association between a
    443445        MACPTR and a set of lisp objects (its slots) as long as the
    444         ObjC instance exists, and we have to ensure that the ObjC
     446        Objective-C instance exists, and we have to ensure that the Objective-C
    445447        instance exists (does not have its -dealloc method called)
    446448        while lisp is trying to think of it as a first-class object
     
    450452        were to do this "by hand", you'd have to face many of the same
    451453        memory-management issues.</para>
    452       </sect2>
    453     </sect1>
    454 
    455     <sect1 id="Defining-Objective-C-Methods">
    456       <title>Defining Objective-C Methods</title>
    457       <para>In ObjC, unlike in CLOS, every method belongs to some
     454    </sect2>
     455  </sect1>
     456
     457  <sect1 id="Defining-Objective-C-Methods">
     458    <title>Defining Objective-C Methods</title>
     459    <para>In Objective-C, unlike in CLOS, every method belongs to some
    458460      particular class.  This is probably not a strange concept to
    459461      you, because C++ and Java do the same thing.  When you use Lisp
    460       to define ObjC methods, it is only possible to define methods
    461       belonging to ObjC classes which have been defined in
     462      to define Objective-C methods, it is only possible to define methods
     463      belonging to Objective-C classes which have been defined in
    462464      Lisp.</para>
    463       <para>The macro <literal>define-objc-method</literal> is used
    464       for this.  As described in , the names of ObjC methods are
     465    <para>The macro <literal>define-objc-method</literal> is used
     466      for this.  As described in , the names of Objective-C methods are
    465467      broken into pieces, each piece followed by a parameter.  The
    466468      types of all parameters must be explicitly declared.</para>
    467       <para>Right now, I'm not sure how to formally describe the usage
    468 of define-objc-method, so I'm going to do it with some short
    469 examples.  Let us define a class to use in them:</para>
    470       <programlisting>
    471 (defclass data-window-controller (ns:ns-window-controller)
    472   ((window :foreign-type :id :accessor window)
    473    (data :initform nil :accessor data))
    474   (:metaclass ns:+ns-object))
    475 </programlisting>
    476       <para>There's nothing special about this class.  It inherits
     469    <para>Right now, I'm not sure how to formally describe the usage
     470      of define-objc-method, so I'm going to do it with some short
     471      examples.  Let us define a class to use in them:</para>
     472    <programlisting>
     473      (defclass data-window-controller (ns:ns-window-controller)
     474      ((window :foreign-type :id :accessor window)
     475      (data :initform nil :accessor data))
     476      (:metaclass ns:+ns-object))
     477    </programlisting>
     478    <para>There's nothing special about this class.  It inherits
    477479      from ns:ns-window-controller.  It has two slots:
    478       <literal>window</literal> is a foreign slot, stored in the ObjC
     480      <literal>window</literal> is a foreign slot, stored in the Objective-C
    479481      world; and <literal>data</literal> is an ordinary slot, stored
    480482      in the Lisp world.</para>
    481       <para>Here is an example of how to define a method which takes
     483    <para>Here is an example of how to define a method which takes
    482484      no arguments.  It happens to be an initialization method, but
    483485      that's not important:</para>
    484       <programlisting>
    485  (define-objc-method ((:id get-window)
    486                      data-window-controller)
    487   (window self))
    488       </programlisting>
    489       <para>The return type of this method is the foreign type :id,
    490       which is used for all ObjC objects.  The name of the method is
     486    <programlisting>
     487      (define-objc-method ((:id get-window)
     488      data-window-controller)
     489      (window self))
     490    </programlisting>
     491    <para>The return type of this method is the foreign type :id,
     492      which is used for all Objective-C objects.  The name of the method is
    491493      <literal>get-window</literal>.  The body of the method is the
    492494      single line (window self).  The variable <literal>self</literal>
     
    494496      the message.  The call to <literal>window</literal> uses the
    495497      CLOS accessor to get the value of the window field.</para>
    496       <para>Here's an example which takes a parameter.  Notice that
     498    <para>Here's an example which takes a parameter.  Notice that
    497499      the name of the method without a parameter was an ordinary
    498500      symbol, but with a parameter, it's a keyword:</para>
    499       <programlisting>
    500 (define-objc-method ((:id :init-with-multiplier (:int multiplier))
    501                      data-window-controller)
    502   (setf (data self) (make-array 100))
    503   (dotimes (i 100)
    504     (setf (aref (data self) i)
    505           (* i multiplier)))
    506   self)
    507       </programlisting>
    508       <para>To Objective-C code which uses the class, the name of this
     501    <programlisting>
     502      (define-objc-method ((:id :init-with-multiplier (:int multiplier))
     503      data-window-controller)
     504      (setf (data self) (make-array 100))
     505      (dotimes (i 100)
     506      (setf (aref (data self) i)
     507      (* i multiplier)))
     508      self)
     509    </programlisting>
     510    <para>To Objective-C code which uses the class, the name of this
    509511      method is "initWithMultiplier:".  The name of the parameter is
    510512      <literal>multiplier</literal>, and its type is :int.  The body
     
    512514      <literal>self</literal>, because this is an initialization
    513515      method.</para>
    514       <para>Here's an example with more than one parameter:</para>
    515       <programlisting>
    516 (define-objc-method ((:id :init-with-multiplier (:int multiplier)
    517                           :and-addend (:int addend))
    518                      data-window-controller)
    519   (setf (data self) (make-array size))
    520   (dotimes (i 100)
    521     (setf (aref (data self) i)
    522           (+ (* i multiplier)
    523              addend)))
    524   self)
    525       </programlisting>
    526       <para>To Objective-C, the name of this method is
     516    <para>Here's an example with more than one parameter:</para>
     517    <programlisting>
     518      (define-objc-method ((:id :init-with-multiplier (:int multiplier)
     519      :and-addend (:int addend))
     520      data-window-controller)
     521      (setf (data self) (make-array size))
     522      (dotimes (i 100)
     523      (setf (aref (data self) i)
     524      (+ (* i multiplier)
     525      addend)))
     526      self)
     527    </programlisting>
     528    <para>To Objective-C, the name of this method is
    527529      "initWithMultiplier:andAddend:".  Both parameters are of type
    528530      :int; the first is named <literal>multiplier</literal>, and the
    529531      second is <literal>addend</literal>.  Again, the method returns
    530532      <literal>self</literal>.</para>
    531       <para>Here is a method which does not return any value, a
     533    <para>Here is a method which does not return any value, a
    532534      so-called "void method".  Where our other methods said :id, this
    533535      one says :void for the return type:</para>
    534       <programlisting>
    535 (define-objc-method ((:void :take-action (:id sender))
    536                      data-window-controller)
    537   (declare (ignore sender))
    538   (dotimes (i 100)
    539     (setf (aref (data self) i)
    540           (- (aref (data self) i)))))
    541 </programlisting>
    542       <para>This method would be called "takeAction:" in ObjC.  The
     536    <programlisting>
     537      (define-objc-method ((:void :take-action (:id sender))
     538      data-window-controller)
     539      (declare (ignore sender))
     540      (dotimes (i 100)
     541      (setf (aref (data self) i)
     542      (- (aref (data self) i)))))
     543    </programlisting>
     544    <para>This method would be called "takeAction:" in Objective-C.  The
    543545      convention for methods that are going to be used as Cocoa
    544546      actions is that they take one parameter, which is the object
     
    547549      ignores it to avoid a compiler warning.  As promised, the method
    548550      doesn't return any value.</para>
    549       <para>There is also an alternate syntax, illustrated here.  The
     551    <para>There is also an alternate syntax, illustrated here.  The
    550552      following two method definitions are equivalent:</para>
    551       <programlisting>
    552 (define-objc-method ("applicationShouldTerminate:"
    553                      "LispApplicationDelegate")
    554                     (:id sender :&lt;BOOL>)
    555   (declare (ignore sender))
    556   nil)
    557 
    558 (define-objc-method ((:&lt;BOOL>
    559                       :application-should-terminate sender)
    560                      lisp-application-delegate)
    561   (declare (ignore sender))
    562   nil)
    563 </programlisting>
    564       <sect2 id="Method-Redefinition-Constraints">
    565         <title>Method Redefinition Constraints</title>
    566         <para>Objective C was not designed, as Lisp was, with runtime
     553    <programlisting>
     554      (define-objc-method ("applicationShouldTerminate:"
     555      "LispApplicationDelegate")
     556      (:id sender :&lt;BOOL>)
     557      (declare (ignore sender))
     558      nil)
     559
     560      (define-objc-method ((:&lt;BOOL>
     561      :application-should-terminate sender)
     562      lisp-application-delegate)
     563      (declare (ignore sender))
     564      nil)
     565    </programlisting>
     566    <sect2 id="Method-Redefinition-Constraints">
     567          <title>Method Redefinition Constraints</title>
     568      <para>Objective C was not designed, as Lisp was, with runtime
    567569        redefinition in mind.  So, there are a few constraints about
    568570        how and when you can replace the definition of an Objective C
     
    570572        collapse, but the behaviour will be confusing; so
    571573        don't.</para>
    572         <para>Objective C methods can be redefined at runtime, but
     574      <para>Objective C methods can be redefined at runtime, but
    573575        their signatures shouldn't change.  That is, the types of the
    574576        arguments and the return type have to stay the same.  The
    575577        reason for this is that changing the signature changes the
    576578        selector which is used to call the method.</para>
    577         <para>When a method has already been defined in one class, and
     579      <para>When a method has already been defined in one class, and
    578580        you define it in a subclass, shadowing the original method,
    579581        they must both have the same type signature.  There is no such
    580582        constraint, though, if the two classes aren't related and the
    581583        methods just happen to have the same name.</para>
    582       </sect2>
    583     </sect1>
    584 
    585     <sect1 id="How-Objective-C-Names-are-Mapped-to-Lisp-Symbols">
    586       <title>How Objective-C Names are Mapped to Lisp Symbols</title>
    587       <para>There is a standard set of naming conventions for Cocoa
     584    </sect2>
     585  </sect1>
     586
     587  <sect1 id="How-Objective-C-Names-are-Mapped-to-Lisp-Symbols">
     588    <title>How Objective-C Names are Mapped to Lisp Symbols</title>
     589    <para>There is a standard set of naming conventions for Cocoa
    588590      classes, messages, etc.  As long as they are followed, the
    589       bridge is fairly good at automaticallly translating between ObjC
     591      bridge is fairly good at automaticallly translating between Objective-C
    590592      and Lisp names.</para>
    591       <para>For example, "NSOpenGLView" becomes ns:ns-opengl-view;
     593    <para>For example, "NSOpenGLView" becomes ns:ns-opengl-view;
    592594      "NSURLHandleClient" becomes ns:ns-url-handle-client; and
    593595      "nextEventMatchingMask:untilDate:inMode:dequeue:" becomes
    594596      (:next-event-matching-mask :until-date :in-mode :dequeue).  What
    595597      a mouthful.</para>
    596       <para>To see how a given ObjC or Lisp name will be translated by
     598    <para>To see how a given Objective-C or Lisp name will be translated by
    597599      the bridge, you can use the following functions:</para>
    598600        <simplelist type="vert">
     
    605607        </simplelist>
    606608
    607       <para>Of course, there will always be exceptions to any naming
     609    <para>Of course, there will always be exceptions to any naming
    608610      convention.  Please tell us on the mailing lists if you come
    609611      across any name translation problems that seem to be bugs.
    610612      Otherwise, the bridge provides two ways of dealing with
    611613      exceptions:</para>
    612       <para>First, you can pass a string as the class name of
     614    <para>First, you can pass a string as the class name of
    613615      MAKE-OBJC-INSTANCE and as the message to SEND.  These strings
    614       will be directly interpreted as ObjC names, with no
     616      will be directly interpreted as Objective-C names, with no
    615617      translation. This is useful for a one-time exception.  For
    616618      example:</para>
    617       <programlisting>
    618 (ccl::make-objc-instance "WiErDclass")
    619 (ccl::send o "WiErDmEsSaGe:WithARG:" x y)
    620       </programlisting>
    621       <para>Alternatively, you can define a special translation rule
     619    <programlisting>
     620      (ccl::make-objc-instance "WiErDclass")
     621      (ccl::send o "WiErDmEsSaGe:WithARG:" x y)
     622    </programlisting>
     623    <para>Alternatively, you can define a special translation rule
    622624      for your exception.  This is useful for an exceptional name that
    623625      you need to use througout your code.  Some examples:</para>
    624       <programlisting>
    625 (ccl::define-classname-translation "WiErDclass" wierd-class)
    626 (ccl::define-message-translation "WiErDmEsSaGe:WithARG:" (:weird-message :with-arg))
    627 (ccl::define-init-translation "WiErDiNiT:WITHOPTION:" (:weird-init :option))
    628 </programlisting>
    629       <para>The normal rule in ObjC names is that each word begins with a
    630 capital letter (except possibly the first).  Using this rule
    631 literally, "NSWindow" would be translated as N-S-WINDOW, which
    632 seems wrong.  "NS" is a special word in ObjC that should not be
    633 broken at each capital letter. Likewise "URL", "PDF", "OpenGL",
    634 etc. Most common special words used in Cocoa are already defined
    635 in the bridge, but you can define new ones as follows:</para>
    636       <programlisting>
    637 (ccl::define-special-objc-word "QuickDraw")
    638 </programlisting>
    639       <para>Note that message keywords in a SEND such as (SEND V
     626    <programlisting>
     627      (ccl::define-classname-translation "WiErDclass" wierd-class)
     628      (ccl::define-message-translation "WiErDmEsSaGe:WithARG:" (:weird-message :with-arg))
     629      (ccl::define-init-translation "WiErDiNiT:WITHOPTION:" (:weird-init :option))
     630    </programlisting>
     631    <para>The normal rule in Objective-C names is that each word begins with a
     632      capital letter (except possibly the first).  Using this rule
     633      literally, "NSWindow" would be translated as N-S-WINDOW, which
     634      seems wrong.  "NS" is a special word in Objective-C that should not be
     635      broken at each capital letter. Likewise "URL", "PDF", "OpenGL",
     636      etc. Most common special words used in Cocoa are already defined
     637      in the bridge, but you can define new ones as follows:</para>
     638    <programlisting>
     639      (ccl::define-special-objc-word "QuickDraw")
     640    </programlisting>
     641    <para>Note that message keywords in a SEND such as (SEND V
    640642      :MOUSE P :IN-RECT R) may look like the keyword arguments in a
    641643      Lisp function call, but they really aren't. All keywords must be
    642644      present and the order is significant. Neither (:IN-RECT :MOUSE)
    643645      nor (:MOUSE) translate to "mouse:inRect:"</para>
    644       <para>Also, as a special exception, an "init" prefix is optional
     646    <para>Also, as a special exception, an "init" prefix is optional
    645647      in the initializer keywords, so (MAKE-OBJC-INSTANCE 'NS-NUMBER
    646648      :INIT-WITH-FLOAT 2.7) can also be expressed as
    647649      (MAKE-OBJC-INSTANCE 'NS-NUMBER :WITH-FLOAT 2.7)</para>
    648     </sect1>
    649   </chapter>
     650  </sect1>
     651</chapter>
  • trunk/source/doc/src/using.xml

    r8822 r8894  
    1212<chapter><title>Using &CCL;</title>
    1313 
     14  <!-- ============================================================ -->
    1415  <sect1><title>Introduction</title>
    1516   
     
    2021      part of the Common Lisp standard, but which may have quirks or
    2122      details in the &CCL; implementation that are not described by
    22       the standard.</para>
     23      the standard. It also describes extensions to the standard; that
     24      is, features of &CCL; that are not part of the Common Lisp
     25      standard at all.</para>
    2326
    2427  </sect1>
    2528
     29  <!-- ============================================================ -->
    2630  <sect1 id="Trace"><title>Trace</title>
    2731
     
    10331037  </sect1>
    10341038
     1039  <!-- ============================================================ -->
    10351040  <sect1 id="Static_Variables">
    10361041    <title>Static Variables</title>
     
    11061111  </sect1>
    11071112
     1113  <!-- ============================================================ -->
     1114  <sect1 id="Saving-Applications">
     1115        <indexterm zone="Saving-Applications">
     1116          <primary>save-application</primary>
     1117        </indexterm>
     1118    <title>Saving Applications</title>
     1119
     1120    <para>&CCL; provides the
     1121    function <code>CCL:SAVE-APPLICATION</code>, which creates a file
     1122    containing an archived Lisp memory image.</para>
     1123
     1124    <para>&CCL; consists of a small executable called the
     1125    Lisp <glossterm linkend="lisp_image">kernel</glossterm>, which
     1126    implements the very lowest level features of the Lisp system, and
     1127    an <glossterm linkend="lisp_image">image</glossterm>, which
     1128    contains the in-memory representation of most of the Lisp system,
     1129    including functions, data structures, variables, and so on. When
     1130    you start &CCL;, you are launching the kernel, which then locates
     1131    and reads an image file, restoring the archived image in
     1132    memory. Once the image is fully restored, the Lisp system is
     1133    running.</para>
     1134
     1135    <para>Using <code>CCL:SAVE-APPLICATION</code>, you can create a
     1136    file that contains a modified image, one that includes any changes
     1137    you've made to the running Lisp system. If you later pass your
     1138    image file to the &CCL; kernel as a command-line parameter, it
     1139    then loads your image file instead of its default one, and &CCL;
     1140    starts up with your modifications.</para>
     1141
     1142    <para>If this scenario seems to you like a convenient way to
     1143    create an application, that's just as intended. You can create an
     1144    application by modifying the running Lisp until it does what you
     1145    want, then use <code>CCL:SAVE-APPLICATION</code> to preserve your
     1146    changes and later load them for use.</para>
     1147
     1148    <para>In fact, you can go further than that. You can replace
     1149    &CCL;'s <glossterm linkend="toplevel_function">toplevel
     1150    function</glossterm> with your own, and then, when the image is
     1151    loaded, the Lisp system immediately performs your tasks rather
     1152    than the default tasks that make it a Lisp development system. If
     1153    you save an image in which you have done this, the resulting Lisp
     1154    system is your tool rather than a Lisp development system.</para>
     1155
     1156    <para>You can go a step further still. You can
     1157    tell <code>CCL:SAVE-APPLICATION</code> to prepend the Lisp kernel
     1158    to the image file. Doing this makes the resulting image into a
     1159    self-contained executable binary. When you run the resulting file,
     1160    the Lisp kernel immediately loads the attached image file and runs
     1161    your saved system. The Lisp system that starts up can have any
     1162    behavior you choose. It can be a Lisp development system, but with
     1163    your customizations; or it can immediately perform some task of
     1164    your design, making it a specialized tool rather than a general
     1165    development system.</para>
     1166
     1167    <para>In other words, you can develop any application you like by
     1168    interactively modifying &CCL; until it does what you want, then
     1169    using <code>CCL:SAVE-APPLICATION</code> to preserve your changes
     1170    in an executable image.</para>
     1171
     1172    <para>On Mac OS X,
     1173    the <link linkend="application_builder">application builder</link>
     1174    uses <code>CCL:SAVE-APPLICATION</code> to create the executable
     1175    portion of the <glossterm linkend="application_bundle">application
     1176    bundle</glossterm>. Double-clicking the application bundle runs
     1177    the executable image created
     1178    by <code>CCL:SAVE-APPLICATION</code>.</para>
     1179
     1180    <para>Also on Mac OS X, &CCL; supports an object type
     1181    called <code>MACPTR</code>, which is the type of pointers into the
     1182    foreign (Mac OS) heap. Examples of
     1183    commonly-user <code>MACPTR</code> objects are Cocoa windows and
     1184    other dynamically-allocated Mac OS sytem objects.</para>
     1185
     1186    <para>Because a <code>MACPTR</code> object is a pointer into a
     1187    foreign heap that exists for the lifetime of the running Lisp
     1188    provess, and because a saved image is used by loading it into a
     1189    brand new Lisp process, saved <code>MACPTR</code> objects cannot
     1190    be relied on to point to the same things when reconstituted from a
     1191    saved image. In fact, a restored <code>MACPTR</code> object might
     1192    point to anything at all&mdash;for example an arbitrary location
     1193    in the middle of a block of code, or a completely nonexistent
     1194    virtual address.</para>
     1195
     1196    <para>For that reason, <code>CCL:SAVE-APPLICATION</code> converts
     1197    all <code>MACPTR</code> objects to <code>DEAD-MACPTR</code>
     1198    objects when writing them to an image
     1199    file. A <code>DAED-MACPTR</code> is functionally identical to
     1200    a <code>MACPTR</code>, except that code that operates
     1201    on <code>MACPTR</code> objects distinguishes them
     1202    from <code>DEAD-MACPTR</code> objects and can handle them
     1203    appropriately&mdash;signaling errors, for example.</para>
     1204
     1205    <para>As of &CCL; 1.2, there is one exception to the conversion
     1206    of <code>MACPTR</code> to <code>DEAD-MACPTR</code> objects:
     1207    a <code>MACPTR</code> object that points to the address 0 is not
     1208    converted, because address 0 can always be relied upon to refer to
     1209    the same thing.</para>
     1210
     1211        <indexterm zone="Saving-Applications">
     1212          <primary>+NULL-PTR+</primary>
     1213        </indexterm>
     1214    <para>As of &CCL; 1.2, the constant <code>CCL:+NULL-PTR+</code>
     1215    refers to a <code>MACPTR</code> object that points to address 0.</para>
     1216
     1217    <para>On all supported platforms, you can
     1218    use <code>CCL:SAVE-APPLICATION</code> to create a command-line
     1219    tool that runs the same way any command-line program
     1220    does. Alternatively, if you choose not to prepend the kernel, you
     1221    can save an image and then later run it by passing it as a
     1222    command-line parameter to the <code>opencml</code>
     1223    or <code>opencml64</code> script.</para>
     1224
     1225    <para>
     1226      <indexterm zone="save-application"/>
     1227      <command><varname id="save-application">SAVE-APPLICATION</varname>
     1228        <parameter>filename</parameter>
     1229        &key;
     1230        <parameter>toplevel-function</parameter>
     1231        <parameter>init-file</parameter>
     1232        <parameter>error-handler</parameter>
     1233        <parameter>application-class</parameter>
     1234        <parameter>clear-clos-caches</parameter>
     1235        <parameter>(purify t)</parameter>
     1236        <parameter>impurify</parameter>
     1237        <parameter>(mode #o644)</parameter>
     1238        <parameter>prepend-kernel</parameter>
     1239        [Function]</command>
     1240    </para>
     1241   
     1242    <variablelist>
     1243      <varlistentry>
     1244        <term><varname>filename</varname></term>
     1245        <listitem>
     1246          <para>The pathname of the file to be created when &CCL;
     1247          saves the application.</para>
     1248        </listitem>
     1249      </varlistentry>
     1250     
     1251      <varlistentry>
     1252        <term><varname>toplevel-function</varname></term>
     1253        <listitem>
     1254          <para>The function to be executed after startup is
     1255            complete. The toplevel is a function of no arguments that
     1256            performs whatever actions the lisp system should perform
     1257            when launched with this image.</para>
     1258          <para>If this parameter is not supplied, &CCL; uses its
     1259          default toplevel. The default toplevel runs
     1260          the <glossterm linkend="REPL">read-eval-print
     1261          loop</glossterm>.</para>
     1262        </listitem>
     1263      </varlistentry>
     1264
     1265      <varlistentry>
     1266        <term><varname>init-file</varname></term>
     1267        <listitem>
     1268          <para>The pathname of a Lisp file to be loaded when the
     1269          image starts up. You can place initialization expressions in
     1270          this file, and use it to customize the behavior of the Lisp
     1271          system when it starts up.</para>
     1272        </listitem>
     1273      </varlistentry>
     1274     
     1275      <varlistentry>
     1276        <term><varname>error-handler</varname></term>
     1277        <listitem>
     1278          <para>The error-handling mode for the saved image. The
     1279          supplied value determines what happens when an error is not
     1280          handled by the saved image. Valid values
     1281          are <code>:quit</code> (Lisp exits with an error
     1282          message); <code>:quit-quietly</code> (Lisp exits without an
     1283          error message); or <code>:listener</code> (Lisp enters a
     1284          break loop, enabling you to debug the problem by interacting
     1285          in a listener). If you don't supply this parameter, the
     1286          saved image uses the default error handler
     1287          (<code>:listener</code>).</para>
     1288        </listitem>
     1289      </varlistentry>
     1290
     1291      <varlistentry>
     1292        <term><varname>application-class</varname></term>
     1293        <listitem>
     1294          <para>The CLOS class that represents the saved Lisp
     1295          application. Normally you don't need to supply this
     1296          parameter; <code>CCL:SAVE-APPLICATION</code> uses the
     1297          class <code>CCL:LISP-DEVELOPMENT-SYSTEM</code>. In some
     1298          cases you may choose to create a custom application class;
     1299          in that case, pass the name of the class as the value for
     1300          this parameter.</para>
     1301        </listitem>
     1302      </varlistentry>
     1303     
     1304      <varlistentry>
     1305        <term><varname>clear-clos-caches</varname></term>
     1306        <listitem>
     1307          <para>If true, ensures that CLOS caches are emptied before
     1308          saving the image. Normally you don't need to supply this
     1309          parameter, but if for some reason you want to ensure the
     1310          CLOS caches are clear when the image starts up, you can pass
     1311          any true value.</para>
     1312        </listitem>
     1313      </varlistentry>
     1314     
     1315     
     1316    </variablelist>
     1317
     1318    <para></para>
     1319  </sect1>
     1320
    11081321</chapter>
Note: See TracChangeset for help on using the changeset viewer.