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

SCM Repository

[smlnj] View of /sml/trunk/src/ml-nlffigen/README
ViewVC logotype

View of /sml/trunk/src/ml-nlffigen/README

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1011 - (download) (annotate)
Thu Jan 10 20:22:04 2002 UTC (18 years, 4 months ago) by blume
File size: 7853 byte(s)
updates to pgraph and, more importantly, to NLFFI
Copyright (c) 2001, Lucent Technologies, Bell Laboratories

author: Matthias Blume (blume@research.bell-labs.com)

This directory contains ML-NLFFI-Gen, a glue-code generator for
the new "NLFFI" foreign function interface.  The generator reads
C source code and emits ML code along with a description file for CM.

Compiling this generator requires the C-Kit ($/ckit-lib.cm) to be
installed.

---------------------------------------------------------------------

January 10, 2002:  Major changes:

I reworked the glue code generator in a way that lets generated code
scale better -- at the expense of some (mostly academic) generality.

Changes involve the following:

1. The functorization is gone.

2. Every top-level C declaration results in a separate top-level
   ML equivalent (implemented by its own ML source file).

3. Incomplete pointer types are treated as new abstract types without
   possibility of later making them "concrete".  (It is here were
   we lose some generality.  Of course, one can always work around
   such problems by going through "voidptr" where necessary.)
   Alternatively, there is the possibility of the programmer
   providing definitions for such incomplete types.

4. All related C sources must be supplied to ml-nlffigen together.
   Types incomplete in one source but complete in another get
   automatically completed in a cross-file fashion.

5. The handle for the shared library to link to is now abstracted as
   a function closure.  Moreover, it must be supplied as a top-level
   variable (by the programmer).  For this purpose, ml-nlffigen has
   corresponding command-line options.

These changes mean that even very large (in number of exported definitions)
libraries such as, e.g., GTK can now be handled gracefully without
reaching the limits of the ML compiler's abilities.

[The example of GTK -- for which ml-nlffigen creates several thousands (!)
of separate ML source files -- puts an unusal burden on CM, though.
However, aside from running a bit longer than usual, CM handles loads
of this magnitute just fine.  Stabilizing the resulting library solves
the problem entirely as far as later clients are concerned.]


Sketch of translation- (and naming-) scheme:

  struct foo { ... }
      -->   structure ST_foo   in    st-foo.sml  (not exported)
               basic type info (name, size)
       &    structure S_foo    in    s-foo.sml
               abstract interface to the type
                    field accessors f_xxx  (unless -light)
                                and f_xxx' (unless -heavy)
                    field types     t_f_xxx
                    field RTTI      typ_f_xxx

  union foo { ... }
      -->   structure UT_foo   in    ut-foo.sml  (not exported)
               basic type info (name, size)
       &    structure U_foo    in    u-foo.sml
               abstract interface to the type
                    field accessors f_xxx  (unless -light)
                                and f_xxx' (unless -heavy)
                    field types     t_f_xxx
                    field RTTI      typ_f_xxx

  struct { ... }
      like struct <n> { ... }, where <n> is a fresh integer

  union { ... }
      like union <n> { ... }, where <n> is a fresh integer

  enum foo { ... }
      -->   structure E_foo   in     e-foo.sml
               enum constants    e_xxx

  enum { ... }
      like enum <n> { ... }, where <n> is a fresh integer

  T foo (T, ..., T)  (global function/function prototype)
      -->   structure F_foo   in     f-foo.sml
               containing three/four members:
                    typ :  RTTI
                    fptr:  thunkified fptr representing the C function
            maybe   f'  :  light-weight function wrapper around fptr
                              Turned off by -heavy (see below).
            maybe   f   :  heavy-weight function wrapper around fptr
                              Turned off by -light (see below).

  T foo;  (global variable)
      -->   structure G_foo   in     g-foo.sml
               containing three members:
                    t   :  type
                    typ :  RTTI
                    obj :  thunkified object representing the C variable

  struct foo *  (without existing definition of struct foo; incomplete type)
      -->   structure IS_foo  in     iptrs.sml
               The structure is generated by instantiating functor
               PointerToIncompletType.
               This is turned off by specifying -incomplete (see below).

  union foo *   (without existing definition of struct foo; incomplete type)
      -->   structure IU_foo  in     iptrs.sml
               The structure is generated by instantiating functor
               PointerToIncompletType.
               This is turned off by specifying -incomplete (see below).

  Additional files for implementing function entry sequences are created
  and used internally.  They do not contribute exports, though.


Command-line options for ml-nlffigen:

  General syntax:   ml-nlffigen <option> ... [--] <C-file> ...

  Options:

   -dir <dir>   output directory where all generated files are placed
                default:  "NLFFI-Generated"
   -allSU       instructs ml-nlffigen to include all structs and unions,
                even those that are defined in included files (as opposed
                to files explicitly listed as arguments)
                default: off
   -width <w>   sets output line width (just a guess) to <w>
                default: 75
   -lambdasplit <x>   instructs ml-nlffigen to generate "lambdasplit"
                options for all ML files (see CM manual for what this means;
                it does not currently work anyway because cross-module
                inlining is broken).
                default: nothing
   -target <t>  Sets the target to <t> (which must be one of "sparc-unix",
                "x86-unix", or "x86-win32").
                default: current architecture
   -light       suppress "heavy" versions of function wrappers and
                field accessors; also resets any earlier -heavy to default
                default: not suppressed
   -heavy       suppress "light" versions of function wrappers and
                field accessors; also resets any earlier -light to default
                default: not suppressed
   -namedargs   instruct ml-nlffigen to generated function wrappers that
                use named arguments (ML records) instead of tuples if
                there is enough information for this in the C source;
                (this is not always very useful)
                default: off
   -incomplete  do not generate definitions for incomplete types;  these
                will then have to be provided by the programmer
                default: generate such definitions, making each incomplete
                type a new abstract type
   -libhandle <h>   Use the variable <h> to refer to the handle to the
                shared library object.  Given the constraints of CM, <h>
                must have the form of a long ML identifier, e.g.,
                MyLibrary.libhandle.
                default: Library.libh
   -include <f> Mention file <f> in the generated .cm file.  This option
                is necessary at least once for providing the library handle.
                It can be used arbitrarily many times, resulting in more
                than one such programmer-supplied file to be mentioned.
                If <f> is relative, then it must be relative to the directory
                specified in the -dir <dir> option.
   -cmfile <f>  Specify name of the generated .cm file, relative to
                the directory specified by the -dir <dir> option.
                default: nlffi-generated.cm
   --           Terminate processing of options, remaining arguments are
                taken to be C sources.


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