Home My Page Projects Code Snippets Project Openings SML/NJ
Summary Activity Forums Tracker Lists Tasks Docs Surveys News SCM Files

SCM Repository

[smlnj] Diff of /sml/trunk/src/ml-nlffi-lib/Doc/manual/nlffi.tex
ViewVC logotype

Diff of /sml/trunk/src/ml-nlffi-lib/Doc/manual/nlffi.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1554, Tue Jul 20 17:59:03 2004 UTC revision 1560, Fri Jul 23 23:23:09 2004 UTC
# Line 60  Line 60 
60  Each generated ML structure contains the ML type and values necessary  Each generated ML structure contains the ML type and values necessary
61  to manipulate the corresponding C item.  to manipulate the corresponding C item.
62    
63    %-------------------------------------------------------------------------
64  \subsection{External variables}  \subsection{External variables}
65    
66  An external C variable $v$ is represented by an ML structure {\tt  An external C variable $v$ of type $t_C$ is represented by an ML
67    G\_}$v$.  This structure contains one type and three values, all  structure {\tt G\_}$v$.  This structure always contains a type {\tt t}
68  with fixed names:  encoding $t_C$ and a value {\tt obj'} providing (``light-weight'')
69    access to the memory location that $v$ stands for in C.  If $t_C$ is
70    {\em complete}, then {\tt G\_}$v$ will also contain a value {\tt obj}
71    (the ``heavy-weight'' equivalent of {\tt obj'}) as well as value {\tt
72      typ} holding run-time type information corresponding to $t_C$ (and
73    {\tt t}).
74    
75    \paragraph*{Details}
76    
77  \begin{description}\setlength{\itemsep}{0pt}  \begin{description}\setlength{\itemsep}{0pt}
78  \item[{\tt type t}] is the witness type for the {\tt obj}  \item[{\tt type t}] is the type to be substituted for $\tau$ in {\tt
79    value that represents $v$.      ($\tau$, $\zeta$) C.obj} to yield the correct type for ML values
80  \item[{\tt val typ}] is the run-time type information corresponding to    representing C memory objects of type $t_C$ (i.e., $v$'s type).
81    type {\tt t}.  The ML type of {\tt typ} is {\tt t C.T.typ}.    (This assumes a properly instantiated $\zeta$ based on whether or
82  \item[{\tt val obj}] is a function that returns the ML value    not the corresponding object was declared {\tt const}.)
83    representing the C object (i.e., the memory location) referred to by  \item[!{\tt val typ}] is the run-time type information corresponding
84    $v$.  Depending on whether or not $v$ was declared {\tt const}, the    to type {\tt t}.  The ML type of {\tt typ} is {\tt t C.T.typ}.  This
85    type of {\tt obj} is either {\tt unit -> (t, C.ro) C.obj} or {\tt    value is not present if $t_C$ is {\em incomplete}.
86      unit -> (t, C.rw) C.obj}.  The result of {\tt obj()} is  \item[!{\tt val obj}] is a function that returns the ML-side
87    ``heavy-weight,'' i.e., it implicitly carries run-time type    representative of the C object (i.e., the memory location) referred
88    information.    to by $v$.  Depending on whether or not $v$ was declared {\tt
89        const}, the type of {\tt obj} is either {\tt unit -> (t, C.ro)
90        C.obj} or {\tt unit -> (t, C.rw) C.obj}.  The result of {\tt
91        obj()} is ``heavy-weight,'' i.e., it implicitly carries run-time
92      type information.  This value is not present if $t_C$ is {\em
93        incomplete}.
94  \item[{\tt val obj'}] is analogous to {\tt val obj}, the only  \item[{\tt val obj'}] is analogous to {\tt val obj}, the only
95    difference being that its result is ``light-weight,'' i.e., without    difference being that its result is ``light-weight,'' i.e., without
96    run-time type information.  The type of {\tt val obj'} is    run-time type information.  The type of {\tt val obj'} is
97    either {\tt unit -> (t, C.ro) C.obj} or {\tt unit -> (t, C.rw) C.obj}.    either {\tt unit -> (t, C.ro) C.obj} or {\tt unit -> (t, C.rw) C.obj}.
98  \end{description}  \end{description}
99    
100  \paragraph*{Examples}:  \subsubsection*{Examples}
101    
102  \begin{center}  \begin{center}
103  \begin{tabular}{c|c}  \begin{tabular}{c|c}
# Line 118  Line 131 
131    
132  \end{verbatim}  \end{verbatim}
133  \end{minipage}  \end{minipage}
134    \\ \hline
135    \begin{minipage}{2in}
136    \begin{verbatim}
137    extern struct str s1;
138    /* str complete */
139    \end{verbatim}
140    \end{minipage}
141    &
142    \begin{minipage}{4in}
143    \begin{verbatim}
144    
145    structure G_s1 : sig
146        type t   = (S_str.tag, rw) C.su_obj C.ptr
147        val typ  : t C.T.typ
148        val obj  : unit -> (t, C.rw) C.obj
149        val obj' : unit -> (t, C.rw) C.obj'
150    end
151    
152    \end{verbatim}
153    \end{minipage}
154    \\ \hline
155    \begin{minipage}{2in}
156    \begin{verbatim}
157    extern struct istr s2;
158    /* istr incomplete */
159    \end{verbatim}
160    \end{minipage}
161    &
162    \begin{minipage}{4in}
163    \begin{verbatim}
164    
165    structure G_s2 : sig
166        type t   = (ST_istr.tag, rw) C.su_obj C.ptr
167        val obj' : unit -> (t, C.rw) C.obj'
168    end
169    
170    \end{verbatim}
171    \end{minipage}
172  \end{tabular}  \end{tabular}
173  \end{center}  \end{center}
174    
175    %-------------------------------------------------------------------------
176    \subsection{Functions}
177    
178    An external C function $f$ is represented by an ML structure {\tt
179      F\_}$f$.  Each such structure always contains at last three values:
180    {\tt typ}, {\tt fptr}, and {\tt f'}.  Variable {\tt typ} holds
181    run-time type information regarding function pointers that share $f$'s
182    prototype.  The most important part of this information is the code
183    that implements native C calling conventions for these functions.
184    Variable {\tt fptr} provides access to a C pointer to $f$.  And {\tt
185      f'} is an ML function that dispatches a call of $f$ (through {\tt
186      fptr}), using ``light-weight'' types for arguments and results.  If
187    the result type of $f$ is {\em complete}, then {\tt F\_}$f$ will also
188    contain a function {\tt f}, using ``heavy-weight'' argument- and
189    result-types.
190    
191    \paragraph*{Details}
192    
193    \begin{description}\setlength{\itemsep}{0pt}
194    \item[{\tt val typ}] holds run-time type information for pointers to
195      functions of the same prototype.  The ML type of {\tt typ} is {\tt
196        ($A$ -> $B$) C.fptr C.T.typ} where $A$ and $B$ are types encoding
197      $f$'s argument list and result type, respectively.  A
198      description of $A$ and $B$ is given below.
199    \item[{\tt val fptr}] is a function that returns the (heavy-weight)
200      function pointer to $f$. The type of {\tt fptr} is {\tt unit -> ($A$
201        -> $B$) C.fptr}.  The encodings of argument- and result types in
202      $A$ and $B$ is the same as the one used for {\tt typ} (see below).
203      Notice that although {\tt fptr} is a heavy-weight value carrying
204      run-time type information, pointer arguments within $A$ or $B$ still
205      use the light-weight version!
206    \item[!{\tt val f}] is an ML function that dispatches a call to $f$
207      via {\tt fptr}.  For convenience, {\tt f} has built-in conversions
208      for arguments (from ML to C) and the result (from C to ML).  For
209      example, if $f$ has an argument of type {\tt double}, then {\tt f}
210      will take an argument of type {\tt MLRep.Real.real} in its place and
211      implicitly convert it to its C equivalent using {\tt
212        C.Cvt.c\_double}.  Similarly, if $f$ returns an {\tt unsigned
213        int}, then {\tt f} has a result type of {\tt MLRep.Unsigned.word}.
214      This is done for all types that have a conversion function in
215      {\tt C.Cvt}.
216      Pointer values (as well as the object argument used for {\tt
217        struct}- or {\tt union}-return values) are taken and returned in
218      their heavy-weight versions.  Function {\tt f} will not be generated
219      if the return type of $f$ is incomplete.
220    \item[{\tt val f'}] is the light-weight equivalent to {\tt f}.  a
221      light-weight function.  The main difference is that pointer- and
222      object-values are passed and returned in their light-weight
223      versions.
224    \end{description}
225    
226    \subsubsection*{Type encoding rules for {\tt ($A$ -> $B$) C.fptr}}
227    
228    A C function $f$'s prototype is encoded as an ML type {\tt $A$ ->
229      $B$}.  Calls of $f$ from ML take an argument of type $A$ and
230    produce a result of type $B$.
231    
232    \begin{itemize}
233    \item Type $A$ is constructed from a sequence $\langle T_1, \ldots,
234      T_k \rangle$ of types.  If that sequence is empty, then {\tt $A =$
235        unit}; if the sequence has only one element $T_1$, then $A = T_1$.
236      Otherwise $A$ is a tuple type {\tt $T_1$ * $\ldots$ * $T_k$}.
237    \item If $f$'s result is neither a {\tt struct} nor a {\tt union},
238      then $T_1$ encodes the type of $f$'s first argument, $T_2$ that of
239      the second, $T_3$ that of the third, and so on.
240    \item If $f$'s result is some {\tt struct} or some {\tt union}, then
241      $T_1$ will be {\tt ($\tau$, C.rw) C.su\_obj'} with $\tau$
242      instantiated to the appropriate {\tt struct}- or {\tt union}-tag
243      type.  Moreover, we then also have $B = T_1$. $T_2$ encodes the type
244      of $f$'s {\em first} argument, $T_3$ that of the second.  (In
245      general, $T_{i+1}$ will encode the type of the $i$th argument of
246      $f$ in this case.)
247    \item The encoding of the $i$th argument of $f$ ($T_i$ or $T_{i+1}$
248      depending on $f$'s return type) is the light-weight ML equivalent of
249      the C type of that argument.
250    \item An argument of C {\tt struct}- or {\tt union}-type corresponds
251      to {\tt ($\tau$, C.ro) C.su\_obj'} with $\tau$ instantiated to the
252      appropriate tag type.
253    \item If $f$'s result type is {\tt void}, then {\tt $B =$ unit}.  If
254      the result type is not a {\tt struct}- or {\tt union}-type, then $B$
255      is the light-weight ML encoding of that type.  Otherwise $B = T_1$
256      (see above).
257    \end{itemize}
258    
259    \subsubsection*{Examples}
260    
261    \begin{small}
262    \begin{center}
263    \begin{tabular}{c|c}
264    C declaration & signature of ML-side representation \\ \hline\hline
265    {\tt void f1 (void);}
266    &
267    \begin{minipage}{4in}
268    \begin{verbatim}
269    
270    structure F_f1 : sig
271        val typ  : (unit -> unit) C.fptr C.T.typ
272        val fptr : unit -> (unit -> unit) C.fptr
273        val f    : unit -> unit
274        val f'   : unit -> unit
275    end
276    
277    \end{verbatim}
278    \end{minipage}
279    \\ \hline
280    {\tt int f2 (void);}
281    &
282    \begin{minipage}{4in}
283    \begin{verbatim}
284    
285    structure F_f2 : sig
286        val typ  : (C.sint -> unit) C.fptr C.T.typ
287        val fptr : unit -> (C.sint -> unit) C.fptr
288        val f    : MLRep.Signed.int -> unit
289        val f'   : MLRep.Signed.int -> unit
290    end
291    
292    \end{verbatim}
293    \end{minipage}
294    \\ \hline
295    {\tt void f3 (int);}
296    &
297    \begin{minipage}{4in}
298    \begin{verbatim}
299    
300    structure F_f3 : sig
301        val typ  : (unit -> C.sint) C.fptr C.T.typ
302        val fptr : unit -> (unit -> C.sint) C.fptr
303        val f    : unit -> MLRep.Signed.int
304        val f'   : unit -> MLRep.Signed.int
305    end
306    
307    \end{verbatim}
308    \end{minipage}
309    \\ \hline
310    {\tt void f4 (double, struct s*);}
311    &
312    \begin{minipage}{4in}
313    \begin{verbatim}
314    
315    structure F_f4 : sig
316        val typ  : (C.double *
317                    (ST_s.tag, C.rw) C.su_obj C.ptr'
318                    -> unit)
319                        C.fptr C.T.typ
320        val fptr : unit -> (C.double *
321                            (ST_s.tag, C.rw) C.su_obj C.ptr'
322                            -> unit) C.fptr
323        val f    : MLRep.Real.real *
324                   (ST_s.tag, C.rw) C.su_obj C.ptr
325                   -> unit
326        val f'   : MLRep.Real.real *
327                   (ST_s.tag, C.rw) C.su_obj C.ptr'
328                   -> unit
329    end
330    
331    \end{verbatim}
332    \end{minipage}
333    \end{tabular}
334    \end{center}
335    \end{small}
336    
337    \begin{small}
338    \begin{center}
339    \begin{tabular}{c|c}
340    C declaration & signature of ML-side representation \\ \hline\hline
341    \begin{minipage}{2in}
342    \begin{verbatim}
343    struct s *f5 (float);
344    /* s incomplete */
345    \end{verbatim}
346    \end{minipage}
347    &
348    \begin{minipage}{4in}
349    \begin{verbatim}
350    
351    structure F_f5 : sig
352        val typ  : (C.float
353                    -> (ST_s.tag, C.rw) C.su_obj C.ptr')
354                        C.fptr C.T.typ
355        val fptr : unit -> (C.float
356                           -> (ST_s.tag, C.rw) C.su_obj C.ptr')
357                               C.fptr
358        val f'   : MLRep.Real.real ->
359                   (ST_s.tag, C.rw) C.su_obj C.ptr'
360    end
361    
362    \end{verbatim}
363    \end{minipage}
364    \\ \hline
365    \begin{minipage}{2in}
366    \begin{verbatim}
367    struct t *f6 (float);
368    /* t complete */
369    \end{verbatim}
370    \end{minipage}
371    &
372    \begin{minipage}{4in}
373    \begin{verbatim}
374    
375    structure F_f6 : sig
376        val typ  : (C.float
377                    -> (S_t.tag, C.rw) C.su_obj C.ptr')
378                        C.fptr C.T.typ
379        val fptr : unit -> (C.float
380                           -> (S_t.tag, C.rw) C.su_obj C.ptr')
381                               C.fptr
382        val f    : MLRep.Real.real ->
383                   (S_t.tag, C.rw) C.su_obj C.ptr
384        val f'   : MLRep.Real.real ->
385                   (S_t.tag, C.rw) C.su_obj C.ptr'
386    end
387    
388    \end{verbatim}
389    \end{minipage}
390    \\ \hline
391    \begin{minipage}{2in}
392    \begin{verbatim}
393    struct t f7 (int, double);
394    /* t complete */
395    \end{verbatim}
396    \end{minipage}
397    &
398    \begin{minipage}{4in}
399    \begin{verbatim}
400    
401    structure F_f7 : sig
402        val typ  : ((S_t.tag, C.rw) C.su_obj' *
403                    C.sint * C.double
404                    -> (S_t.tag, C.rw) C.su_obj')
405                        C.fptr C.T.typ
406        val fptr : unit -> ((S_t.tag, C.rw) C.su_obj' *
407                            C.sint * C.double
408                            -> (S_t.tag, C.rw) C.su_obj')
409                                C.fptr
410        val f    : (S_t.tag, C.rw) C.su_obj *
411                   MLRep.Signed.int *
412                   MLRep.Real.real
413                   -> (S_t.tag, C.rw) C.su_obj
414        val f'   : (S_t.tag, C.rw) C.su_obj' *
415                   MLRep.Signed.int *
416                   MLRep.Real.real
417                   -> (S_t.tag, C.rw) C.su_obj'
418    end
419    
420    \end{verbatim}
421    \end{minipage}
422    \end{tabular}
423    \end{center}
424    \end{small}
425    
426    \subsection{Type definitions ({\tt typedef})}
427    
428    ...
429    
430    \subsection{{\tt struct} and {\tt union}}
431    
432    ...
433    
434    \subsection{Enumerations ({\tt enum})}
435    
436    ...
437    
438  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
439  %\appendix  %\appendix
440  %\input{A-syntax}  %\input{A-syntax}

Legend:
Removed from v.1554  
changed lines
  Added in v.1560

root@smlnj-gforge.cs.uchicago.edu
ViewVC Help
Powered by ViewVC 1.0.0