Skip to content
GitLab
Projects
Groups
Snippets
Help
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Sign in / Register
Toggle navigation
GHC
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Locked Files
Issues
4,321
Issues
4,321
List
Boards
Labels
Service Desk
Milestones
Iterations
Merge Requests
362
Merge Requests
362
Requirements
Requirements
List
CI / CD
CI / CD
Pipelines
Jobs
Schedules
Security & Compliance
Security & Compliance
Dependency List
License Compliance
Operations
Operations
Incidents
Environments
Analytics
Analytics
CI / CD
Code Review
Insights
Issue
Repository
Value Stream
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Jobs
Commits
Issue Boards
Open sidebar
Glasgow Haskell Compiler
GHC
Commits
90e1b1bc
Commit
90e1b1bc
authored
Jun 08, 2000
by
rrt
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
[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
Showing
7 changed files
with
33 additions
and
158 deletions
+33
-158
ghc/docs/users_guide/ffi-chap.sgml
ghc/docs/users_guide/ffi-chap.sgml
+6
-0
ghc/docs/users_guide/glasgow_exts.sgml
ghc/docs/users_guide/glasgow_exts.sgml
+8
-145
ghc/docs/users_guide/gone_wrong.sgml
ghc/docs/users_guide/gone_wrong.sgml
+7
-6
ghc/docs/users_guide/sooner.sgml
ghc/docs/users_guide/sooner.sgml
+2
-2
ghc/docs/users_guide/ug-book.sgml
ghc/docs/users_guide/ug-book.sgml
+1
-0
ghc/docs/users_guide/ug-ent.sgml
ghc/docs/users_guide/ug-ent.sgml
+2
-0
ghc/docs/users_guide/using.sgml
ghc/docs/users_guide/using.sgml
+7
-5
No files found.
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