ghc/docs/libraries/Stable.sgml

   1 <sect> <idx/Stable/
   2 <label id="sec:Stable">
   3 <p>
   4
   5 This module provides two kinds of stable references to Haskell
   6 objects, stable names and stable pointers.
   7
   8 <sect1> <idx/Stable Pointers/
   9 <label id="sec:stable-pointers">
  10 <p>
  11
  12 A <em/stable pointer/ is a reference to a Haskell expression that
  13 can be passed to foreign functions via the foreign function
  14 interface.
  15
  16 Normally a Haskell object will move around from time to time, because
  17 of garbage collection, hence we can't just pass the address of an
  18 object to a foreign function and expect it to remain valid.  Stable
  19 pointers provide a level of indirection so that the foreign code can
  20 get the "real address" of the Haskell object by calling
  21 <tt/deRefStablePtr/ on the stable pointer object it has.
  22
  23 The Haskell interface provided by the <tt/Stable/ module is as follows:
  24
  25 <tscreen><verb>
  26 data StablePtr a  -- abstract, instance of: Eq.
  27 makeStablePtr  :: a -> IO (StablePtr a)
  28 deRefStablePtr :: StablePtr a -> IO a
  29 freeStablePtr  :: StablePtr a -> IO ()
  30 </verb></tscreen>
  31
  32 Care must be taken to free stable pointers that are no longer required
  33 using the <tt/freeStablePtr/ function, otherwise two bad things can
  34 happen:
  35
  36 <itemize>
  37 <item> The object referenced by the stable pointer will be retained in
  38 the heap.
  39 <item> The runtime system's internal stable pointer table will grow,
  40 which imposes an overhead on garbage collection.
  41 </itemize>
  42
  43 Notes:
  44
  45 <itemize>
  46 <item> If <tt/sp1 :: StablePtr/ and <tt/sp2 :: StablePtr/ and <tt/sp1
  47 == sp2/ then <tt/sp1/ and <tt/sp2/ are either the same stable pointer,
  48 or they were created by calls to <tt/makeStablePtr/ on the same
  49 object.  Another way to say this is "every time you call
  50 <tt/makeStablePtr/ on an object you get back the same stable pointer".
  51 <item> The reverse is not necessarily true: if two stable pointers are
  52 not equal, it doesn't mean that they don't refer to the same Haskell
  53 object (although they probably don't).  <item> Calling
  54 <tt/deRefStablePtr/ on a stable pointer which has previously been
  55 freed results in undefined behaviour.
  56 </itemize>
  57
  58 The C interface (which is brought into scope by <tt/#include
  59 &lt;Stable.h&gt;/) is as follows:
  60
  61 <tscreen><verb>
  62 typedef StablePtr /* abstract, probably an unsigned long */
  63 extern StgPtr         deRefStablePtr(StgStablePtr stable_ptr);
  64 static void           freeStablePtr(StgStablePtr sp);
  65 static StgStablePtr   splitStablePtr(StgStablePtr sp);
  66 </verb></tscreen>
  67
  68 The functions <tt/deRefStablePtr/ and <tt/freeStablePtr/ are
  69 equivalent to the Haskell functions of the same name above.
  70
  71 The function <tt/splitStablePtr/ allows a stable pointer to be
  72 duplicated without making a new one with <tt/makeStablePtr/.  The
  73 stable pointer won't be removed from the runtime system's internal
  74 table until <tt/freeStablePtr/ is called on both pointers.
  75
  76 <sect1>Stable Names
  77 <label id="sec:stable-pointers">
  78 <p>
  79
  80 A haskell object can be given a <em/stable name/ by calling
  81 <tt/makeStableName/ on it.  Stable names solve the following problem:
  82 suppose you want to build a hash table with Haskell objects as keys,
  83 but you want to use pointer equality for comparison; maybe because the
  84 keys are large and hashing would be slow, or perhaps because the keys
  85 are infinite in size.  We can't build a hash table using the address
  86 of the object as the key, because objects get moved around by the
  87 garbage collector, meaning a re-hash would be necessary after every
  88 garbage collection.
  89
  90 Enter stable names.  A stable name is an abstract entity that supports
  91 equality and hashing, with the following interface:
  92
  93 <tscreen><verb>
  94 data StableName a -- abstract, instance Eq.
  95 makeStableName :: a -> IO (StableName a)
  96 hashStableName :: StableName a -> Int
  97 </verb></tscreen>
  98
  99 All these operations run in constant time.
 100
 101 Stable names have the following properties:
 102
 103 <enum>
 104 <item> If <tt/sn1 :: StablePtr/ and <tt/sn2 :: StablePtr/ and <tt/sn1
 105 == sn2/ then <tt/sn1/ and <tt/sn2/ are either the same stable name,
 106 or they were created by calls to <tt/makeStableName/ on the same
 107 object.
 108 <item> The reverse is not necessarily true: if two stable names are
 109 not equal, it doesn't mean that they don't refer to the same Haskell
 110 object (although they probably don't).
 111 <item> There is no <tt/freeStableName/ operation.  Stable names are
 112 reclaimed by the runtime system when they are no longer needed.
 113 <item> There is no <tt/deRefStableName/ operation.  You can't get back
 114 from a stable name to the original Haskell object.  The reason for
 115 this is that the existence of a stable name for an object doesn't
 116 guarantee the existence of the object itself; it can still be garbage
 117 collected.
 118 <item> There is a <tt/hashStableName/ operation, which converts a
 119 stable name to an <tt/Int/.  The <tt/Int/ returned is not necessarily
 120 unique (that is, it doesn't satisfy property (1) above), but it can be
 121 used for building hash tables of stable names.
 122 </enum>
 123
 124 Properties (1) and (2) are similar to stable pointers, but the key
 125 differences are that you can't get back to the original object from a
 126 stable name, and you can convert one to an <tt/Int/ for hashing.