6d41fa15d194b13258184b9dd48dd3b61582a64c
[ghc.git] / docs / users_guide / ffi-chap.rst
1 .. _ffi:
2
3 Foreign function interface (FFI)
4 ================================
5
6 .. index::
7    single: Foreign function interface
8    single: interfacing with native code
9
10 .. ghc-flag:: -XForeignFunctionInterface
11     :shortdesc: Enable :ref:`foreign function interface <ffi>`.
12     :type: dynamic
13     :reverse: -XNoForeignFunctionInterface
14     :category: language
15
16     :since: 6.8.1
17
18     Allow use of the Haskell foreign function interface.
19
20 GHC (mostly) conforms to the Haskell Foreign Function Interface, whose
21 definition is part of the Haskell Report on
22 `http://www.haskell.org/ <http://www.haskell.org/>`__.
23
24 FFI support is enabled by default, but can be enabled or disabled
25 explicitly with the :ghc-flag:`-XForeignFunctionInterface` flag.
26
27 GHC implements a number of GHC-specific extensions to the FFI Chapter of the
28 Haskell 2010 Report. These extensions are described in :ref:`ffi-ghcexts`, but
29 please note that programs using these features are not portable. Hence, these
30 features should be avoided where possible.
31
32 The FFI libraries are documented in the accompanying  library
33 documentation; see for example the :base-ref:`Foreign.` module.
34
35 GHC differences to the FFI Chapter
36 ----------------------------------
37
38 Guaranteed call safety
39 ~~~~~~~~~~~~~~~~~~~~~~
40
41 The FFI addendum stipulates that an implementation is free to implement an
42 ``unsafe`` call by performing a ``safe`` call (and therefore may run in an
43 arbitrary thread and may be subject to concurrent garbage collection). This
44 greatly constrains library authors since it implies that it is never safe to
45 pass any heap object reference to a foreign function, even if invoked with an
46 ``unsafe`` call. For instance, it is often desirable to pass an unpinned
47 ``ByteArray#``\s directly to native code to avoid making an
48 otherwise-unnecessary copy. However, this can only be done safely under
49 ``unsafe`` call semantics as otherwise the array may be moved by the garbage
50 collector in the middle of the call.
51
52 In previous releases, GHC would take advantage of the freedom afforded by the
53 Chapter by performing ``safe`` foreign calls in place of ``unsafe`` calls in
54 the bytecode interpreter. This meant that some packages which worked when
55 compiled would fail under GHCi (e.g. :ghc-ticket:`13730`).
56
57 However, since version 8.4 this is no longer the case: GHC **guarantees** that
58 garbage collection will never occur during an ``unsafe`` call, even in the
59 bytecode interpreter.
60
61
62 .. _ffi-ghcexts:
63
64 GHC extensions to the FFI Chapter
65 ---------------------------------
66
67 The FFI features that are described in this section are specific to GHC.
68 Your code will not be portable to other compilers if you use them.
69
70 Unboxed types
71 ~~~~~~~~~~~~~
72
73 The following unboxed types may be used as basic foreign types (see FFI
74 Chapter, Section 8.6): ``Int#``, ``Word#``, ``Char#``, ``Float#``,
75 ``Double#``, ``Addr#``, ``StablePtr# a``, ``MutableByteArray#``,
76 ``ForeignObj#``, and ``ByteArray#``.
77
78 .. _ffi-newtype-io:
79
80 Newtype wrapping of the IO monad
81 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
82
83 The FFI spec requires the IO monad to appear in various places, but it
84 can sometimes be convenient to wrap the IO monad in a ``newtype``, thus: ::
85
86       newtype MyIO a = MIO (IO a)
87
88 (A reason for doing so might be to prevent the programmer from calling
89 arbitrary IO procedures in some part of the program.)
90
91 The Haskell FFI already specifies that arguments and results of foreign
92 imports and exports will be automatically unwrapped if they are newtypes
93 (Section 3.2 of the FFI addendum). GHC extends the FFI by automatically
94 unwrapping any newtypes that wrap the IO monad itself. More precisely,
95 wherever the FFI specification requires an ``IO`` type, GHC will accept any
96 newtype-wrapping of an ``IO`` type. For example, these declarations are
97 OK: ::
98
99        foreign import foo :: Int -> MyIO Int
100        foreign import "dynamic" baz :: (Int -> MyIO Int) -> CInt -> MyIO Int
101
102 .. _ffi-prim:
103
104 Primitive imports
105 ~~~~~~~~~~~~~~~~~
106
107 GHC extends the FFI with an additional calling convention ``prim``,
108 e.g.: ::
109
110        foreign import prim "foo" foo :: ByteArray# -> (# Int#, Int# #)
111
112 This is used to import functions written in Cmm code that follow an
113 internal GHC calling convention. The arguments and results must be
114 unboxed types, except that an argument may be of type ``Any`` (by way of
115 ``unsafeCoerce#``) and the result type is allowed to be an unboxed tuple
116 or the type ``Any``.
117
118 This feature is not intended for use outside of the core libraries that
119 come with GHC. For more details see the
120 :ghc-wiki:`GHC developer wiki <Commentary/PrimOps>`.
121
122 .. _ffi-interruptible:
123
124 Interruptible foreign calls
125 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
126
127 .. ghc-flag:: -XInterruptibleFFI
128     :shortdesc: Enable interruptible FFI.
129     :type: dynamic
130     :reverse: -XNoInterruptibleFFI
131     :category: language
132
133     :since: 7.2.1
134
135 This concerns the interaction of foreign calls with
136 ``Control.Concurrent.throwTo``. Normally when the target of a
137 ``throwTo`` is involved in a foreign call, the exception is not raised
138 until the call returns, and in the meantime the caller is blocked. This
139 can result in unresponsiveness, which is particularly undesirable in the
140 case of user interrupt (e.g. Control-C). The default behaviour when a
141 Control-C signal is received (``SIGINT`` on Unix) is to raise the
142 ``UserInterrupt`` exception in the main thread; if the main thread is
143 blocked in a foreign call at the time, then the program will not respond
144 to the user interrupt.
145
146 The problem is that it is not possible in general to interrupt a foreign
147 call safely. However, GHC does provide a way to interrupt blocking
148 system calls which works for most system calls on both Unix and Windows.
149 When the ``InterruptibleFFI`` extension is enabled, a foreign call can
150 be annotated with ``interruptible`` instead of ``safe`` or ``unsafe``: ::
151
152     foreign import ccall interruptible
153        "sleep" sleepBlock :: CUint -> IO CUint
154
155 ``interruptible`` behaves exactly as ``safe``, except that when a
156 ``throwTo`` is directed at a thread in an interruptible foreign call, an
157 OS-specific mechanism will be used to attempt to cause the foreign call
158 to return:
159
160 Unix systems
161     The thread making the foreign call is sent a ``SIGPIPE`` signal
162     using ``pthread_kill()``. This is usually enough to cause a blocking
163     system call to return with ``EINTR`` (GHC by default installs an
164     empty signal handler for ``SIGPIPE``, to override the default
165     behaviour which is to terminate the process immediately).
166
167 Windows systems
168     [Vista and later only] The RTS calls the Win32 function
169     ``CancelSynchronousIO``, which will cause a blocking I/O operation
170     to return with the error ``ERROR_OPERATION_ABORTED``.
171
172 If the system call is successfully interrupted, it will return to
173 Haskell whereupon the exception can be raised. Be especially careful
174 when using ``interruptible`` that the caller of the foreign function is
175 prepared to deal with the consequences of the call being interrupted; on
176 Unix it is good practice to check for ``EINTR`` always, but on Windows
177 it is not typically necessary to handle ``ERROR_OPERATION_ABORTED``.
178
179 .. _ffi-capi:
180
181 The CAPI calling convention
182 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
183
184 .. ghc-flag:: -XCApiFFI
185     :shortdesc: Enable :ref:`the CAPI calling convention <ffi-capi>`.
186     :type: dynamic
187     :reverse: -XNoCAPIFFI
188     :category: language
189
190     :since: 7.10.1
191
192 The ``CApiFFI`` extension allows a calling convention of ``capi`` to be
193 used in foreign declarations, e.g. ::
194
195     foreign import capi "header.h f" f :: CInt -> IO CInt
196
197 Rather than generating code to call ``f`` according to the platform's
198 ABI, we instead call ``f`` using the C API defined in the header
199 ``header.h``. Thus ``f`` can be called even if it may be defined as a
200 CPP ``#define`` rather than a proper function.
201
202 When using ``capi``, it is also possible to import values, rather than
203 functions. For example, ::
204
205     foreign import capi "pi.h value pi" c_pi :: CDouble
206
207 will work regardless of whether ``pi`` is defined as
208
209 .. code-block:: c
210
211     const double pi = 3.14;
212
213 or with
214
215 .. code-block:: c
216
217     #define pi 3.14
218
219 In order to tell GHC the C type that a Haskell type corresponds to when
220 it is used with the CAPI, a ``CTYPE`` pragma can be used on the type
221 definition. The header which defines the type can optionally also be
222 specified. The syntax looks like: ::
223
224     data    {-# CTYPE "unistd.h" "useconds_t" #-} T = ...
225     newtype {-# CTYPE            "useconds_t" #-} T = ...
226
227 ``hs_thread_done()``
228 ~~~~~~~~~~~~~~~~~~~~
229
230 .. code-block:: c
231
232     void hs_thread_done(void);
233
234 GHC allocates a small amount of thread-local memory when a thread calls
235 a Haskell function via a ``foreign export``. This memory is not normally
236 freed until ``hs_exit()``; the memory is cached so that subsequent calls
237 into Haskell are fast. However, if your application is long-running and
238 repeatedly creates new threads that call into Haskell, you probably want
239 to arrange that this memory is freed in those threads that have finished
240 calling Haskell functions. To do this, call ``hs_thread_done()`` from
241 the thread whose memory you want to free.
242
243 Calling ``hs_thread_done()`` is entirely optional. You can call it as
244 often or as little as you like. It is safe to call it from a thread that
245 has never called any Haskell functions, or one that never will. If you
246 forget to call it, the worst that can happen is that some memory remains
247 allocated until ``hs_exit()`` is called. If you call it too often, the
248 worst that can happen is that the next call to a Haskell function incurs
249 some extra overhead.
250
251 .. _ffi-ghc:
252
253 Using the FFI with GHC
254 ----------------------
255
256 The following sections also give some hints and tips on the use of the
257 foreign function interface in GHC.
258
259 .. _foreign-export-ghc:
260
261 Using ``foreign export`` and ``foreign import ccall "wrapper"`` with GHC
262 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
263
264 .. index::
265    single: foreign export; with GHC
266
267 When GHC compiles a module (say ``M.hs``) which uses ``foreign export``
268 or ``foreign import "wrapper"``, it generates a ``M_stub.h`` for use by
269 C programs.
270
271 For a plain ``foreign export``, the file ``M_stub.h`` contains a C
272 prototype for the foreign exported function. For example, if we compile
273 the following module: ::
274
275     module Foo where
276
277     foreign export ccall foo :: Int -> IO Int
278
279     foo :: Int -> IO Int
280     foo n = return (length (f n))
281
282     f :: Int -> [Int]
283     f 0 = []
284     f n = n:(f (n-1))
285
286 Then ``Foo_stub.h`` will contain something like this:
287
288 .. code-block:: c
289
290     #include "HsFFI.h"
291     extern HsInt foo(HsInt a0);
292
293 To invoke ``foo()`` from C, just ``#include "Foo_stub.h"`` and call
294 ``foo()``.
295
296 The ``Foo_stub.h`` file can be redirected using the ``-stubdir`` option;
297 see :ref:`options-output`.
298
299 .. _using-own-main:
300
301 Using your own ``main()``
302 ^^^^^^^^^^^^^^^^^^^^^^^^^
303
304 Normally, GHC's runtime system provides a ``main()``, which arranges to
305 invoke ``Main.main`` in the Haskell program. However, you might want to
306 link some Haskell code into a program which has a main function written
307 in another language, say C. In order to do this, you have to initialize
308 the Haskell runtime system explicitly.
309
310 Let's take the example from above, and invoke it from a standalone C
311 program. Here's the C code:
312
313 .. code-block:: c
314
315     #include <stdio.h>
316     #include "HsFFI.h"
317
318     #ifdef __GLASGOW_HASKELL__
319     #include "Foo_stub.h"
320     #endif
321
322     int main(int argc, char *argv[])
323     {
324       int i;
325
326       hs_init(&argc, &argv);
327
328       for (i = 0; i < 5; i++) {
329         printf("%d\n", foo(2500));
330       }
331
332       hs_exit();
333       return 0;
334     }
335
336 We've surrounded the GHC-specific bits with
337 ``#ifdef __GLASGOW_HASKELL__``; the rest of the code should be portable
338 across Haskell implementations that support the FFI standard.
339
340 The call to ``hs_init()`` initializes GHC's runtime system. Do NOT try
341 to invoke any Haskell functions before calling ``hs_init()``: bad things
342 will undoubtedly happen.
343
344 We pass references to ``argc`` and ``argv`` to ``hs_init()`` so that it
345 can separate out any arguments for the RTS (i.e. those arguments between
346 ``+RTS...-RTS``).
347
348 After we've finished invoking our Haskell functions, we can call
349 ``hs_exit()``, which terminates the RTS.
350
351 There can be multiple calls to ``hs_init()``, but each one should be matched by
352 one (and only one) call to ``hs_exit()``. The outermost ``hs_exit()`` will
353 actually de-initialise the system.  Note that currently GHC's runtime cannot
354 reliably re-initialise after this has happened; see :ref:`infelicities-ffi`.
355
356 .. note::
357     When linking the final program, it is normally easiest to do the
358     link using GHC, although this isn't essential. If you do use GHC, then
359     don't forget the flag :ghc-flag:`-no-hs-main`, otherwise GHC
360     will try to link to the ``Main`` Haskell module.
361
362 .. note::
363     On Windows hs_init treats argv as UTF8-encoded. Passing other encodings
364     might lead to unexpected results. Passing NULL as argv is valid but can
365     lead to <unknown> showing up in error messages instead of the name of the
366     executable.
367
368 To use ``+RTS`` flags with ``hs_init()``, we have to modify the example
369 slightly. By default, GHC's RTS will only accept "safe" ``+RTS`` flags (see
370 :ref:`options-linker`), and the :ghc-flag:`-rtsopts[=⟨none|some|all⟩]`
371 link-time flag overrides this. However, :ghc-flag:`-rtsopts[=⟨none|some|all⟩]`
372 has no effect when :ghc-flag:`-no-hs-main` is in use (and the same goes for
373 :ghc-flag:`-with-rtsopts=⟨opts⟩`). To set these options we have to call a
374 GHC-specific API instead of ``hs_init()``:
375
376 .. code-block:: c
377
378     #include <stdio.h>
379     #include "HsFFI.h"
380
381     #ifdef __GLASGOW_HASKELL__
382     #include "Foo_stub.h"
383     #include "Rts.h"
384     #endif
385
386     int main(int argc, char *argv[])
387     {
388       int i;
389
390     #if __GLASGOW_HASKELL__ >= 703
391       {
392           RtsConfig conf = defaultRtsConfig;
393           conf.rts_opts_enabled = RtsOptsAll;
394           hs_init_ghc(&argc, &argv, conf);
395       }
396     #else
397       hs_init(&argc, &argv);
398     #endif
399
400       for (i = 0; i < 5; i++) {
401         printf("%d\n", foo(2500));
402       }
403
404       hs_exit();
405       return 0;
406     }
407
408 Note two changes: we included ``Rts.h``, which defines the GHC-specific
409 external RTS interface, and we called ``hs_init_ghc()`` instead of
410 ``hs_init()``, passing an argument of type ``RtsConfig``. ``RtsConfig``
411 is a struct with various fields that affect the behaviour of the runtime
412 system. Its definition is:
413
414 .. code-block:: c
415
416     typedef struct {
417         RtsOptsEnabledEnum rts_opts_enabled;
418         const char *rts_opts;
419     } RtsConfig;
420
421     extern const RtsConfig defaultRtsConfig;
422
423     typedef enum {
424         RtsOptsNone,         // +RTS causes an error
425         RtsOptsSafeOnly,     // safe RTS options allowed; others cause an error
426         RtsOptsAll           // all RTS options allowed
427       } RtsOptsEnabledEnum;
428
429 There is a default value ``defaultRtsConfig`` that should be used to
430 initialise variables of type ``RtsConfig``. More fields will undoubtedly
431 be added to ``RtsConfig`` in the future, so in order to keep your code
432 forwards-compatible it is best to initialise with ``defaultRtsConfig``
433 and then modify the required fields, as in the code sample above.
434
435 .. _ffi-library:
436
437 Making a Haskell library that can be called from foreign code
438 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
439
440 The scenario here is much like in :ref:`using-own-main`, except that the
441 aim is not to link a complete program, but to make a library from
442 Haskell code that can be deployed in the same way that you would deploy
443 a library of C code.
444
445 The main requirement here is that the runtime needs to be initialized
446 before any Haskell code can be called, so your library should provide
447 initialisation and deinitialisation entry points, implemented in C or
448 C++. For example:
449
450 .. code-block:: c
451
452     #include <stdlib.h>
453     #include "HsFFI.h"
454
455     HsBool mylib_init(void){
456       int argc = 2;
457       char *argv[] = { "+RTS", "-A32m", NULL };
458       char **pargv = argv;
459
460       // Initialize Haskell runtime
461       hs_init(&argc, &pargv);
462
463       // do any other initialization here and
464       // return false if there was a problem
465       return HS_BOOL_TRUE;
466     }
467
468     void mylib_end(void){
469       hs_exit();
470     }
471
472 The initialisation routine, ``mylib_init``, calls ``hs_init()`` as
473 normal to initialise the Haskell runtime, and the corresponding
474 deinitialisation function ``mylib_end()`` calls ``hs_exit()`` to shut
475 down the runtime.
476
477 .. _glasgow-foreign-headers:
478
479 Using header files
480 ~~~~~~~~~~~~~~~~~~
481
482 .. index::
483    single: C calls, function headers
484
485 C functions are normally declared using prototypes in a C header file.
486 Earlier versions of GHC (6.8.3 and earlier) ``#include``\ d the header
487 file in the C source file generated from the Haskell code, and the C
488 compiler could therefore check that the C function being called via the
489 FFI was being called at the right type.
490
491 GHC no longer includes external header files when compiling via C, so
492 this checking is not performed. The change was made for compatibility
493 with the :ref:`native code generator <native-code-gen>` (:ghc-flag:`-fasm`) and to
494 comply strictly with the FFI specification, which requires that FFI calls are
495 not subject to macro expansion and other CPP conversions that may be applied
496 when using C header files. This approach also simplifies the inlining of foreign
497 calls across module and package boundaries: there's no need for the header file
498 to be available when compiling an inlined version of a foreign call, so the
499 compiler is free to inline foreign calls in any context.
500
501 The ``-#include`` option is now deprecated, and the ``include-files``
502 field in a Cabal package specification is ignored.
503
504 Memory Allocation
505 ~~~~~~~~~~~~~~~~~
506
507 The FFI libraries provide several ways to allocate memory for use with
508 the FFI, and it isn't always clear which way is the best. This decision
509 may be affected by how efficient a particular kind of allocation is on a
510 given compiler/platform, so this section aims to shed some light on how
511 the different kinds of allocation perform with GHC.
512
513 ``alloca``
514     Useful for short-term allocation when the allocation is intended to
515     scope over a given ``IO`` computation. This kind of allocation is
516     commonly used when marshalling data to and from FFI functions.
517
518     In GHC, ``alloca`` is implemented using ``MutableByteArray#``, so
519     allocation and deallocation are fast: much faster than C's
520     ``malloc/free``, but not quite as fast as stack allocation in C. Use
521     ``alloca`` whenever you can.
522
523 ``mallocForeignPtr``
524     Useful for longer-term allocation which requires garbage collection.
525     If you intend to store the pointer to the memory in a foreign data
526     structure, then ``mallocForeignPtr`` is *not* a good choice,
527     however.
528
529     In GHC, ``mallocForeignPtr`` is also implemented using
530     ``MutableByteArray#``. Although the memory is pointed to by a
531     ``ForeignPtr``, there are no actual finalizers involved (unless you
532     add one with ``addForeignPtrFinalizer``), and the deallocation is
533     done using GC, so ``mallocForeignPtr`` is normally very cheap.
534
535 ``malloc/free``
536     If all else fails, then you need to resort to ``Foreign.malloc`` and
537     ``Foreign.free``. These are just wrappers around the C functions of
538     the same name, and their efficiency will depend ultimately on the
539     implementations of these functions in your platform's C library. We
540     usually find ``malloc`` and ``free`` to be significantly slower than
541     the other forms of allocation above.
542
543 ``Foreign.Marshal.Pool``
544     Pools are currently implemented using ``malloc/free``, so while they
545     might be a more convenient way to structure your memory allocation
546     than using one of the other forms of allocation, they won't be any
547     more efficient. We do plan to provide an improved-performance
548     implementation of Pools in the future, however.
549
550 .. _ffi-threads:
551
552 Multi-threading and the FFI
553 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
554
555 In order to use the FFI in a multi-threaded setting, you must use the
556 :ghc-flag:`-threaded` option (see :ref:`options-linker`).
557
558 Foreign imports and multi-threading
559 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
560
561 When you call a ``foreign import``\ ed function that is annotated as
562 ``safe`` (the default), and the program was linked using :ghc-flag:`-threaded`,
563 then the call will run concurrently with other running Haskell threads.
564 If the program was linked without :ghc-flag:`-threaded`, then the other Haskell
565 threads will be blocked until the call returns.
566
567 This means that if you need to make a foreign call to a function that
568 takes a long time or blocks indefinitely, then you should mark it
569 ``safe`` and use :ghc-flag:`-threaded`. Some library functions make such calls
570 internally; their documentation should indicate when this is the case.
571
572 If you are making foreign calls from multiple Haskell threads and using
573 :ghc-flag:`-threaded`, make sure that the foreign code you are calling is
574 thread-safe. In particularly, some GUI libraries are not thread-safe and
575 require that the caller only invokes GUI methods from a single thread.
576 If this is the case, you may need to restrict your GUI operations to a
577 single Haskell thread, and possibly also use a bound thread (see
578 :ref:`haskell-threads-and-os-threads`).
579
580 Note that foreign calls made by different Haskell threads may execute in
581 *parallel*, even when the ``+RTS -N`` flag is not being used
582 (:ref:`parallel-options`). The :rts-flag:`-N ⟨x⟩` flag controls parallel
583 execution of Haskell threads, but there may be an arbitrary number of
584 foreign calls in progress at any one time, regardless of the ``+RTS -N``
585 value.
586
587 If a call is annotated as ``interruptible`` and the program was
588 multithreaded, the call may be interrupted in the event that the Haskell
589 thread receives an exception. The mechanism by which the interrupt
590 occurs is platform dependent, but is intended to cause blocking system
591 calls to return immediately with an interrupted error code. The
592 underlying operating system thread is not to be destroyed. See
593 :ref:`ffi-interruptible` for more details.
594
595 .. _haskell-threads-and-os-threads:
596
597 The relationship between Haskell threads and OS threads
598 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
599
600 Normally there is no fixed relationship between Haskell threads and OS
601 threads. This means that when you make a foreign call, that call may
602 take place in an unspecified OS thread. Furthermore, there is no
603 guarantee that multiple calls made by one Haskell thread will be made by
604 the same OS thread.
605
606 This usually isn't a problem, and it allows the GHC runtime system to
607 make efficient use of OS thread resources. However, there are cases
608 where it is useful to have more control over which OS thread is used,
609 for example when calling foreign code that makes use of thread-local
610 state. For cases like this, we provide *bound threads*, which are
611 Haskell threads tied to a particular OS thread. For information on bound
612 threads, see the documentation for the :base-ref:`Control.Concurrent.` module.
613
614 Foreign exports and multi-threading
615 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
616
617 When the program is linked with :ghc-flag:`-threaded`, then you may invoke
618 ``foreign export``\ ed functions from multiple OS threads concurrently.
619 The runtime system must be initialised as usual by calling
620 ``hs_init()``, and this call must complete before invoking any
621 ``foreign export``\ ed functions.
622
623 .. _hs-exit:
624
625 On the use of ``hs_exit()``
626 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
627
628 ``hs_exit()`` normally causes the termination of any running Haskell
629 threads in the system, and when ``hs_exit()`` returns, there will be no
630 more Haskell threads running. The runtime will then shut down the system
631 in an orderly way, generating profiling output and statistics if
632 necessary, and freeing all the memory it owns.
633
634 It isn't always possible to terminate a Haskell thread forcibly: for
635 example, the thread might be currently executing a foreign call, and we
636 have no way to force the foreign call to complete. What's more, the
637 runtime must assume that in the worst case the Haskell code and runtime
638 are about to be removed from memory (e.g. if this is a
639 :ref:`Windows DLL <win32-dlls>`, ``hs_exit()`` is normally called before unloading
640 the DLL). So ``hs_exit()`` *must* wait until all outstanding foreign
641 calls return before it can return itself.
642
643 The upshot of this is that if you have Haskell threads that are blocked
644 in foreign calls, then ``hs_exit()`` may hang (or possibly busy-wait)
645 until the calls return. Therefore it's a good idea to make sure you
646 don't have any such threads in the system when calling ``hs_exit()``.
647 This includes any threads doing I/O, because I/O may (or may not,
648 depending on the type of I/O and the platform) be implemented using
649 blocking foreign calls.
650
651 The GHC runtime treats program exit as a special case, to avoid the need
652 to wait for blocked threads when a standalone executable exits. Since
653 the program and all its threads are about to terminate at the same time
654 that the code is removed from memory, it isn't necessary to ensure that
655 the threads have exited first.  If you want this fast and loose
656 version of ``hs_exit()``, you can call:
657
658 .. code-block:: c
659
660    void hs_exit_nowait(void);
661
662 instead.  This is particularly useful if you have foreign libraries
663 that need to call ``hs_exit()`` at program exit (perhaps via a C++
664 destructor): in this case you should use ``hs_exit_nowait()``, because
665 the thread that called ``exit()`` and is running C++ destructors is in
666 a foreign call from Haskell that will never return, so ``hs_exit()``
667 would deadlock.
668
669 .. _hs_try_putmvar:
670
671 Waking up Haskell threads from C
672 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
673
674 Sometimes we want to be able to wake up a Haskell thread from some C
675 code.  For example, when using a callback-based C API, we register a C
676 callback and then we need to wait for the callback to run.
677
678 One way to do this is to create a ``foreign export`` that will do
679 whatever needs to be done to wake up the Haskell thread - perhaps
680 ``putMVar`` - and then call this from our C callback.  There are a
681 couple of problems with this:
682
683 1. Calling a foreign export has a lot of overhead: it creates a
684    complete new Haskell thread, for example.
685 2. The call may block for a long time if a GC is in progress.  We
686    can't use this method if the C API we're calling doesn't allow
687    blocking in the callback.
688
689 For these reasons GHC provides an external API to ``tryPutMVar``,
690 ``hs_try_putmvar``, which you can use to cheaply and asynchronously
691 wake up a Haskell thread from C/C++.
692
693 .. code-block:: c
694
695   void hs_try_putmvar (int capability, HsStablePtr sp);
696
697 The C call ``hs_try_putmvar(cap, mvar)`` is equivalent to the Haskell
698 call ``tryPutMVar mvar ()``, except that it is
699
700 * non-blocking: takes a bounded, short, amount of time
701
702 * asynchronous: the actual putMVar may be performed after the call
703   returns (for example, if the RTS is currently garbage collecting).
704   That's why ``hs_try_putmvar()`` doesn't return a result to say
705   whether the put succeeded.  It is your responsibility to ensure that
706   the ``MVar`` is empty; if it is full, ``hs_try_putmvar()`` will have
707   no effect.
708
709 **Example**. Suppose we have a C/C++ function to call that will return and then
710 invoke a callback at some point in the future, passing us some data.
711 We want to wait in Haskell for the callback to be called, and retrieve
712 the data.  We can do it like this:
713
714 .. code-block:: haskell
715
716      import GHC.Conc (newStablePtrPrimMVar, PrimMVar)
717
718      makeExternalCall = mask_ $ do
719        mvar <- newEmptyMVar
720        sp <- newStablePtrPrimMVar mvar
721        fp <- mallocForeignPtr
722        withForeignPtr fp $ \presult -> do
723          cap <- threadCapability =<< myThreadId
724          scheduleCallback sp cap presult
725          takeMVar mvar `onException`
726            forkIO (do takeMVar mvar; touchForeignPtr fp)
727          peek presult
728
729      foreign import ccall "scheduleCallback"
730          scheduleCallback :: StablePtr PrimMVar
731                           -> Int
732                           -> Ptr Result
733                           -> IO ()
734
735 And inside ``scheduleCallback``, we create a callback that will in due
736 course store the result data in the ``Ptr Result``, and then call
737 ``hs_try_putmvar()``.
738
739 There are a few things to note here.
740
741 * There's a special function to create the ``StablePtr``:
742   ``newStablePtrPrimMVar``, because the RTS needs a ``StablePtr`` to
743   the primitive ``MVar#`` object, and we can't create that directly.
744   Do *not* just use ``newStablePtr`` on the ``MVar``: your program
745   will crash.
746
747 * The ``StablePtr`` is freed by ``hs_try_putmvar()``.  This is because
748   it would otherwise be difficult to arrange to free the ``StablePtr``
749   reliably: we can't free it in Haskell, because if the ``takeMVar``
750   is interrupted by an asynchronous exception, then the callback will
751   fire at a later time.  We can't free it in C, because we don't know
752   when to free it (not when ``hs_try_putmvar()`` returns, because that
753   is an async call that uses the ``StablePtr`` at some time in the
754   future).
755
756 * The ``mask_`` is to avoid asynchronous exceptions before the
757   ``scheduleCallback`` call, which would leak the ``StablePtr``.
758
759 * We find out the current capability number and pass it to C.  This is
760   passed back to ``hs_try_putmvar``, and helps the RTS to know which
761   capability it should try to perform the ``tryPutMVar`` on.  If you
762   don't care, you can pass ``-1`` for the capability to
763   ``hs_try_putmvar``, and it will pick an arbitrary one.
764
765   Picking the right capability will help avoid unnecessary context
766   switches.  Ideally you should pass the capability that the thread
767   that will be woken up last ran on, which you can find by calling
768   ``threadCapability`` in Haskell.
769
770 * If you want to also pass some data back from the C callback to
771   Haskell, this is best done by first allocating some memory in
772   Haskell to receive the data, and passing the address to C, as we did
773   in the above example.
774
775 * ``takeMVar`` can be interrupted by an asynchronous exception.  If
776   this happens, the callback in C will still run at some point in the
777   future, will still write the result, and will still call
778   ``hs_try_putmvar()``.  Therefore we have to arrange that the memory
779   for the result stays alive until the callback has run, so if an
780   exception is thrown during ``takeMVar`` we fork another thread to
781   wait for the callback and hold the memory alive using
782   ``touchForeignPtr``.
783
784 For a fully working example, see
785 ``testsuite/tests/concurrent/should_run/hs_try_putmvar001.hs`` in the
786 GHC source tree.
787
788 .. _ffi-floating-point:
789
790 Floating point and the FFI
791 ~~~~~~~~~~~~~~~~~~~~~~~~~~
792
793 .. index::
794    single: Floating point; and the FFI
795
796 The standard C99 ``fenv.h`` header provides operations for inspecting
797 and modifying the state of the floating point unit. In particular, the
798 rounding mode used by floating point operations can be changed, and the
799 exception flags can be tested.
800
801 In Haskell, floating-point operations have pure types, and the
802 evaluation order is unspecified. So strictly speaking, since the
803 ``fenv.h`` functions let you change the results of, or observe the
804 effects of floating point operations, use of ``fenv.h`` renders the
805 behaviour of floating-point operations anywhere in the program
806 undefined.
807
808 Having said that, we *can* document exactly what GHC does with respect
809 to the floating point state, so that if you really need to use
810 ``fenv.h`` then you can do so with full knowledge of the pitfalls:
811
812 -  GHC completely ignores the floating-point environment, the runtime
813    neither modifies nor reads it.
814
815 -  The floating-point environment is not saved over a normal thread
816    context-switch. So if you modify the floating-point state in one
817    thread, those changes may be visible in other threads. Furthermore,
818    testing the exception state is not reliable, because a context switch
819    may change it. If you need to modify or test the floating point state
820    and use threads, then you must use bound threads
821    (``Control.Concurrent.forkOS``), because a bound thread has its own
822    OS thread, and OS threads do save and restore the floating-point
823    state.
824
825 -  It is safe to modify the floating-point unit state temporarily during
826    a foreign call, because foreign calls are never pre-empted by GHC.
827