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 1560, Fri Jul 23 23:23:09 2004 UTC revision 1568, Wed Jul 28 23:23:57 2004 UTC
# Line 1  Line 1 
1  % -*- latex -*-  % -*- latex -*-
2  \documentclass[titlepage,letterpaper]{article}  \documentclass[titlepage,letterpaper]{article}
3    \usepackage{latexsym}
4  \usepackage{times}  \usepackage{times}
5  \usepackage{hyperref}  \usepackage{hyperref}
6    
7    \newcommand{\gentool}{{\tt ml-nlffigen}}
8    
9  \marginparwidth0pt\oddsidemargin0pt\evensidemargin0pt\marginparsep0pt  \marginparwidth0pt\oddsidemargin0pt\evensidemargin0pt\marginparsep0pt
10  \topmargin0pt\advance\topmargin by-\headheight\advance\topmargin by-\headsep  \topmargin0pt\advance\topmargin by-\headheight\advance\topmargin by-\headsep
11  \textwidth6.7in\textheight9.1in  \textwidth6.7in\textheight9.1in
# Line 53  Line 56 
56  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
57  \section{Translation conventions}  \section{Translation conventions}
58    
59  The {\tt ml-nlffigen} tool generates one ML structure for each  The {\gentool} tool generates one ML structure for each
60  exported C definition.  In particular, there is one structure per  exported C definition.  In particular, there is one structure per
61  external variable, function, {\tt typedef}, {\tt struct}, {\tt union},  external variable, function, {\tt typedef}, {\tt struct}, {\tt union},
62  and {\tt enum}.  and {\tt enum}.
# Line 99  Line 102 
102    
103  \subsubsection*{Examples}  \subsubsection*{Examples}
104    
105    \begin{small}
106  \begin{center}  \begin{center}
107  \begin{tabular}{c|c}  \begin{tabular}{c|c}
108  C declaration & signature of ML-side representation \\ \hline\hline  C declaration & signature of ML-side representation \\ \hline\hline
109  {\tt extern int i;}  \begin{minipage}{2in}
110    \begin{verbatim}
111    extern int i;
112    \end{verbatim}
113    \end{minipage}
114  &  &
115  \begin{minipage}{4in}  \begin{minipage}{4in}
116  \begin{verbatim}  \begin{verbatim}
# Line 117  Line 125 
125  \end{verbatim}  \end{verbatim}
126  \end{minipage}  \end{minipage}
127  \\ \hline  \\ \hline
128  {\tt extern const double d;}  \begin{minipage}{2in}
129    \begin{verbatim}
130    extern const double d;
131    \end{verbatim}
132    \end{minipage}
133  &  &
134  \begin{minipage}{4in}  \begin{minipage}{4in}
135  \begin{verbatim}  \begin{verbatim}
# Line 171  Line 183 
183  \end{minipage}  \end{minipage}
184  \end{tabular}  \end{tabular}
185  \end{center}  \end{center}
186    \end{small}
187    
188  %-------------------------------------------------------------------------  %-------------------------------------------------------------------------
189  \subsection{Functions}  \subsection{Functions}
# Line 425  Line 438 
438    
439  \subsection{Type definitions ({\tt typedef})}  \subsection{Type definitions ({\tt typedef})}
440    
441  ...  In C a {\tt typedef} declaration associates a type name $t$ with a
442    type $t_C$.  On the ML side, $t$ is represented by an ML structure
443    {\tt T\_$t$}.  This structure contains a type abbreviation {\tt t} for
444    the ML encoding of $t_C$ and, provided $t_C$ is not {\em incomplete},
445    a value {\tt typ} of type {\tt t C.T.typ} with run-time type
446    information regarding $t_C$.
447    
448    \subsubsection*{Examples}
449    
450    \begin{small}
451    \begin{center}
452    \begin{tabular}{c|c}
453    C declaration & signature of ML-side representation \\ \hline\hline
454    \begin{minipage}{2in}
455    \begin{verbatim}
456    typedef int t1;
457    \end{verbatim}
458    \end{minipage}
459    &
460    \begin{minipage}{4in}
461    \begin{verbatim}
462    
463    structure T_t1 : sig
464        type t   = C.sint
465        val typ  : t C.T.typ
466    end
467    
468    \end{verbatim}
469    \end{minipage}
470    \\ \hline
471    \begin{minipage}{2in}
472    \begin{verbatim}
473    typedef struct s t2;
474    /* s incomplete */
475    \end{verbatim}
476    \end{minipage}
477    &
478    \begin{minipage}{4in}
479    \begin{verbatim}
480    
481    structure T_t2 : sig
482        type t  = ST_s.tag C.su
483    end
484    
485    \end{verbatim}
486    \end{minipage}
487    \\ \hline
488    \begin{minipage}{2in}
489    \begin{verbatim}
490    typedef struct s *t3;
491    /* s incomplete */
492    \end{verbatim}
493    \end{minipage}
494    &
495    \begin{minipage}{4in}
496    \begin{verbatim}
497    
498    structure T_t3 : sig
499        type t  = (ST_s.tag, C.rw) C.su_obj C.ptr
500    end
501    
502    \end{verbatim}
503    \end{minipage}
504    \\ \hline
505    \begin{minipage}{2in}
506    \begin{verbatim}
507    typedef struct t t4;
508    /* t complete */
509    \end{verbatim}
510    \end{minipage}
511    &
512    \begin{minipage}{4in}
513    \begin{verbatim}
514    
515    structure T_t4 : sig
516        type t  = ST_t.tag C.su
517        val typ : t T.typ
518    end
519    
520    \end{verbatim}
521    \end{minipage}
522    \end{tabular}
523    \end{center}
524    \end{small}
525    
526  \subsection{{\tt struct} and {\tt union}}  \subsection{{\tt struct} and {\tt union}}
527    
528  ...  The type identity of a named C {\tt struct} (or {\tt union}) is
529    provided by a unique ML {\em tag} type.  There is a 1-1 correspondence
530    between C tag names $t$ for {\tt struct}s on one side and ML tag types
531    $s_t$ on the other.  An analogous correspondence exists between C tag
532    names $t$ for {\tt union}s and ML tag types $u_t$.  Notice that these
533    correspondences are {\em independent of the actual declaration} of the
534    C {\tt struct} or {\tt union} in question.
535    
536    A C type of the form {\tt struct $t$} is represented in ML as {\tt
537      $s_t$ C.su}, a type of the form {\tt union $t$} as {\tt $u_t$ C.su}.
538    For example, this means that a heavy-weight non-constant memory object
539    of C type {\tt struct $t$} has ML type {\tt ($s_t$ C.su, C.rw) C.obj}
540    which can be abbreviated to {\tt ($s_t$, C.rw) C.su\_obj}.
541    
542    All ML types {\tt ($\tau$ C.su, $\zeta$) C.obj} are originally
543    completely abstract: they does not come with any operations that could
544    be applied to their values.  In C, the operations to be applied to a
545    {\tt struct}- or {\tt union}-value is field selection.  Field
546    selection {\em does} depend on the actual C declaration, so it is
547    {\gentool}'s job to generate a set of ML-side field-accessors that
548    correspond to field-access operations in C.
549    
550    Each field is represented by a function mapping a memory object of the
551    {\tt struct}- or {\tt union}-type to an object of the respective field
552    type.  Let {\tt int i;} and {\tt const double d;} be fields of some
553    {\tt struct t} and let {\tt tag} be the ML tag type corresponding to
554    {\tt t}.  Here are the types of the (heavy-weight) access functions
555    for {\tt i} and {\tt d}:
556    
557    \begin{small}
558    \begin{center}
559    \begin{tabular}{l@{~~~~$\leadsto$~~~~}l}
560    {\tt int i;} &
561      {\tt val f\_i : (tag C.su, 'c) C.obj -> (C.sint, 'c) C.obj} \\
562    {\tt const double d;} &
563      {\tt val f\_d : (tag C.su, 'c) C.obj -> (C.double, C.ro) C.obj}
564    \end{tabular}
565    \end{center}
566    \end{small}
567    
568    \noindent Notice how each field access function is polymorphic in the
569    {\tt const} property of the argument object.  For fields declared {\tt
570      const}, the result always uses {\tt C.ro} while for ordinary fields
571    the argument's type is used---reflecting the idea that a field is
572    considered writable if it has not been declared {\tt const} and, at
573    the same time, the enclosing {\tt struct} or {\tt union} is writable.
574    
575    \subsubsection*{Incomplete declarations}
576    
577    If the {\tt struct} or {\tt union} is incomplete (i.e., if only its
578    tag $t$ is known), then {\gentool} will merely generate an ML structure
579    (called {\tt ST\_$t$} for {\tt struct} and {\tt UT\_$t$} for {\tt
580      union}) with a single type {\tt tag} that is an abbreviation for the
581    library-defined type that corresponds to tag $t$.
582    
583    \subsubsection*{Complete declarations}
584    
585    If the {\tt struct} or {\tt union} with tag $t$ is complete, then
586    {\gentool} will generate an ML structure (called {\tt S\_$t$} for {\tt
587      struct} and {\tt U\_$t$} for {\tt union}) which contains at least:
588    \begin{description}\setlength{\itemsep}{0pt}
589    \item[{\tt type tag}] --- an abbreviation for the library-defined type
590      that corresponds to $t$
591    \item[{\tt val size}] --- a value representing information about the
592      size of memory objects of this {\tt struct}- or {\tt union}-type.
593      The ML type of {\tt size} is {\tt tag C.su C.S.size}.
594    \item[{\tt val typ}] --- a value representing run-time type
595      information corresponding to this {\tt struct}- or {\tt union}-type.
596      The ML type of {\tt typ} is {\tt tag C.su C.T.typ}.
597    \end{description}
598    In addition to this, there will be a light-weight access function {\tt
599      f\_$f$'} for each field or bitfield $f$ of the {\tt struct} or {\tt
600      union}.
601    
602    If $f$ is a regular field, then {\tt f\_$f$'} maps a value of type
603    {\tt (tag C.su, $\zeta$) C.obj'} to a value of type {\tt (${\tau}_f$,
604      ${\zeta}_f$) C.obj'} where ${\tau}_f$ is the ML type encoding the C
605    type of field $f$ and where {\tt ${\zeta}_f =$ C.rw} when $f$ was
606    declared {\tt const} or ${\zeta}_f = \zeta$ otherwise.
607    
608    If $f$ is a bitfield, then the result type of {\tt f\_$f$'} is either
609    {\tt ${\zeta}_f$ C.sbf} or {\tt ${\zeta}_f$ C.ubf}, depending on
610    whether the bitfield's C type is {\tt signed} or {\tt unsigned}.
611    
612    For every field $f$ that is either a regular field of complete type or
613    a bitfield there is also a heavy-weight access function {\tt f\_$f$}
614    which maps {\tt (tag C.su, $\zeta$) C.obj} to {\tt (${\tau}_f$,
615      ${\zeta}_f$) C.obj}, {\tt ${\zeta}_f$ C.sbf}, or {\tt ${\zeta}_f$
616      C.ubf}.
617    
618  \subsection{Enumerations ({\tt enum})}  \subsection{Enumerations ({\tt enum})}
619    

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

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