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.