FFI Report, CVS Id 1.5

[Manuel M. T. Chakravarty]

There is now a new revision of the definition at

  http://www.cse.unsw.edu.au/~chak/haskell/ffi.{ps.gz,tex}

"Simon Peyton-Jones" <simonpj at microsoft.com> wrote,

> Suggestion: would you like to add this to the CVS repository.
> Then others can get hold of it, and even modify it (e.g. correct
> typos, add examples).  It's inefficient to type a message saying
> "add a comma after "..bubble.."".
> 
> There's an obvious place for it.  The Haskell Report is in the
> CVS repository cvs.haskell.org in the 'module' haskell-report.
> Thus
> 	cvs checkout haskell-report
> 
> There is a sub-directory for report/ and another for libraries/,
> so you could just create a directory for ffi/.

Done.  The .tex and .bib files are in this directory.  For
formatting the file, my grammar.sty is missing.  I will soon
put this in there, too.

However, concurrent editing of text files is much more
dangerous conflictwise than program code.  So, please always
update the local copy before changing it and check in
changes immediately to avoid problems.  Moreover, I think,
any changes concerning the semantics of the document should
still go through me.

> *  I strongly suggest however adding a brief collection of examples 
> as Section 1.3  (or Section 2).

Examples before the definitions?  Won't they be more
meaningful later on?

> * Similarly, for each language-specific section, we must add a
> collection of examples.
> No one who was not intimately familiar with the FFI would
> be able to make sense of 'import dynamic' or 'import wrapper'.  

Yes, I added a few now, but I am aware that these are still
not sufficient.  More to come...

> * You mention en passant that there's a new type CInt.  Very good, but 
> the full set of types (and their operations) must be defined in the 
> language-specific sections.  Indeed, I suggest we take 3.2 and 
> make it a top-level Section, with a sub-section for each language.

The types have to be defined, but I was planing to do that
as part of the libraries (where they are defined).  One
reason for that is that with calling conventions like
dotnet, the correlation between calling convention and
language (and so language-specific types) becomes unclear.

> * "external types" are mentioned in 3.2.1 but nowhere defined.

> * Nowhere do you say that in 
> 	foreign import ... foo :: type
>   that this defines the Haskell variable 'foo' with type 'type'.
> (Currently
>   it's just "defines a variable", with nothing about type.)

I have filled in the sections detailing import and export
declarations and foreign types now.

> * I think we are agreed that the stuff about marshalling libraries
> belongs in
> this document too.  Much of it is already written.  Could it be
> incorporated?

Yes.  However, as the libraries are the most stable part of
the whole FFI story at the moment and incorporating the
exiting descriptions is largely an exercise in type setting,
I was leaving this until the rest has settled.

Foreign Types
~~~~~~~~~~~~~
This looks quite different from the old FFI spec.  Problems
with old specification:

* It doesn't make much sense to name data constructors in
  the grammar (we don't know from which module they are) and
  the grammar didn't consider qualified identifiers.

* Doesn't take the reversed data flow between foreign import
  and export into account (important for where `ForeignPtr's
  can appear).

* The treatment of newtypes was rather ad hoc.

The new definition reduces the problem of defining exactly
which types can be marshalled to a reference to Storable.
IMHO this is more elegant and more rigorous.  However, there
is one caveat to cleanly defining it, newtypes that need to
make use of the "newtype transparency" during marshalling
have to include a `deriving Storable' in their definition.

Consequently, Storable must be derivable.  This, I believe,
is a reasonable extensions as the Haskell 98 report says in
Section~4.3.3, ``Classes defined by the standard libraries
may also be derivable.''  The restriction would be that only
newtypes of instances of Storable can derive Storable.

Open questions
~~~~~~~~~~~~~~

* Consider

    foreign import "foo" foo :: t

  Currently, it can also be written in the following forms:

    foreign import "static foo" foo :: t
    foreign import "static"     foo :: t
    foreign import ""           foo :: t

  Is the last one nice?  Shall we make the external entity
  optional as in

    foreign import              foo :: t

  and make it default to "".  (The same issue arise for
  foreign export, of course.)

* How feasible is it not to allow exceptions to be
  propagated from an external entity to Haskell land in case
  of JNI?

* The old FFI spec restricted `ft' to `prim_args -> IO
  prim_result'.  Why didn't forbid thunks and pure
  functions?  Is this really necessary?

* How many calling conventions should we nail down now?
  What should we say about the others (in particular
  cplusplus)?

Note
~~~~

I have added a restriction: exported variables must be
defined by a function or pattern binding in the *same*
module.

This shouldn't be a serious restriction in practice, but
may make live easier for some systems.

Any opinions regarding the changes and especially regarding
the open questions?

Cheers,
Manuel