FFI Addendum, RC3 & Open Issues

[Manuel M. T. Chakravarty]

I have put Release Candidate 3 up at

  http://www.cse.unsw.edu.au/~chak/haskell/ffi/

Changes wrt to the last version are the following:

* 3.2: Clarified the description of foreign types; so far, `IO ()' was
    strictly speaking not included as a valid return type.
* 4.1.5: New section discussing the traps & pitfalls of type promotion with
    C bindings.
* 5.8: Clarified documentation for `MarshalAlloc.free'.
* 5.8: Added `MarshalAlloc.realloc'.

Moreover, I would like to draw your attention to the
following points, which we should solve before I post the
next version to `haskell at haskell.org':

* Olaf Chitil has pointed out some unclear points wrt to ()
  and IO () as a result type in foreign declarations in the
  previous version of the Addendum.  I have edited Section
  3.2 to improve this, but you may want to check out that
  the new version meets your expectations.

* I have added Section 4.1.5 as a consequence of the recent
  discussion on argument type promotion on this list.  It
  seemed that everybody agreed what the FFI should do, but
  that a detailed explanation in the specification is
  needed, so I have added one.  Please check whether you
  find it sufficient.

* I think, for reasons of orthogonality `MarshalAlloc'
  should include

    realloc :: Storable b => Ptr a -> IO (Ptr b)

  I have added this in the document.  Let me know if anybody
  disagrees with this.

* There is the open question, raised by SPJ, of whether we
  like to have something like

    import_entity -> [String]
    export_entity -> [String]

  See my message from yesterday.

* Sigbjorn, while adding support for OS threads to GHC, has
  introduced a new safety mode `threadsafe'.  It seems
  worthwhile to include this into the Addendum.  On systems
  that don't support OS threads, `threadsafe' might behave
  like `safe', but at least code that uses `threadsafe'
  would still be valid on other systems.  The semantics is
  as follows:

   unsafe	must not call back
 
   safe		may call back; if it blocks outside Haskell,
		the whole Haskell system blocks
 
   threadsafe	on systems supporting OS threads, the
		Haskell runtime will not block, even if the
		call blocks;
 		must call an OS-thread safe procedure
 
  ('safe' remains the default.)

If there are no objections, I will add the latter two
changes to the FFI Addendum.

Cheers,
Manuel