</VarListEntry>
<VarListEntry>
-<Term>Calling out to C:</Term>
+<Term>Foreign calling:</Term>
<ListItem>
<Para>
Just what it sounds like. We provide <Emphasis>lots</Emphasis> of rope that you
-can dangle around your neck. Please see <XRef LinkEnd="glasgow-ccalls">.
+can dangle around your neck. Please see <XRef LinkEnd="ffi">.
</Para>
</ListItem>
</VarListEntry>
</Para>
</Sect1>
-
-<Sect1 id="glasgow-ccalls">
-<Title>Calling C directly from Haskell</Title>
-
-<Para>
-<IndexTerm><Primary>C calls (Glasgow extension)</Primary></IndexTerm>
-<IndexTerm><Primary>_ccall_ (Glasgow extension)</Primary></IndexTerm>
-<IndexTerm><Primary>_casm_ (Glasgow extension)</Primary></IndexTerm>
-GOOD ADVICE: Because this stuff is not Entirely Stable as far as names
-and things go, you would be well-advised to keep your C-callery
-corraled in a few modules, rather than sprinkled all over your code.
-It will then be quite easy to update later on.
-</Para>
-
-<Sect2 id="ccall-intro">
-<Title><Function>_ccall_</Function> and <Function>_casm_</Function>: an introduction
-</Title>
-
-<Para>
-The simplest way to use a simple C function
-</Para>
-
-<Para>
-
-<ProgramListing>
-double fooC( FILE *in, char c, int i, double d, unsigned int u )
-</ProgramListing>
-
-</Para>
-
-<Para>
-is to provide a Haskell wrapper:
-</Para>
-
-<Para>
-
-<ProgramListing>
-fooH :: Char -> Int -> Double -> Word -> IO Double
-fooH c i d w = _ccall_ fooC (“stdin”::Addr) c i d w
-</ProgramListing>
-
-</Para>
-
-<Para>
-The function <Function>fooH</Function> unbox all of its arguments, call the C
-function <Function>fooC</Function> and box the corresponding arguments.
-</Para>
-
-<Para>
-One of the annoyances about <Function>_ccall_</Function>s is when the C types don't quite
-match the Haskell compiler's ideas. For this, the <Function>_casm_</Function> variant
-may be just the ticket (NB: <Emphasis>no chance</Emphasis> of such code going
-through a native-code generator):
-</Para>
-
-<Para>
-
-<ProgramListing>
-import Addr
-import CString
-
-oldGetEnv name
- = _casm_ “%r = getenv((char *) %0);” name >>= \ litstring ->
- return (
- if (litstring == nullAddr) then
- Left ("Fail:oldGetEnv:"++name)
- else
- Right (unpackCString litstring)
- )
-</ProgramListing>
-
-</Para>
-
-<Para>
-The first literal-literal argument to a <Function>_casm_</Function> is like a <Function>printf</Function>
-format: <Literal>%r</Literal> is replaced with the “result,” <Literal>%0</Literal>–<Literal>%n-1</Literal> are
-replaced with the 1st–nth arguments. As you can see above, it is an
-easy way to do simple C casting. Everything said about <Function>_ccall_</Function> goes
-for <Function>_casm_</Function> as well.
-</Para>
-
-<Para>
-The use of <Function>_casm_</Function> in your code does pose a problem to the compiler
-when it comes to generating an interface file for a freshly compiled
-module. Included in an interface file is the unfolding (if any) of a
-declaration. However, if a declaration's unfolding happens to contain
-a <Function>_casm_</Function>, its unfolding will <Emphasis>not</Emphasis> be emitted into the interface
-file even if it qualifies by all the other criteria. The reason why
-the compiler prevents this from happening is that unfolding <Function>_casm_</Function>s
-into an interface file unduly constrains how code that import your
-module have to be compiled. If an imported declaration is unfolded and
-it contains a <Function>_casm_</Function>, you now have to be using a compiler backend
-capable of dealing with it (i.e., the C compiler backend). If you are
-using the C compiler backend, the unfolded <Function>_casm_</Function> may still cause you
-problems since the C code snippet it contains may mention CPP symbols
-that were in scope when compiling the original module are not when
-compiling the importing module.
-</Para>
+<Sect1 id="sec-ffi">
+<Title>The foreign interface</Title>
<Para>
-If you're willing to put up with the drawbacks of doing cross-module
-inlining of C code (GHC - A Better C Compiler :-), the option
-<Option>-funfold-casms-in-hi-file</Option> will turn off the default behaviour.
-<IndexTerm><Primary>-funfold-casms-in-hi-file option</Primary></IndexTerm>
+The foreign interface consists of language and library support. The former
+is described later in <XRef LinkEnd="ffi">; the latter is outlined below,
+and detailed in the hslibs documentation.
</Para>
-</Sect2>
-
-<Sect2 id="glasgow-literal-literals">
-<Title>Literal-literals</Title>
-
-<Para>
-<IndexTerm><Primary>Literal-literals</Primary></IndexTerm>
-The literal-literal argument to <Function>_casm_</Function> can be made use of separately
-from the <Function>_casm_</Function> construct itself. Indeed, we've already used it:
-</Para>
-
-<Para>
-
-<ProgramListing>
-fooH :: Char -> Int -> Double -> Word -> IO Double
-fooH c i d w = _ccall_ fooC (“stdin”::Addr) c i d w
-</ProgramListing>
-
-</Para>
-
-<Para>
-The first argument that's passed to <Function>fooC</Function> is given as a literal-literal,
-that is, a literal chunk of C code that will be inserted into the generated
-<Filename>.hc</Filename> code at the right place.
-</Para>
-
-<Para>
-A literal-literal is restricted to having a type that's an instance of
-the <Literal>CCallable</Literal> class, see <XRef LinkEnd="ccall-gotchas">
-for more information.
-</Para>
-
-<Para>
-Notice that literal-literals are by their very nature unfriendly to
-native code generators, so exercise judgement about whether or not to
-make use of them in your code.
-</Para>
-
-</Sect2>
-
<Sect2 id="glasgow-foreign-headers">
<Title>Using function headers
</Title>
</Title>
<Para>
-This section documents GHC's implementation of multi-paramter type
+This section documents GHC's implementation of multi-parameter type
classes. There's lots of background in the paper <ULink
URL="http://research.microsoft.com/~simonpj/multi.ps.gz" >Type
classes: exploring the design space</ULink > (Simon Peyton Jones, Mark
</Para>
<Para>
-If your program has no <Function>_ccall_</Function>s/<Function>_casm_</Function>s in it, then a crash is
-always a BUG in the GHC system, except in one case: If your program is
-made of several modules, each module must have been compiled after any
-modules on which it depends (unless you use <Filename>.hi-boot</Filename> files, in which
-case these <Emphasis>must</Emphasis> be correct with respect to the module source).
+If your program has no foreign calls in it, then a crash is always a BUG in
+the GHC system, except in one case: If your program is made of several
+modules, each module must have been compiled after any modules on which it
+depends (unless you use <Filename>.hi-boot</Filename> files, in which case
+these <Emphasis>must</Emphasis> be correct with respect to the module
+source).
</Para>
<Para>
</Para>
<Para>
-Of course, if you have <Function>_ccall_</Function>s/<Function>_casm_</Function>s in your program then all
+Of course, if you have foreign calls in your program then all
bets are off, because you can trash the heap, the stack, or whatever.
</Para>
</Para>
<Para>
-Compile via C, and don't use the native-code generator. (There are
-many cases when GHC does this on its own.) You might pick up a little
-bit of speed by compiling via C. If you use <Function>_ccall_gc_</Function>s or
-<Function>_casm_</Function>s, you probably <Emphasis>have</Emphasis> to use <Option>-fvia-C</Option>.
+Compile via C, and don't use the native-code generator. (There are many
+cases when GHC does this on its own.) You might pick up a little bit of
+speed by compiling via C (e.g. for floating-point intensive code on Intel).
+If you use <Function>_casm_</Function>s (which are utterly
+deprecated), you probably <Emphasis>have</Emphasis> to use
+<Option>-fvia-C</Option>.
</Para>
<Para>
</Para>
<Para>
-If you are compiling with lots of <Literal>ccalls</Literal>, etc., you may need to
+If you are compiling with lots of foreign calls, you may need to
tell the C compiler about some <Literal>#include</Literal> files. There is no real
pretty way to do this, but you can use this hack from the
command-line:
projects / ghc-hetmet.git / commitdiff