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 1567, Wed Jul 28 23:23:13 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 522  Line 525 
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.1567  
changed lines
  Added in v.1568

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