typo: varibale -> variable
[haskell-report.git] / report / ffi.verb
1 % The Haskell 98 Foreign Function Interface
2 % [An Addendum to the Definition of Haskell 98]
3 %
4 % Editor: Manuel M T Chakravarty
5 %
6 % Copyright [2002..2003] Manuel M T Chakravarty
7 %
8 % The authors intend this Report to belong to the entire Haskell community, and
9 % so we grant permission to copy and distribute it for any purpose, provided
10 % that it is reproduced in its entirety, including this Notice.  Modified
11 % versions of this Report may also be copied and distributed for any purpose,
12 % provided that the modified version is clearly presented as such, and that it
13 % does not claim to be a definition of the Haskell 98 Foreign Function
14 % Interface. 
15
16 % Changes since RC15:
17 % * 6.3: Footnote regarding __STDC_ISO_10646__ added to text introducing
18 %        `CWString'.
19 %
20 % Changes since RC14:
21 % * 6.2: CWChar -> CWchar
22 % * 6.3: - CWChar -> CWchar
23 %        - Stated explicitly that memory allocated by `newCString' and friends
24 %          can be deallocated by `Foreign.Marshal.Alloc.free'
25 %        - Improved documentation
26 %
27 % Changes since RC13:
28 % * 5.3: Fixed typo
29 % * 5.7: Fixed a mistake in the type of `peekByteOff' and `pokeByteOff' (the
30 %        type variable constrained by `Storable' must be different from the
31 %        parameter of the `Ptr')
32 % * 6.3: Improved documentation
33 %
34 % Changes since RC12:
35 % * Acks : Added John Meacham
36 % * 4.1.5: Bug fix courtesy of Wolfgang Thaller
37 % * 5.5  : Added `FinalizerEnvPtr', `newForeignPtrEnv', and
38 %          `addForeignPtrFinalizerEnv'
39 % * 6.3  : Added John Meacham proposal for `wchar_t' support as well localised
40 %          string marshalling; in particular, this adds `CWString' and
41 %          `CWStringLen' as well as the `CWString' and the `CAString' family
42 %          of marshalling routines.  In addition, `charIsRepresentable' was
43 %          added. 
44 %
45 % Changes since RC11:
46 % * 5.5: Swapped argument order of `newForeignPtr' and `addForeignPtrFinalizer'
47 %
48 % Changes since RC10:
49 % * 3.3  : Clarified use of foreign functions of pure type
50 % * 4.1.1: Clarified the meaning of foreign imports without a "&" that have a
51 %          non-functional type in Haskell
52 % * 5.1  : Clarified the scope of safe use of unsafePerformIO
53 % * 5.5  : "pre-emptive" dropped in footnote regarding finalizers; added
54 %          `newForeignPointer_' and renamed `foreignPtrToPtr' to
55 %          `unsafeForeignPtrToPtr'
56 % * Typos throughout
57 %
58 % Changes since RC9:
59 % * 1:     Mentioning interaction with foreign threads as an open problem.
60 % * 2 & 3: Removed `threadsafe' again, as the proposal for thread support is
61 %          still evolving and it is not yet clear whether a new safety level
62 %          is required.
63 % * 5.5:   Added the type synonym `FinalizerPtr' and rewrote the documentation
64 %          of finalizers.
65 % * 5.6:   Clarified the description of `StablePtr'
66 % * 5.8:   Added `finalizerFree'
67 % * 6.2:   All the types in CTypes must be newtypes that are exported
68 %          abstractly. 
69 %
70 % Changes since RC8:
71 % * 5.8: `MarshallAlloc.reallocBytes' is no longer permitted on memory
72 %        allocated with `alloca' or `allocaBytes'. 
73 % * 6.1: Deinitialisation of the RTS via `hs_exit()' followed by
74 %        (re)initialisation with `hs_init()' must be supported.
75 %
76 % Changes since RC7:
77 % * Clarified the lexis of C identifiers and C header file names
78 % * In `ForeignPtr', added `mallocForeignPtrArray' and `mallocForeignPtrArray0'
79 % * Clarified spec of allocations functions adding constraints taken from the
80 %   corresponding C routines
81 % * `mallocBytes' and `allocaBytes' must align memory sufficiently for any
82 %   basic foreign type that fits into the allocated block
83 % * Removed typos in the description of the module `ForeignPtr'
84 % * Added Peter Gammie to the list of acknowledged people
85 % * `addForeignPtrFinalizer' guarantees that finalizers for a single foreign
86 %   pointer are executed in the opposite order as they were added.
87 % * `Storable': Require that the size is divisible by the alignment
88 % * Added Ross Paterson to the list of acknowledged people
89 % * Added hs_free_fun_ptr() and hs_free_stable_ptr()
90 % * Changed order of arguments of `mkIOError' and `annotateIOError' to match
91 %   with the current implementation in GHC's FFI libraries.
92 %
93 % Changes since RC6:
94 % * Fixed typos
95 %
96 % Changes since RC5:
97 % * Author list: changed Alastair Reid's institution
98 % * 1.4:   Clarified the wording
99 % * 4.1:   Explicitly stated that access to pre-processor symbols is not
100 %          provided by the FFI
101 % * 4.1.1: Removed [lib] from impent syntax and discussion
102 % * 4.1.3: Added parentheses round FunPtr ft to make it easier to 
103 %          understand a tolerably complex type.
104 % * 4.1.4: Removed all mention of library objects; clarified that header files
105 %          do not impact the semantics of foreign calls, but may be required
106 %          for correct code generation by some systems
107 % * 5.2:   Clarified that all operations in Bits are member functions of the
108 %          type class.  Reverse the meaning of the sign of the second argument
109 %          for `rotate' and `shift' (this makes it the same as GHC used all
110 %          the time).  `bitSize' on `Integer' etc is now undefined.
111 % * 5.5:   Finalisers must be external functions to facilitate the
112 %          implementation on Haskell systems that do not support pre-emptive
113 %          concurrency.
114 %          Added mallocForeignPtr and mallocForeignPtrBytes.
115 % * 6:     Specified that HsBool==int in table2
116 %          Relabelled column 1 in table 3 (C symbol -> CPP symbol)
117 %          Replaced 0 and 1 with HS_BOOL_FALSE/TRUE
118 % * 6.1:   Clarified that nullPtr (nullFunPtr) coincides with (HsPtr) NULL and
119 %          (HsFunPtr) NULL, respectively.
120 %          Allowing multiple calls to hs_init() and clarified the constraints
121 %          on the relative timing between hs_set_argv() and
122 %          getProgName/getArgs. 
123 %          Added hs_perform_gc().
124 %
125 % Changes since RC4:
126 % * 5.6: Clarified documentation of `StablePtr's (RC 5)
127 %
128 % Changes between RC2 and RC4:
129 %
130 % * 5.8: Clarified documentation for `MarshalAlloc.free'.
131 % * 5.8: Added `MarshalAlloc.realloc'.
132 % * 3: Added the new safety level `threadsafe' with an explanation at the end
133 %   of 3.3.
134 % * 3: Replaced the nontermional `entity' by `impent' and `expent' to
135 %   distinguish between import and export entities (as they are defined
136 %   differently in later sections).
137 % * 3.2: Clarified the description of foreign types; so far, `IO ()' was
138 %   strictly speaking not included as a valid return type.  Currently,
139 %   functions of type `a -> ()' are included.  Do we want this?  Their use
140 %   might not be portable if they include side effects.
141 % * 4.1.5: New section discussing the traps & pitfalls of type promotion with
142 %   C bindings.
143
144 % TODO:
145 % * Implement HTMLization.  (Malcolm suggests using
146 %   <http://pauillac.inria.fr/~maranget/hevea/>)
147
148 % TODO after Version 1.0:
149 %
150 % * Review suggestions by Antony Courtney <antony@@apocalypse.org> re FFI
151 %   support for Java.
152
153 \section{Foreign Function Interface}
154 \label{ffi}
155
156 % Old FFI addendum text:
157 % The definition of Haskell 98~\cite{haskell98}, while being comprehensive with
158 % respect to the functional core language, does lack a range of features of more
159 % operational flavour, such as a foreign language interface, concurrency
160 % support, and fully fledged exception handling.  As these features are of
161 % central importance to many real world applications of the language, there is a
162 % danger that different implementations become de facto incompatible for such
163 % applications due to system-specific extensions of the core language.  The
164 % present FFI specification is aimed at reducing this risk by defining a simple,
165 % yet comprehensive extension to Haskell 98 for the purpose of interfacing to
166 % program components implemented in a language other than Haskell.
167
168 The Foreign Function Interface (FFI) has two purposes: it enables (1) to
169 describe in Haskell the interface to foreign language functionality and
170 (2) to use from foreign code Haskell routines.  More generally, its aim
171 is to support the implementation of programs in a mixture of Haskell and
172 other languages such that the source code is portable across different
173 implementations of Haskell and non-Haskell systems as well as
174 independent of the architecture and operating system.
175
176 % Old FFI addendum text:
177 % The design as presented in this report builds on experiences with a number of
178 % foreign function interfaces that, over time, have been provided by the major
179 % Haskell implementations.  Central in the final design was the goal to be
180 % comprehensive while being simple and minimising changes with respect to
181 % Haskell 98; the latter includes to avoid pollution of the name space with new
182 % keywords.  Consequently, as much as possible of the FFI functionality is
183 % realised in the form of libraries.  Simplicity generally overruled maximum
184 % convenience for the programmer as a design goal.  Thus, support for more
185 % convenient interface specifications is the domain of system-independent tools
186 % that generate code following the present specification.
187
188 \subsection{Foreign Languages}
189
190 The Haskell FFI currently only specifies the interaction between Haskell
191 code and foreign code that follows the C calling convention.  However,
192 the design of the FFI is such that it enables the modular extension of
193 the present definition to include the calling conventions of other
194 programming languages, such as C++ and Java.  A precise definition of
195 the support for those languages is expected to be included in later
196 versions of the language.  The second major omission is the definition
197 of the interaction with multithreading in the foreign language and, in
198 particular, the treatment of thread-local state, and so these details
199 are currently implementation-defined.
200
201 The core of the present specification is independent of the foreign language
202 that is used in conjunction with Haskell.  However, there are two areas where
203 FFI specifications must become language specific: (1) the specification of
204 external names and (2) the marshalling of the basic types of a foreign
205 language.  As an example of the former, consider that in C~\cite{C} a simple
206 identifier is sufficient to identify an object, while
207 Java~\cite{gosling-etal:Java}, in general, requires a qualified name in
208 conjunction with argument and result types to resolve possible overloading.
209 Regarding the second point, consider that many languages do not specify the
210 exact representation of some basic types.  For example the type @int@ in
211 C may be 16, 32, or 64 bits wide.  Similarly, Haskell guarantees
212 only that @Int@ covers at least the range \([-2^{29}, 2^{29} - 1]\) (Section~\ref{numbers}).  As
213 a consequence, to reliably represent values of C's @int@ in Haskell, we
214 have to introduce a new type @CInt@, which is guaranteed to match the
215 representation of @int@.
216
217 The specification of external names, dependent on a calling convention, is
218 described in Section~\ref{sec:extent}, whereas the marshalling of the basic
219 types in dependence on a foreign language is described in
220 Section~\ref{sec:marshalling}.
221
222 \subsection{Contexts}
223
224 For a given Haskell system, we define the \emph{Haskell context} to be the
225 execution context of the abstract machine on which the Haskell system is
226 based.  This includes the heap, stacks, and the registers of the abstract
227 machine and their mapping onto a concrete architecture.  We call any other
228 execution context an \emph{external context.}  Generally, we cannot assume any
229 compatibility between the data formats and calling conventions between the
230 Haskell context and a given external context, except where Haskell explicitly prescribes a specific data format.
231
232 The principal goal of a foreign function interface is to provide a
233 programmable interface between the Haskell context and external
234 contexts.  As a result Haskell threads can access data in external
235 contexts and invoke functions that are executed in an external context
236 as well as vice versa.  In the rest of this definition, external
237 contexts are usually identified by a calling convention.
238
239 \subsubsection{Cross Language Type Consistency}
240
241 Given that many external languages support static types, the question arises
242 whether the consistency of Haskell types with the types of the external
243 language can be enforced for foreign functions.  Unfortunately, this is, in
244 general, not possible without a significant investment on the part of the
245 implementor of the Haskell system (i.e., without implementing a dedicated type
246 checker).  For example, in the case of the C calling convention, the only
247 other approach would be to generate a C prototype from the Haskell type and
248 leave it to the C compiler to match this prototype with the prototype that is
249 specified in a C header file for the imported function.  However, the Haskell
250 type is lacking some information that would be required to pursue this route.
251 In particular, the Haskell type does not contain any information as to when
252 @const@ modifiers have to be emitted.  
253
254 As a consequence, this definition does not require the Haskell system to check
255 consistency with foreign types.  Nevertheless, Haskell systems are encouraged
256 to provide any cross language consistency checks that can be implemented with
257 reasonable effort.
258
259 \subsection{Lexical Structure}
260
261 The FFI reserves a single keyword @foreign@, and a set of special
262 identifiers.  The latter have a special meaning only within foreign
263 declarations, but may be used as ordinary identifiers elsewhere.
264
265 The special identifiers @ccall@, @cplusplus@, @dotnet@,
266 @jvm@, and @stdcall@ are defined to denote calling conventions.
267 However, a concrete implementation of the FFI is free to support additional,
268 system-specific calling conventions whose name is not explicitly listed here.
269
270 To refer to objects of an external C context, we introduce the following
271 phrases:
272 %
273 @@@
274 chname -> \{chchar\} @.@ @h@               & (\tr{C header filename})
275 cid    -> letter \{letter | ascDigit\}     & (\tr{C identifier})
276 chchar -> letter | ascSymbol_{\langle{}@&@\rangle{}}
277 letter -> ascSmall | ascLarge | @_@
278 @@@
279 %
280 The range of lexemes that are admissible for "chname" is a subset of
281 those permitted as arguments to the @#include@ directive in C.  In
282 particular, a file name "chname" must end in the suffix @.h@.  The
283 lexemes produced by "cid" coincide with those allowed as C identifiers,
284 as specified in~\cite{C}.
285
286 \subsection{Foreign Declarations}
287
288 The syntax of foreign declarations is as follows:
289 %
290 @@@
291 topdecl  -> @foreign@ fdecl
292 fdecl    -> @import@ callconv [safety] impent var @::@ ftype & (\tr{define variable})
293          |  @export@ callconv expent var @::@ ftype & (\tr{expose variable})
294 callconv -> @ccall@ | @stdcall@ | @cplusplus@  & (\tr{calling convention})
295          | @jvm@ | @dotnet@
296          |  \mbox{\bf system-specific calling conventions}
297 impent   -> [string]
298 expent   -> [string]
299 safety   -> @unsafe@ | @safe@
300 @@@
301 %
302 There are two flavours of foreign declarations: import and export
303 declarations.  An import declaration makes an \emph{external entity,} i.e., a
304 function or memory location defined in an external context, available in the
305 Haskell context.  Conversely, an export declaration defines a function of the
306 Haskell context as an external entity in an external context.  Consequently,
307 the two types of declarations differ in that an import declaration defines a
308 new variable, whereas an export declaration uses a variable that is already
309 defined in the Haskell module.
310
311 The external context that contains the external entity is determined by the
312 calling convention given in the foreign declaration.  Consequently, the exact
313 form of the specification of the external entity is dependent on both the
314 calling convention and on whether it appears in an import declaration (as
315 "impent") or in an export declaration (as "expent").  To provide
316 syntactic uniformity in the presence of different calling conventions, it is
317 guaranteed that the description of an external entity lexically appears as a
318 Haskell string lexeme.  The only exception is where this string would be the
319 empty string (i.e., be of the form @""@); in this case, the string may be
320 omitted in its entirety.
321
322 \subsubsection{Calling Conventions}
323 \label{sec:call-conv}
324
325 The binary interface to an external entity on a given architecture is
326 determined by a calling convention.  It often depends on the programming
327 language in which the external entity is implemented, but usually is more
328 dependent on the system for which the external entity has been compiled.
329
330 As an example of how the calling convention is dominated by the system rather
331 than the programming language, consider that an entity compiled to byte code
332 for the Java Virtual Machine (JVM)~\cite{lindholm-etal:JVM} needs to be
333 invoked by the rules of the JVM rather than that of the source language in
334 which it is implemented (the entity might be implemented in Oberon, for
335 example).
336
337 Any implementation of the Haskell FFI must at least implement the C calling
338 convention denoted by @ccall@.  All other calling conventions are
339 optional.  Generally, the set of calling conventions is open, i.e., individual
340 implementations may elect to support additional calling conventions.  In
341 addition to @ccall@, Table~\ref{tab:callconv} specifies a range of
342 identifiers for common calling conventions.
343 %
344 \begin{table}[tbp]
345   \begin{center}
346     \begin{tabular}{|l|l|}
347       \hline
348       Identifier & Represented calling convention\\
349       \hline\hline
350       @ccall@ 
351       & Calling convention of the standard C compiler on a system\\
352       @cplusplus@
353       & Calling convention of the standard C{+}{+} compiler on a system\\
354       @dotnet@
355       & Calling convention of the \textsc{.net} platform\\
356       @jvm@ 
357       & Calling convention of the Java Virtual Machine\\
358       @stdcall@
359       & Calling convention of the Win32 API (matches Pascal conventions)\\
360       \hline
361     \end{tabular}
362     \caption{Calling conventions}
363     \label{tab:callconv}
364   \end{center}
365 \end{table}
366 %
367 Implementations need not implement all of these conventions, but if any is
368 implemented, it must use the listed name.  For any other calling convention,
369 implementations are free to choose a suitable name.
370
371 Only the semantics of the calling conventions @ccall@ and @stdcall@ are
372 defined herein; more calling conventions may be added in future versions
373 of Haskell.
374
375 It should be noted that the code generated by a Haskell system to implement a
376 particular calling convention may vary widely with the target code of that
377 system.  For example, the calling convention @jvm@ will be trivial to
378 implement for a Haskell compiler generating Java code, whereas for a Haskell
379 compiler generating C code, the Java Native Interface (JNI)~\cite{liang:JNI}
380 has to be targeted.
381
382 \subsubsection{Foreign Types}
383 \label{sec:foreign-types}
384
385 The following types constitute the set of \emph{basic foreign types}:
386 %
387 \begin{itemize}
388 \item @Char@, @Int@, @Double@, @Float@, and @Bool@ as
389   exported by the Haskell @Prelude@ as well as
390 \item @Int8@, @Int16@, @Int32@, @Int64@, @Word8@,
391   @Word16@, @Word32@, @Word64@, @Ptr a@, @FunPtr a@,
392   and @StablePtr a@, for any type @a@, as exported by @Foreign@
393   (Section~\ref{module:Foreign}).
394 \end{itemize}
395 %
396 A Haskell system that implements the FFI needs to be able to pass these types
397 between the Haskell and the external context as function arguments and
398 results.
399
400 Foreign types are produced according to the following grammar:
401 %
402 @@@
403 ftype -> frtype
404       |  fatype \rightarrow ftype
405 frtype -> fatype
406        | @()@
407 fatype -> qtycon atype_1 \ldots atype_k & (k \geq 0)
408 @@@
409 %
410 A foreign type is the Haskell type of an external entity.  Only a subset of
411 Haskell's types are permissible as foreign types, as only a restricted set of
412 types can be canonically transferred between the Haskell context and an
413 external context.  A foreign type has the form
414 \[
415 \textit{at}_1@ -> @\cdots@ -> @\textit{at}_n@ -> @\textit{rt}
416 \]
417 where \(n\geq0\).  It implies that the arity of the external entity is $n$.
418
419 External functions are strict in all arguments.
420
421 \paragraph{Marshallable foreign types.}
422
423 The argument types \(\textit{at}_i\) produced by "fatype" must be
424 \emph{marshallable foreign types;} that is, either
425
426 \begin{itemize}
427 \item a basic foreign type,
428
429 \item a type synonym of a marshallable foreign type,
430
431 \item a type "T t'_1 ... t'_n" where "T" is defined by a @newtype@ declaration
432
433 \begin{quote}
434 @newtype @"T a_1 ... a_n"@ = @"N t"
435 \end{quote}
436
437 and
438
439 \begin{itemize}
440 \item the constructor "N" is visible where "T" is used,
441
442 \item "t[t'_1/a_1..t'_n/a_n]" is a marshallable foreign type
443 \end{itemize}
444 \end{itemize}
445
446 Consequently, in order for a type defined by @newtype@ to be used in a
447 @foreign@ declaration outside of the module that defines it, the type
448 must not be exported abstractliy.  The module @Foreign.C.Types@ that
449 defines the Haskell equivalents for C types follows this convention;
450 see Chapter~\ref{module:Foreign.C.Types}.
451
452 \paragraph{Marshallable foreign result types.}
453
454 The result type \textit{rt} produced by "frtype" must be a
455 \emph{marshallable foreign result type;} that is, either
456
457 \begin{itemize}
458 \item a marshallable foreign type,
459 \item the type @()@,
460 \item a type matching @Prelude.IO @$t$, where $t$ is a marshallable foreign type or @()@,
461 \item a type "T t'_1 ... t'_n" where "T" is defined by a @newtype@ declaration
462
463 \begin{quote}
464 @newtype @"T a_1 ... a_n"@ = @"N t"
465 \end{quote}
466
467 and
468
469 \begin{itemize}
470 \item the constructor "N" is visible where "T" is used,
471
472 \item "t[t'_1/a_1..t'_n/a_n]" is a marshallable foreign result type
473 \end{itemize}
474 \end{itemize}
475
476 \subsubsection{Import Declarations}
477 \label{sec:import}
478
479 Generally, an import declaration has the form
480 %
481 \[
482 @foreign@~@import@~c~e~v~@::@~t
483 \]
484 %
485 which declares the variable $v$ of type $t$ to be defined externally.
486 Moreover, it specifies that $v$ is evaluated by executing the external entity
487 identified by the string $e$ using calling convention $c$.  The precise form
488 of $e$ depends on the calling convention and is detailed in
489 Section~\ref{sec:extent}.  If a variable $v$ is defined by an import
490 declaration, no other top-level declaration for $v$ is allowed in the same
491 module.  For example, the declaration
492 \bprog
493 @
494 foreign import ccall "string.h strlen"
495    cstrlen :: Ptr CChar -> IO CSize
496 @
497 \eprog
498 introduces the function @cstrlen@, which invokes the external function
499 @strlen@ using the standard C calling convention.  Some external entities
500 can be imported as pure functions; for example,
501 \bprog
502 @
503 foreign import ccall "math.h sin"
504    sin :: CDouble -> CDouble.
505 @
506 \eprog
507 %
508 Such a declaration asserts that the external entity is a true function; i.e.,
509 when applied to the same argument values, it always produces the same result.
510
511 Whether a particular form of external entity places a constraint on the
512 Haskell type with which it can be imported is defined in
513 Section~\ref{sec:extent}.  Although, some forms of external entities restrict
514 the set of Haskell types that are permissible, the system can generally not
515 guarantee the consistency between the Haskell type given in an import
516 declaration and the argument and result types of the external entity.  It is
517 the responsibility of the programmer to ensure this consistency.
518
519 Optionally, an import declaration can specify, after the calling convention,
520 the safety level that should be used when invoking an external entity.  A
521 @safe@ call is less efficient, but guarantees to leave the Haskell system
522 in a state that allows callbacks from the external code.  In contrast, an
523 @unsafe@ call, while carrying less overhead, must not trigger a callback
524 into the Haskell system.  If it does, the system behaviour is undefined.  The
525 default for an invocation is to be @safe@.  Note that a callback into
526 the Haskell system implies that a garbage collection might be triggered after
527 an external entity was called, but before this call returns.  Consequently,
528 objects other than stable pointers (cf.\ Section~\ref{module:Foreign.StablePtr}) may be
529 moved or garbage collected by the storage manager.
530
531 \subsubsection{Export Declarations}
532
533 The general form of export declarations is
534 %
535 \[
536 @foreign@~@export@~c~e~v~@::@~t
537 \]
538 %
539 Such a declaration enables external access to $v$, which may be a value, field
540 name, or class method that is declared on the top-level of the same module or
541 imported.  Moreover, the Haskell system defines the external entity described
542 by the string $e$, which may be used by external code using the calling
543 convention $c$; an external invocation of the external entity $e$ is
544 translated into evaluation of $v$.  The type $t$ must be an instance of the
545 type of $v$.  For example, we may have
546 \bprog
547 @
548 foreign export ccall "addInt"   (+) :: Int   -> Int   -> Int
549 foreign export ccall "addFloat" (+) :: Float -> Float -> Float
550 @
551 \eprog
552 If an evaluation triggered by an external invocation of an exported Haskell
553 value returns with an exception, the system behaviour is undefined.  Thus,
554 Haskell exceptions have to be caught within Haskell and explicitly marshalled
555 to the foreign code.
556
557
558 \subsection{Specification of External Entities}
559 \label{sec:extent}
560
561 Each foreign declaration has to specify the external entity that is accessed
562 or provided by that declaration.  The syntax and semantics of the notation
563 that is required to uniquely determine an external entity depends heavily on
564 the calling convention by which this entity is accessed.  For example, for the
565 calling convention @ccall@, a global label is sufficient.  However, to
566 uniquely identify a method in the calling convention @jvm@, type
567 information has to be provided.  For the latter, there is a choice between the
568 Java source-level syntax of types and the syntax expected by JNI---but,
569 clearly, the syntax of the specification of an external entity depends on the
570 calling convention and may be non-trivial.
571
572 Consequently, the FFI does not fix a general syntax for denoting external
573 entities, but requires both "impent" and "expent" to take the
574 form of a Haskell "string" literal.  The formation rules for the values
575 of these strings depend on the calling convention and a Haskell system
576 implementing a particular calling convention will have to parse these strings
577 in accordance with the calling convention.
578
579 Defining "impent" and "expent" to take the form of a
580 "string" implies that all information that is needed to statically
581 analyse the Haskell program is separated from the information needed to
582 generate the code interacting with the foreign language.  This is, in
583 particular, helpful for tools processing Haskell source code.  When ignoring
584 the entity information provided by "impent" or "expent", foreign
585 import and export declarations are still sufficient to infer identifier
586 definition and use information as well as type information.
587
588 For more complex calling conventions, there is a choice between the user-level
589 syntax for identifying entities (e.g., Java or C{+}{+}) and the system-level
590 syntax (e.g., the type syntax of JNI or mangled C{+}{+}, respectively).  If
591 such a choice exists, the user-level syntax is preferred.  Not only because it
592 is more user friendly, but also because the system-level syntax may not be
593 entirely independent of the particular implementation of the foreign language.
594
595 The following defines the syntax for specifying external entities and their
596 semantics for the calling conventions @ccall@ and @stdcall@.  Other
597 calling conventions from Table~\ref{tab:callconv} are expected to be defined
598 in future versions of Haskell.
599
600
601 \subsubsection{Standard C Calls}
602 \label{sec:ccall}
603
604 The following defines the structure of external entities for foreign
605 declarations under the @ccall@ calling convention for both import and
606 export declarations separately.  Afterwards additional constraints on the type
607 of foreign functions are defined.
608
609 The FFI covers only access to C functions and global variables.  There are no
610 mechanisms to access other entities of C programs.  In particular, there is no
611 support for accessing pre-processor symbols from Haskell, which includes
612 @#define@d constants.  Access from Haskell to such entities is the
613 domain of language-specific tools, which provide added convenience over the
614 plain FFI as defined here.
615
616 \paragraph{Import Declarations}
617
618 For import declarations, the syntax for the specification of external entities
619 under the @ccall@ calling convention is as follows:
620 @@@
621 impent -> @"@ [@static@] [chname] [@&@] [cid] @"@ & (\tr{static function or address})
622        | @"@ dynamic @"@ & (\tr{stub factory importing addresses})
623        | @"@ wrapper @"@ & (\tr{stub factory exporting thunks})
624 @@@
625 The first alternative either imports a static function "cid" or, if
626 @&@ precedes the identifier, a static address.  If "cid" is
627 omitted, it defaults to the name of the imported Haskell variable.  The
628 optional filename "chname" specifies a C header file, where the
629 intended meaning is that the header file declares the C entity identified by
630 "cid".  In particular, when the Haskell system compiles Haskell to C
631 code, the directive
632 %
633 \begin{quote}
634   @#include "@"chname"@"@
635 \end{quote}
636 %
637 needs to be placed into any generated C file that refers to the foreign entity
638 before the first occurrence of that entity in the generated C file.
639
640 The second and third alternative, identified by the keywords @dynamic@
641 and @wrapper@, respectively, import stub functions that have to be
642 generated by the Haskell system.  In the case of @dynamic@, the stub
643 converts C function pointers into Haskell functions; and conversely, in the
644 case of @wrapper@, the stub converts Haskell thunks to C function
645 pointers.  If neither of the specifiers @static@, @dynamic@, or
646 @wrapper@ is given, @static@ is assumed.  The specifier
647 @static@ is nevertheless needed to import C routines that are named
648 @dynamic@ or @wrapper@.
649
650 It should be noted that a static foreign declaration that does not import an
651 address (i.e., where @&@ is not used in the specification of the external
652 entity) always refers to a C function, even if the Haskell type is
653 non-functional.  For example, 
654 \bprog
655 @
656 foreign import ccall foo :: CInt
657 @
658 \eprog
659 refers to a pure C function @foo@ with no arguments that returns an
660 integer value.  Similarly, if the type is @IO CInt@, the declaration
661 refers to an impure nullary function.  If a Haskell program needs to access a
662 C variable @bar@ of integer type,
663 \bprog
664 @
665 foreign import ccall "&" bar :: Ptr CInt
666 @
667 \eprog
668 must be used to obtain a pointer referring to the variable.  The variable can
669 be read and updated using the routines provided by the module @Foreign.Storable@
670 (cf.\ Section~\ref{module:Foreign.Storable}).
671
672 \paragraph{Export Declarations}
673
674 External entities in "ccall" export declarations are of the form
675 %
676 @@@
677 expent -> @"@ [cid] @"@
678 @@@
679 %
680 The optional C identifier "cid" defines the external name by which the
681 exported Haskell variable is accessible in C.  If it is omitted, the external
682 name defaults to the name of the exported Haskell variable.
683
684 \paragraph{Constraints on Foreign Function Types}
685
686 In the case of import declaration, there are, depending on the kind of import
687 declaration, constraints regarding the admissible Haskell type that the
688 variable defined in the import may have.  These constraints are specified in
689 the following.
690 %
691 \begin{description}
692 \item[Static Functions.]  A static function can be of any foreign type; in
693   particular, the result type may or may not be in the IO monad.  If a
694   function that is not pure is not imported in the IO monad, the system
695   behaviour is undefined.  Generally, no check for consistency with the C type
696   of the imported label is performed.
697
698   As an example, consider
699   %
700 \bprog
701 @
702 foreign import ccall "static stdlib.h"
703    system :: Ptr CChar -> IO CInt
704 @
705 \eprog
706   %
707   This declaration imports the @system()@ function whose prototype is
708   available from @stdlib.h@.
709
710 \item[Static addresses.]  The type of an imported address is constrained to be
711   of the form @Ptr @\textit{a} or @FunPtr @\textit{a}, where
712   \textit{a} can be any type.
713
714   As an example, consider
715   %
716 \bprog
717 @
718 foreign import ccall "errno.h &errno" errno :: Ptr CInt
719 @
720 \eprog
721   %
722   It imports the address of the variable @errno@, which is of the C type
723   @int@.
724
725 \item[Dynamic import.]  The type of a "dynamic" stub has to be of the
726   form @(FunPtr @\textit{ft}@) -> @\textit{ft}, where \textit{ft} may
727   be any foreign type.
728
729   As an example, consider
730   %
731 \bprog
732 @
733 foreign import ccall "dynamic" 
734   mkFun :: FunPtr (CInt -> IO ()) -> (CInt -> IO ())
735 @
736 \eprog
737   %
738   The stub factory @mkFun@ converts any pointer to a C function that gets
739   an integer value as its only argument and does not have a return value into
740   a corresponding Haskell function.
741
742 \item[Dynamic wrapper.]  The type of a "wrapper" stub has to be of the
743   form \textit{ft}@ -> IO (FunPtr @\textit{ft}), where
744   \textit{ft} may be any foreign type.
745
746   As an example, consider
747   %
748 \bprog
749 @
750 foreign import ccall "wrapper" 
751   mkCallback :: IO () -> IO (FunPtr (IO ()))
752 @
753 \eprog
754   %
755   The stub factory @mkCallback@ turns any Haskell computation of type
756   @IO ()@ into a C function pointer that can be passed to C routines,
757   which can call back into the Haskell context by invoking the referenced
758   function.
759
760 \end{description}
761
762 \paragraph{Specification of Header Files}
763
764 A C header specified in an import declaration is always included by
765 @#include "@"chname"@"@.  There is no explicit support for
766 @#include <@"chname"@>@ style inclusion.  The ISO C99~\cite{C99}
767 standard guarantees that any search path that would be used for a
768 @#include <@"chname"@>@ is also used for @#include "@"chname"@"@ and it is guaranteed that these paths are searched after
769 all paths that are unique to @#include "@"chname"@"@.  Furthermore,
770 we require that "chname" ends on @.h@ to make parsing of the
771 specification of external entities unambiguous.
772   
773 The specification of include files has been kept to a minimum on purpose.
774 Libraries often require a multitude of include directives, some of which may
775 be system-dependent.  Any design that attempts to cover all possible
776 configurations would introduce significant complexity.  Moreover, in the
777 current design, a custom include file can be specified that uses the standard
778 C preprocessor features to include all relevant headers.
779
780 Header files have no impact on the semantics of a foreign call, and whether an
781 implementation uses the header file or not is implementation-defined.
782 However, as some implementations may require a header file that supplies a
783 correct prototype for external functions in order to generate correct code,
784 portable FFI code must include suitable header files.
785
786 \paragraph{C Argument Promotion}
787
788 The argument passing conventions of C are dependant on whether a function
789 prototype for the called functions is in scope at a call site.  In particular,
790 if no function prototype is in scope, \emph{default argument promotion} is
791 applied to integral and floating types.  In general, it cannot be expected
792 from a Haskell system that it is aware of whether a given C function was
793 compiled with or without a function prototype being in scope.  For the sake of
794 portability, we thus require that a Haskell system generally implements calls
795 to C functions as well as C stubs for Haskell functions as if a function
796 prototype for the called function is in scope.
797
798 This convention implies that the onus for ensuring the match between C and
799 Haskell code is placed on the FFI user.  In particular, when a C function that
800 was compiled without a prototype is called from Haskell, the Haskell signature
801 at the corresponding @foreign import@ declaration must use the types
802 \emph{after} argument promotion.  For example, consider the following C
803 function definition, which lacks a prototype:
804 %
805 \bprog
806 @
807 void foo (a)
808 float a;
809 {
810   ...
811 }
812 @
813 \eprog
814 %
815 The lack of a prototype implies that a C compiler will apply default argument
816 promotion to the parameter @a@, and thus, @foo@ will expect to
817 receive a value of type @double@, \emph{not} @float@.  Hence, the
818 correct @foreign import@ declaration is
819 %
820 \bprog
821 @
822 foreign import ccall foo :: Double -> IO ()
823 @
824 \eprog
825
826 In contrast, a C function compiled with the prototype
827 %
828 \bprog
829 @
830 void foo (float a);
831 @
832 \eprog
833 %
834 requires
835 %
836 \bprog
837 @
838 foreign import ccall foo :: Float -> IO ()
839 @
840 \eprog
841
842 A similar situation arises in the case of @foreign export@ declarations
843 that use types that would be altered under the C default argument promotion
844 rules.  When calling such Haskell functions from C, a function prototype
845 matching the signature provided in the @foreign export@ declaration must
846 be in scope; otherwise, the C compiler will erroneously apply the promotion
847 rules to all function arguments.
848
849 Note that for a C function defined to a accept a variable number of arguments,
850 all arguments beyond the explicitly typed arguments suffer argument promotion.
851 However, because C permits the calling convention to be different for such
852 functions; a Haskell system will, in general, not be able to make use of
853 variable argument functions.  Hence, their use is deprecated in portable code.
854
855
856 \subsubsection{Win32 API Calls}
857
858 The specification of external entities under the @stdcall@ calling
859 convention is identical to that for standard C calls.  The two calling
860 conventions only differ in the generated code.
861
862
863 % \begin{FUTURE} % ===== Material for future extension =======================
864
865 % \subsubsection{C{+}{+} Calls}
866
867 % The syntax for the specification of external entities under the
868 % @cplusplus@ calling convention is
869
870 % \subsubsection{JVM Calls}
871
872 % The syntax for the specification of external entities under the @jvm@
873 % calling convention is 
874 % %
875
876 %   \grule{impent}{%
877 %     ""jtype" "jqid"("jtypes")"}
878 %   \gor[constructor call]{%
879 %     "new "jqid"("jtypes")"}
880 %   \grule[$n\geq0$]{jtypes}{%
881 %     \gnterm[1]{jtype},\gellipse,\gnterm[n]{jtype}}
882
883 % %
884 % where "jqid" is a qualified Java identifier and "jtype" a Java
885 % types as defined in~\cite{gosling-etal:Java}.
886
887 % \begin{verbatim}
888 % FIXME: 
889 % - force the inclusion of the return type in case of "new"?
890 % \end{verbatim}
891
892 % \subsubsection{.NET Calls}
893
894 % The syntax for the specification of external entities under the @dotnet@
895 % calling convention is
896
897 % \end{FUTURE}% =============================================================
898
899
900 \subsection{Marshalling}
901 \label{sec:marshalling}
902
903 In addition to the language extension discussed in previous sections, the FFI
904 includes a set of standard libraries, which ease portable use of foreign
905 functions as well as marshalling of compound structures.  Generally, the
906 marshalling of Haskell structures into a foreign representation and vice versa
907 can be implemented in either Haskell or the foreign language.  At least where
908 the foreign language is at a significantly lower level, e.g.\ C, there are
909 good reasons for doing the marshalling in Haskell:
910 %
911 \begin{itemize}
912 \item Haskell's lazy evaluation strategy would require any foreign code that
913   attempts to access Haskell structures to force the evaluation of these
914   structures before accessing them. This would lead to complicated code in the
915   foreign language, but does not need any extra consideration when coding the
916   marshalling in Haskell.
917 \item Despite the fact that marshalling code in Haskell tends to look like C
918   in Haskell syntax, the strong type system still catches many errors that
919   would otherwise lead to difficult-to-debug runtime faults.
920 \item Direct access to Haskell heap structures from a language like
921   C---especially, when marshalling from C to Haskell, i.e., when Haskell
922   structures are created---carries the risk of corrupting the heap, which
923   usually leads to faults that are very hard to debug.
924 \end{itemize}
925 %
926 Consequently, the Haskell FFI emphasises Haskell-side marshalling.
927
928 The interface to the marshalling libraries is provided by the module
929 @Foreign@ (Chapter~\ref{module:Foreign}) plus a language-dependent module per supported language.  In
930 particular, the standard requires the availability of the module
931 @Foreign.C@ (Chapter~\ref{module:Foreign.C}), which simplifies portable interfacing with external C code.
932 Language-dependent modules, such as @Foreign.C@, generally provide Haskell
933 types representing the basic types of the foreign language using a
934 representation that is compatible with the foreign types as implemented by the
935 default implementation of the foreign language on the present architecture.
936 This is especially important for languages where the standard leaves some
937 aspects of the implementation of basic types open.  For example, in C, the
938 size of the various integral types is not fixed.  Thus, to represent C
939 interfaces faithfully in Haskell, for each integral type in C, we need to have
940 an integral type in Haskell that is guaranteed to have the same size as the
941 corresponding C type.
942
943 \subsection{The External C Interface}
944
945 \begin{table}
946   \begin{center}
947     \begin{tabular}{|l|l|l|}
948       \hline
949       C symbol          & Haskell symbol & Constraint on concrete C type\\
950       \hline\hline
951       @HsChar@     & @Char@    
952       & integral type\\
953       \hline
954       @HsInt@      & @Int@
955       & signed integral type, $\geq30$ bit\\
956       \hline
957       @HsInt8@     & @Int8@
958       & signed integral type, 8 bit; @int8_t@ if available\\
959       \hline
960       @HsInt16@    & @Int16@
961       & signed integral type, 16 bit; @int16_t@ if available\\
962       \hline
963       @HsInt32@    & @Int32@
964       & signed integral type, 32 bit; @int32_t@ if available\\
965       \hline
966       @HsInt64@    & @Int64@
967       & signed integral type, 64 bit; @int64_t@ if available\\ 
968       \hline
969       @HsWord8@    & @Word8@
970       & unsigned integral type, 8 bit; @uint8_t@ if available\\
971       \hline
972       @HsWord16@   & @Word16@
973       & unsigned integral type, 16 bit; @uint16_t@ if available\\
974       \hline
975       @HsWord32@   & @Word32@
976       & unsigned integral type, 32 bit; @uint32_t@ if available\\
977       \hline
978       @HsWord64@   & @Word64@
979       & unsigned integral type, 64 bit; @uint64_t@ if available\\
980       \hline
981       @HsFloat@    & @Float@
982       & floating point type\\
983      \hline
984       @HsDouble@   & @Double@
985       & floating point type\\
986      \hline
987       @HsBool@     & @Bool@
988       & @int@\\
989      \hline
990       @HsPtr@      & @Ptr a@
991       & @(void *)@\\
992      \hline
993       @HsFunPtr@   & @FunPtr a@
994       & @(void (*)(void))@\\
995      \hline
996       @HsStablePtr@& @StablePtr a@
997       & @(void *)@\\
998      \hline
999     \end{tabular}
1000     \caption{C Interface to Basic Haskell Types}
1001     \label{tab:c-haskell-types}
1002   \end{center}
1003 \end{table}
1004 %
1005 \begin{table}
1006   \begin{center}
1007 %    \begin{tabular}{|l|l|l|}
1008     \begin{tabular}{|l|l|p{30ex}|}
1009       \hline
1010       CPP symbol           & Haskell value & Description\\
1011       \hline\hline
1012       @HS_CHAR_MIN@ & @minBound :: Char@
1013       & \\
1014       \hline
1015       @HS_CHAR_MAX@ & @maxBound :: Char@
1016       & \\
1017       \hline
1018       @HS_INT_MIN@ & @minBound :: Int@
1019       & \\
1020       \hline
1021       @HS_INT_MAX@ & @maxBound :: Int@
1022       & \\
1023       \hline
1024       @HS_INT8_MIN@ & @minBound :: Int8@
1025       & \\
1026       \hline
1027       @HS_INT8_MAX@ & @maxBound :: Int8@
1028       & \\
1029       \hline
1030       @HS_INT16_MIN@ & @minBound :: Int16@
1031       & \\
1032       \hline
1033       @HS_INT16_MAX@ & @maxBound :: Int16@
1034       & \\
1035       \hline
1036       @HS_INT32_MIN@ & @minBound :: Int32@
1037       & \\
1038       \hline
1039       @HS_INT32_MAX@ & @maxBound :: Int32@
1040       & \\
1041       \hline
1042       @HS_INT64_MIN@ & @minBound :: Int64@
1043       & \\
1044       \hline
1045       @HS_INT64_MAX@ & @maxBound :: Int64@
1046       & \\
1047       \hline
1048       @HS_WORD8_MAX@ & @maxBound :: Word8@
1049       & \\
1050       \hline
1051       @HS_WORD16_MAX@ & @maxBound :: Word16@
1052       & \\
1053       \hline
1054       @HS_WORD32_MAX@ & @maxBound :: Word32@
1055       & \\
1056       \hline
1057       @HS_WORD64_MAX@ & @maxBound :: Word64@
1058       & \\
1059       \hline
1060       @HS_FLOAT_RADIX@ & @floatRadix :: Float@
1061       & \\
1062       \hline
1063       @HS_FLOAT_ROUND@ & n/a
1064       & rounding style as per~\cite{C99}\\
1065       \hline
1066       @HS_FLOAT_EPSILON@ & n/a
1067       & difference between 1 and the least value greater
1068       than 1 as per~\cite{C99}\\
1069       \hline
1070       @HS_DOUBLE_EPSILON@ & n/a
1071       & (as above)\\
1072       \hline
1073       @HS_FLOAT_DIG@ & n/a
1074       & number of decimal digits as per~\cite{C99}\\
1075       \hline
1076       @HS_DOUBLE_DIG@ & n/a
1077       & (as above)\\
1078       \hline
1079       @HS_FLOAT_MANT_DIG@ & @floatDigits :: Float@
1080       & \\
1081       \hline
1082       @HS_DOUBLE_MANT_DIG@ & @floatDigits :: Double@
1083       & \\
1084       \hline
1085       @HS_FLOAT_MIN@ & n/a
1086       & minimum floating point number as per~\cite{C99}\\
1087       \hline
1088       @HS_DOUBLE_MIN@ & n/a
1089       & (as above)\\
1090       \hline
1091       @HS_FLOAT_MIN_EXP@ & @fst . floatRange :: Float@
1092       & \\
1093       \hline
1094       @HS_DOUBLE_MIN_EXP@ & @fst . floatRange :: Double@
1095       & \\
1096       \hline
1097       @HS_FLOAT_MIN_10_EXP@ & n/a
1098       & minimum decimal exponent as per~\cite{C99}\\
1099       \hline
1100       @HS_DOUBLE_MIN_10_EXP@ & n/a
1101       & (as above)\\
1102       \hline
1103       @HS_FLOAT_MAX@ & n/a
1104       & maximum floating point number as per~\cite{C99}\\
1105       \hline
1106       @HS_DOUBLE_MAX@ & n/a
1107       & (as above)\\
1108       \hline
1109       @HS_FLOAT_MAX_EXP@ & @snd . floatRange :: Float@
1110       & \\
1111       \hline
1112       @HS_DOUBLE_MAX_EXP@ & @snd . floatRange :: Double@
1113       & \\
1114       \hline
1115       @HS_FLOAT_MAX_10_EXP@ & n/a
1116       & maximum decimal exponent as per~\cite{C99}\\
1117       \hline
1118       @HS_DOUBLE_MAX_10_EXP@ & n/a
1119       & (as above)\\
1120       \hline
1121       @HS_BOOL_FALSE@ & False
1122       & \\
1123       \hline
1124       @HS_BOOL_TRUE@ & True
1125       & \\
1126       \hline
1127     \end{tabular}
1128     \caption{C Interface to Range and Precision of Basic Types}
1129     \label{tab:c-haskell-values}
1130   \end{center}
1131 \end{table}
1132 %
1133 Every Haskell system that implements the FFI needs to provide a C header file
1134 named @HsFFI.h@ that defines the C symbols listed in
1135 Tables~\ref{tab:c-haskell-types} and~\ref{tab:c-haskell-values}.
1136 Table~\ref{tab:c-haskell-types} table lists symbols that represent types
1137 together with the Haskell type that they represent and any constraints that
1138 are placed on the concrete C types that implement these symbols.  When a C
1139 type @HsT@ represents a Haskell type @T@, the occurrence of @T@
1140 in a foreign function declaration should be matched by @HsT@ in the
1141 corresponding C function prototype.  Indeed, where the Haskell system
1142 translates Haskell to C code that invokes @foreign@ @import@ed C
1143 routines, such prototypes need to be provided and included via the header that
1144 can be specified in external entity strings for foreign C functions (cf.\ 
1145 Section~\ref{sec:ccall}); otherwise, the system behaviour is undefined.  It is
1146 guaranteed that the Haskell value @nullPtr@ is mapped to @(HsPtr) NULL@ in C and @nullFunPtr@ is mapped to @(HsFunPtr) NULL@ and
1147 vice versa.
1148
1149 Table~\ref{tab:c-haskell-values} contains symbols characterising the range and
1150 precision of the types from Table~\ref{tab:c-haskell-types}.  Where available,
1151 the table states the corresponding Haskell values.  All C symbols, with the
1152 exception of @HS_FLOAT_ROUND@ are constants that are suitable for use in
1153 @#if@ preprocessing directives.  Note that there is only one rounding
1154 style (@HS_FLOAT_ROUND@) and one radix (@HS_FLOAT_RADIX@), as
1155 this is all that is supported by ISO C~\cite{C99}.
1156
1157 Moreover, an implementation that does not support 64 bit integral types on the
1158 C side should implement @HsInt64@ and @HsWord64@ as a structure.  In
1159 this case, the bounds @HS_INT64_MIN@, @HS_INT64_MAX@, and
1160 @HS_WORD64_MAX@ are undefined.
1161
1162 In addition, to the symbols from Table~\ref{tab:c-haskell-types}
1163 and~\ref{tab:c-haskell-values}, the header @HsFFI.h@ must also contain
1164 the following prototypes:
1165 %
1166 \begin{quote}
1167 \begin{verbatim}
1168 void hs_init     (int *argc, char **argv[]);
1169 void hs_exit     (void);
1170 void hs_set_argv (int argc, char *argv[]);
1171
1172 void hs_perform_gc (void);
1173
1174 void hs_free_stable_ptr (HsStablePtr sp);
1175 void hs_free_fun_ptr    (HsFunPtr fp);
1176 \end{verbatim}
1177 \end{quote}
1178 %
1179 These routines are useful for mixed language programs, where the main
1180 application is implemented in a foreign language that accesses routines
1181 implemented in Haskell.  The function @hs_init()@ initialises the
1182 Haskell system and provides it with the available command line arguments.
1183 Upon return, the arguments solely intended for the Haskell runtime system are
1184 removed (i.e., the values that @argc@ and @argv@ point to may have
1185 changed).  This function must be called during program startup before any
1186 Haskell function is invoked; otherwise, the system behaviour is undefined.
1187 Conversely, the Haskell system is deinitialised by a call to
1188 @hs_exit()@.  Multiple invocations of @hs_init()@ are permitted,
1189 provided that they are followed by an equal number of calls to
1190 @hs_exit()@ and that the first call to @hs_exit()@ is after the
1191 last call to @hs_init()@.  In addition to nested calls to
1192 @hs_init()@, the Haskell system may be de-initialised with
1193 @hs_exit()@ and be re-initialised with @hs_init()@ at a later
1194 point in time.  This ensures that repeated initialisation due to multiple
1195 libraries being implemented in Haskell is covered.
1196
1197 The Haskell system will ignore the command line arguments passed to the second
1198 and any following calls to @hs_init()@.  Moreover, @hs_init()@ may
1199 be called with @NULL@ for both @argc@ and @argv@, signalling
1200 the absence of command line arguments.
1201
1202 The function @hs_set_argv()@ sets the values returned by the functions
1203 @getProgName@ and @getArgs@ of the module @System.Environment@ (Section~\ref{module:System.Environment}).  This function may only be invoked after
1204 @hs_init()@.  Moreover, if @hs_set_argv()@ is called at all, this
1205 call must precede the first invocation of @getProgName@ and
1206 @getArgs@.  Note that the separation of @hs_init()@ and
1207 @hs_set_argv()@ is essential in cases where in addition to the Haskell
1208 system other libraries that process command line arguments during
1209 initialisation are used.
1210
1211 The function @hs_perform_gc()@ advises the Haskell storage manager to
1212 perform a garbage collection, where the storage manager makes an effort to
1213 releases all unreachable objects.  This function must not be invoked from C
1214 functions that are imported @unsafe@ into Haskell code nor may it be used
1215 from a finalizer.
1216
1217 Finally, @hs_free_stable_ptr()@ and @hs_free_fun_ptr()@ are
1218 the C counterparts of the Haskell functions @freeStablePtr@ and
1219 @freeHaskellFunPtr@.