[[project @ 2000-06-08 14:36:13 by rrt]
rrt**20000608143613
Added new FFI story from fptools/docs, and removed ccall docs.
Pls mrg
] {
addfile ./ghc/docs/users_guide/ffi-chap.sgml
hunk ./ghc/docs/users_guide/ffi-chap.sgml 1
+
+
+
+Foreign interface
+&ffi-body;
+
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 88
-Calling out to C:
+Foreign calling:
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 92
-can dangle around your neck. Please see .
+can dangle around your neck. Please see .
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 1479
-
-
-Calling C directly from Haskell
-
-
-C calls (Glasgow extension)
-_ccall_ (Glasgow extension)
-_casm_ (Glasgow extension)
-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.
-
-
-
-<Function>_ccall_</Function> and <Function>_casm_</Function>: an introduction
-
-
-
-The simplest way to use a simple C function
-
-
-
-
-
-double fooC( FILE *in, char c, int i, double d, unsigned int u )
-
-
-
-
-
-is to provide a Haskell wrapper:
-
-
-
-
-
-fooH :: Char -> Int -> Double -> Word -> IO Double
-fooH c i d w = _ccall_ fooC (“stdin”::Addr) c i d w
-
-
-
-
-
-The function fooH unbox all of its arguments, call the C
-function fooC and box the corresponding arguments.
-
-
-
-One of the annoyances about _ccall_s is when the C types don't quite
-match the Haskell compiler's ideas. For this, the _casm_ variant
-may be just the ticket (NB: no chance of such code going
-through a native-code generator):
-
-
-
-
-
-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)
- )
-
-
-
-
-
-The first literal-literal argument to a _casm_ is like a printf
-format: %r is replaced with the “result,” %0–%n-1 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 _ccall_ goes
-for _casm_ as well.
-
-
-
-The use of _casm_ 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 _casm_, its unfolding will not 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 _casm_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 _casm_, 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 _casm_ 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.
-
+
+The foreign interface
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 1483
-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
- will turn off the default behaviour.
--funfold-casms-in-hi-file option
+The foreign interface consists of language and library support. The former
+is described later in ; the latter is outlined below,
+and detailed in the hslibs documentation.
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 1488
-
-
-
-Literal-literals
-
-
-Literal-literals
-The literal-literal argument to _casm_ can be made use of separately
-from the _casm_ construct itself. Indeed, we've already used it:
-
-
-
-
-
-fooH :: Char -> Int -> Double -> Word -> IO Double
-fooH c i d w = _ccall_ fooC (“stdin”::Addr) c i d w
-
-
-
-
-
-The first argument that's passed to fooC is given as a literal-literal,
-that is, a literal chunk of C code that will be inserted into the generated
-.hc code at the right place.
-
-
-
-A literal-literal is restricted to having a type that's an instance of
-the CCallable class, see
-for more information.
-
-
-
-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.
-
-
-
-
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 2206
-This section documents GHC's implementation of multi-paramter type
+This section documents GHC's implementation of multi-parameter type
hunk ./ghc/docs/users_guide/gone_wrong.sgml 223
-If your program has no _ccall_s/_casm_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 .hi-boot files, in which
-case these must 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 .hi-boot files, in which case
+these must be correct with respect to the module
+source).
hunk ./ghc/docs/users_guide/gone_wrong.sgml 274
-Of course, if you have _ccall_s/_casm_s in your program then all
+Of course, if you have foreign calls in your program then all
hunk ./ghc/docs/users_guide/sooner.sgml 459
-Use _ccall_s (a GHC extension) to plug into fast libraries:
+Use foreign import (a GHC extension) to plug into fast libraries:
hunk ./ghc/docs/users_guide/sooner.sgml 468
- says a little about how to use C calls.
+ describes the foreign calling interface.
hunk ./ghc/docs/users_guide/ug-book.sgml 16
+&ffi-chap
hunk ./ghc/docs/users_guide/ug-ent.sgml 17
+
+
hunk ./ghc/docs/users_guide/using.sgml 1573
-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 _ccall_gc_s or
-_casm_s, you probably have to use .
+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 _casm_s (which are utterly
+deprecated), you probably have to use
+.
hunk ./ghc/docs/users_guide/using.sgml 2073
-If you are compiling with lots of ccalls, etc., you may need to
+If you are compiling with lots of foreign calls, you may need to
}