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 1557, Wed Jul 21 23:19:18 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}:  \paragraph*{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$.  This structure always contains at last three values: {\tt
180      typ}, {\tt fptr}, and {\tt f'}.  Variable {\tt typ} holds run-time
181    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} represents a C pointer to $f$.  And {\tt f'} is an
185    ML function that dispatches a call of $f$ (through {\tt fptr}), using
186    ``light-weight'' types for arguments and results where this
187    distinction is relevant.  If the result type of $f$ is {\em complete},
188    then {\tt F\_}$f$ will also contain a function {\tt f}, using
189    ``heavy-weight'' argument- and 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.
198    \item[{\tt val fptr}] is a function that returns the (heavy-weight)
199      function pointer to $f$. The type of {\tt fptr} is {\tt unit -> ($A$
200        -> $B$) C.fptr}.  The encodings of argument- and result types is
201      the same as the one used for {\tt typ}.  Notice that even though
202      {\tt fptr} is a heavy-weight value carrying run-time type
203      information, pointer arguments within $A$ or $B$ still use the
204      light-weight version!
205    \item[!{\tt val f}] is an ML function that dispatches a call to $f$
206      via {\tt fptr}.  For convenience, {\tt f} has built-in conversions
207      for arguments (from ML to C) and the result (from C to ML).  For
208      example, if $f$ has an argument of type {\tt double}, then {\tt f}
209      will take an argument of type {\tt MLRep.Real.real} in its place and
210      implicitly convert it to its C equivalent using {\tt
211        C.Cvt.c\_double}.  Similarly, if $f$ returns an {\tt unsigned
212        int}, then {\tt f} has a result type of {\tt MLRep.Unsigned.word}.
213      This is done for all types that have a conversion function in
214      {\tt C.Cvt}.
215      Pointer values (as well as the object argument used for {\tt
216        struct}- or {\tt union}-return values) are taken and returned in
217      their heavy-weight versions.  Function {\tt f} will not be generated
218      if the return type of $f$ is incomplete.
219    \item[{\tt val f'}] is the light-weight equivalent to {\tt f}.  a
220      light-weight function.  The main difference is that pointer- and
221      object-values are passed and returned in their light-weight
222      versions.
223    \end{description}
224    
225    \paragraph*{Examples}
226    
227    ...
228    
229    \subsubsection{Type encoding rules for {\tt ($A$ -> $B$) C.fptr}}
230    
231    ...
232    
233    
234    
235  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
236  %\appendix  %\appendix
237  %\input{A-syntax}  %\input{A-syntax}

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

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