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