Foreign/StablePtr.hs

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