Plan 9 from Bell Labs’s /usr/web/sources/contrib/fernan/nhc98/docs/ffi.html

Copyright © 2021 Plan 9 Foundation.
Distributed under the MIT License.
Download the Plan 9 distribution.


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>Primitive FFI in nhc98</title></head>
<body bgcolor='#ffffff'>
<table><tr><td width=500>

<center>
  <h1>Primitive FFI in nhc98</h1>
</center>
<hr>

<p>
The <b>nhc98</b> compiler contains an implementation of the
<em>standard foreign function interface</em> that is also available
in <em>Hugs</em> and <em>ghc</em>.  The most recent released version
of <b>nhc98</b> implements the latest standard syntax for foreign
function declarations, as specified at:

<a href="http://www.cse.unsw.edu.au/~chak/haskell/ffi/">
<tt>http://www.cse.unsw.edu.au/~chak/haskell/ffi/</tt></a>

<p>
The FFI standard specifies both the basic mechanism as a language
extension, and a layer of libraries.  The libraries contain many useful
datatypes and access functions, for instance to manage memory storage
in the foreign language.  nhc98's implementation includes two versions
of these libraries: <a href="libs/FFI.html">nhc98's internal FFI
library</a>, and the <a href="http://www.haskell.org/ghc/ffi">standard
portable Foreign libraries</a>.  The latter collection departs from
the official standard only in the use of the hierarchical module
namespace instead of the official flat namespace.

<p>
<br>

<h3>Compliance notes</h3>
<p>
<ul>
<li> Supported calling conventions are: <tt>ccall</tt>, <tt>noproto</tt>,
     and <tt>cast</tt>.  (The latter two are non-standard, see below.)
     Unsupported calling conventions are: <tt>stdcall</tt>, <tt>jvm</tt>,
     <tt>dotnet</tt>, <tt>cplusplus</tt>.
<li> <tt>foreign import "wrapper"</tt> is not yet supported.
<li> The annotation <tt>unsafe</tt> has no special meaning in <b>nhc98</b>;
     it is purely a speed optimisation for <em>ghc</em>.
<li> A <tt>foreign export</tt> specification is treated as the actual
     type signature for the exported function.  You are not allowed a
     second (possibly more general) type signature.
<li> Hence, you cannot <tt>foreign export</tt> any function that
     requires a class dictionary.
</ul>

<h3>Extensions</h3>
<p>
<ul>
<li> Two non-standard calling conventions are provided.
     <tt>cast</tt> indicates that an arity-1 foreign import is only being
     used for its C type-cast, and hence eliminates some runtime overheads.
     For example,
     <pre>  foreign import cast floatToDouble :: Float -&gt; Double </pre>
     The calling convention <tt>noproto</tt> is essentially the same as
     <tt>ccall</tt> but tells the compiler not to generate a C function
     prototype for the external function.  For example,
     <pre>  foreign import sin noproto :: Float -&gt; Float </pre>
     eliminates the normal generation of
     <pre>  extern float sin (float); </pre>
     for occasions when such a declaration might conflict with an external
     declaration.  (Note, if you mention a header file in the foreign entity
     description, this has the same effect as noproto - i.e. the header file
     declaration is used in preference to generating a prototype.)
<li> The set of primitive types allowed across the FFI is slightly
     larger in <b>nhc98</b> than the standard allowed set:  we
     allow <tt>PackedString</tt> to be passed - these are genuine
     null-terminated C-style strings.  Used as a result type, the
     string is copied into the Haskell heap (allowing the original
     pointer to be freed safely); used as an argument type, a pointer
     to the heap-allocated string is passed to C (i.e. do not free
     it!).  However, we recommend you use the standard type
     <tt>Foreign.C.String</tt> instead - it is more portable.
<li> Additionally, we allow any non-primitive datatype to be passed
     across the FFI (but give a <em>Warning</em> for each one) as a heap
     pointer.  This feature should only be used by serious implementers,
     because any foreign code manipulating non-primitive data must use
     <b>nhc98</b>'s internal heap format.
</ul>

<h3>Recent Changes</h3>
<p>
<ul>
<li> In a <tt>foreign import</tt> specification, the specification of a
     C header file or library in the "external entity" string was
     previously ignored.  <b>nhc98</b> now generates <tt>#include</tt>
     for these header files.  Where a header file is specified, the
     compiler does not generate its own prototype for the foreign function,
     as if the 'noproto' calling convention had been used.
<li> <tt>foreign import "dynamic"</tt> is now fully supported.
</ul>
<p>
<br>

<hr>
<p>
The latest updates to these pages are available on the WWW from
<a href="http://www.haskell.org/nhc98/">
<tt>http://www.haskell.org/nhc98/</tt></a>

<p>
This page last modified: 16th June 2003<br>
<a href="http://www.cs.york.ac.uk/fp/">
York Functional Programming Group</a><br>

</td></tr></table>
</body></html>


Bell Labs OSI certified Powered by Plan 9

(Return to Plan 9 Home Page)

Copyright © 2021 Plan 9 Foundation. All Rights Reserved.
Comments to [email protected].