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
 [smlnj] / sml / trunk / src / ml-nlffi-lib / Doc / manual / nlffi.tex

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

revision 1557, Wed Jul 21 23:19:18 2004 UTC revision 1560, Fri Jul 23 23:23:09 2004 UTC
# Line 97  Line 97
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 176  Line 176
176  \subsection{Functions}  \subsection{Functions}
177
178  An external C function $f$ is represented by an ML structure {\tt  An external C function $f$ is represented by an ML structure {\tt
179    F\_}$f$.  This structure always contains at last three values: {\tt    F\_}$f$.  Each such structure always contains at last three values:
180    typ}, {\tt fptr}, and {\tt f'}.  Variable {\tt typ} holds run-time  {\tt typ}, {\tt fptr}, and {\tt f'}.  Variable {\tt typ} holds
181  type information regarding function pointers that share $f$'s  run-time type information regarding function pointers that share $f$'s
182  prototype.  The most important part of this information is the code  prototype.  The most important part of this information is the code
183  that implements native C calling conventions for these functions.  that implements native C calling conventions for these functions.
184  Variable {\tt fptr} represents a C pointer to $f$.  And {\tt f'} is an  Variable {\tt fptr} provides access to a C pointer to $f$.  And {\tt
185  ML function that dispatches a call of $f$ (through {\tt fptr}), using    f'} is an ML function that dispatches a call of $f$ (through {\tt
186  light-weight'' types for arguments and results where this    fptr}), using light-weight'' types for arguments and results.  If
187  distinction is relevant.  If the result type of $f$ is {\em complete},  the result type of $f$ is {\em complete}, then {\tt F\_}$f$ will also
188  then {\tt F\_}$f$ will also contain a function {\tt f}, using  contain a function {\tt f}, using heavy-weight'' argument- and
189  heavy-weight'' argument- and result-types.  result-types.
190
191  \paragraph*{Details}  \paragraph*{Details}
192
# Line 194  Line 194
194  \item[{\tt val typ}] holds run-time type information for pointers to  \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    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      ($A$ -> $B$) C.fptr C.T.typ} where $A$ and $B$ are types encoding
197    $f$'s argument list and result type, respectively.    $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)  \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$    function pointer to $f$. The type of {\tt fptr} is {\tt unit -> ($A$
201      -> $B$) C.fptr}.  The encodings of argument- and result types is      -> $B$) C.fptr}.  The encodings of argument- and result types in
202    the same as the one used for {\tt typ}.  Notice that even though    $A$ and $B$ is the same as the one used for {\tt typ} (see below).
203    {\tt fptr} is a heavy-weight value carrying run-time type    Notice that although {\tt fptr} is a heavy-weight value carrying
204    information, pointer arguments within $A$ or $B$ still use the    run-time type information, pointer arguments within $A$ or $B$ still
205    light-weight version!    use the light-weight version!
206  \item[!{\tt val f}] is an ML function that dispatches a call to $f$  \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    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    for arguments (from ML to C) and the result (from C to ML).  For
# Line 222  Line 223
223    versions.    versions.
224  \end{description}  \end{description}
225
226  \paragraph*{Examples}  \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  \subsubsection{Type encoding rules for {\tt ($A$ -> $B$) C.fptr}}  \subsection{{\tt struct} and {\tt union}}
431
432  ...  ...
433
434    \subsection{Enumerations ({\tt enum})}
435
436    ...
437
438  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
439  %\appendix  %\appendix

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