522c6fc3449c5fcc2058d0b7260e7ab8c4cf85d3
[ghc.git] / libraries / base / Foreign / StablePtr.hs
1 {-# LANGUAGE CPP, NoImplicitPrelude #-}
2
3 -----------------------------------------------------------------------------
4 -- |
5 -- Module : Foreign.StablePtr
6 -- Copyright : (c) The University of Glasgow 2001
7 -- License : BSD-style (see the file libraries/base/LICENSE)
8 --
9 -- Maintainer : ffi@haskell.org
10 -- Stability : provisional
11 -- Portability : portable
12 --
13 -- This module is part of the Foreign Function Interface (FFI) and will usually
14 -- be imported via the module "Foreign".
15 --
16 -----------------------------------------------------------------------------
17
18
19 module Foreign.StablePtr
20 ( -- * Stable references to Haskell values
21 StablePtr -- abstract
22 , newStablePtr -- :: a -> IO (StablePtr a)
23 , deRefStablePtr -- :: StablePtr a -> IO a
24 , freeStablePtr -- :: StablePtr a -> IO ()
25 , castStablePtrToPtr -- :: StablePtr a -> Ptr ()
26 , castPtrToStablePtr -- :: Ptr () -> StablePtr a
27 , -- ** The C-side interface
28
29 -- $cinterface
30 ) where
31
32 #ifdef __GLASGOW_HASKELL__
33 import GHC.Stable
34 #endif
35
36 #ifdef __HUGS__
37 import Hugs.StablePtr
38 #endif
39
40 #ifdef __NHC__
41 import NHC.FFI
42 ( StablePtr
43 , newStablePtr
44 , deRefStablePtr
45 , freeStablePtr
46 , castStablePtrToPtr
47 , castPtrToStablePtr
48 )
49 #endif
50
51 -- $cinterface
52 --
53 -- The following definition is available to C programs inter-operating with
54 -- Haskell code when including the header @HsFFI.h@.
55 --
56 -- > typedef void *HsStablePtr; /* C representation of a StablePtr */
57 --
58 -- Note that no assumptions may be made about the values representing stable
59 -- pointers. In fact, they need not even be valid memory addresses. The only
60 -- guarantee provided is that if they are passed back to Haskell land, the
61 -- function 'deRefStablePtr' will be able to reconstruct the
62 -- Haskell value referred to by the stable pointer.