[project @ 2002-05-09 13:13:28 by simonmar]

[ghc-base.git] / Foreign / StablePtr.hs

diff --git a/Foreign/StablePtr.hs b/Foreign/StablePtr.hs
index 1b169d0..9b1bb9b 100644 (file)
--- a/Foreign/StablePtr.hs
+++ b/Foreign/StablePtr.hs
@@ -9,20 +9,40 @@
 -- Stability   :  provisional
 -- Portability :  portable
 --
--- Stable pointers.
+-- This module is part of the Foreign Function Interface (FFI) and will usually
+-- be imported via the module "Foreign".
 --
 -----------------------------------------------------------------------------
 
+
 module Foreign.StablePtr
-        ( StablePtr,         -- abstract
+        ( -- * Stable references to Haskell values
+         StablePtr,         -- abstract
         , newStablePtr       -- :: a -> IO (StablePtr a)
         , deRefStablePtr     -- :: StablePtr a -> IO a
         , freeStablePtr      -- :: StablePtr a -> IO ()
         , castStablePtrToPtr -- :: StablePtr a -> Ptr ()
         , castPtrToStablePtr -- :: Ptr () -> StablePtr a
+       , -- ** The C-side interface
+
+         -- $cinterface
         ) where
 
 #ifdef __GLASGOW_HASKELL__
 import GHC.Stable
 import GHC.Err
 #endif
+
+
+-- $cinterface
+--
+-- The following definition is available to C programs inter-operating with
+-- Haskell code when including the header @HsFFI.h@.
+--
+-- > typedef void *HsStablePtr;  /* C representation of a StablePtr */
+--
+-- Note that no assumptions may be made about the values representing stable
+-- pointers.  In fact, they need not even be valid memory addresses.  The only
+-- guarantee provided is that if they are passed back to Haskell land, the
+-- function 'deRefStablePtr' will be able to reconstruct the
+-- Haskell value refereed to by the stable pointer.