Skip to content
GitLab
Menu
Projects
Groups
Snippets
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Sign in / Register
Toggle navigation
Menu
Open sidebar
Glasgow Haskell Compiler
GHC
Commits
90e1b1bc
Commit
90e1b1bc
authored
Jun 08, 2000
by
rrt
Browse files
[project @ 2000-06-08 14:36:13 by rrt]
Added new FFI story from fptools/docs, and removed ccall docs. Pls mrg
parent
c7979ff1
Changes
7
Hide whitespace changes
Inline
Side-by-side
ghc/docs/users_guide/ffi-chap.sgml
0 → 100644
View file @
90e1b1bc
<!-- FFI docs as a chapter -->
<Chapter id="ffi">
<Title>Foreign interface</Title>
&ffi-body;
</Chapter>
ghc/docs/users_guide/glasgow_exts.sgml
View file @
90e1b1bc
...
...
@@ -85,11 +85,11 @@ Instead of being a boolean expression, a guard is a list of qualifiers, exactly
</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>
...
...
@@ -1476,152 +1476,15 @@ qualifier list has just one element, a boolean expression.
</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>
...
...
@@ -2340,7 +2203,7 @@ stuff is hairy with a capital H!
</Title>
<Para>
This section documents GHC's implementation of multi-paramter type
This section documents GHC's implementation of multi-param
e
ter 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
...
...
ghc/docs/users_guide/gone_wrong.sgml
View file @
90e1b1bc
...
...
@@ -220,11 +220,12 @@ please see <XRef LinkEnd="sooner-faster-quicker">).
</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>
...
...
@@ -270,7 +271,7 @@ So, before you report a bug because of a core dump, you should probably:
</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 call
s in your program then all
bets are off, because you can trash the heap, the stack, or whatever.
</Para>
...
...
ghc/docs/users_guide/sooner.sgml
View file @
90e1b1bc
...
...
@@ -456,7 +456,7 @@ types.
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>Use <
Function>_ccall_s</Function
> (a GHC extension) to plug into fast libraries:</Term>
<Term>Use <
Literal>foreign import</Literal
> (a GHC extension) to plug into fast libraries:</Term>
<ListItem>
<Para>
This may take real work, but… There exist piles of
...
...
@@ -465,7 +465,7 @@ to compete with it, but link with it.
</Para>
<Para>
<XRef LinkEnd="
glasgow-ccalls"> says a little about how to use C calls
.
<XRef LinkEnd="
sec-ffi"> describes the foreign calling interface
.
</Para>
</ListItem>
</VarListEntry>
...
...
ghc/docs/users_guide/ug-book.sgml
View file @
90e1b1bc
...
...
@@ -13,6 +13,7 @@
&prof
&sooner
&lang-features
&ffi-chap
&wrong
&utils
&win32-dll
ghc/docs/users_guide/ug-ent.sgml
View file @
90e1b1bc
...
...
@@ -14,3 +14,5 @@
<!ENTITY wrong SYSTEM "gone_wrong.sgml" >
<!ENTITY utils SYSTEM "utils.sgml" >
<!ENTITY win32-dll SYSTEM "win32-dlls.sgml">
<!ENTITY ffi-body SYSTEM "../../../docs/ffi.sgml">
<!ENTITY ffi-chap SYSTEM "ffi-chap.sgml">
ghc/docs/users_guide/using.sgml
View file @
90e1b1bc
...
...
@@ -1570,10 +1570,12 @@ Here are some “dangerous” optimisations you <Emphasis>might</Emphasi
</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>
...
...
@@ -2068,7 +2070,7 @@ THIS MAY CHANGE. Meanwhile, options so sent are:
</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:
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment