16. Weak

The Weak library provides a "weak pointer" abstraction, giving the user some control over the garbage collection of specified objects, and allowing objects to be "finalised" with an arbitrary Haskell IO computation when they die.

Weak pointers partially replace the old foreign object interface, as we will explain later.

16.1 Module Signature

module Weak (
        Weak,                   -- abstract
        -- instance Eq (Weak v)  

        mkWeak,                 -- :: k -> v -> IO () -> IO (Weak v)
        deRefWeak,              -- :: Weak v -> IO (Maybe v)
        finalise,               -- :: Weak v -> IO ()

        -- Not yet implemented
        -- replaceFinaliser     -- :: Weak v -> IO () -> IO ()

        mkWeakPtr,              -- :: k -> IO () -> IO (Weak k)
        mkWeakPair,             -- :: k -> v -> IO () -> IO (Weak (k,v))
        mkWeakNoFinaliser,      -- :: k -> v -> IO (Weak v)
        addFinaliser,           -- :: k -> IO () -> IO ()
        addForeignFinaliser     -- :: ForeignObj -> IO () -> IO ()
   ) where

16.2 Weak pointers

In general terms, a weak pointer is a reference to an object that is not followed by the garbage collector --- that is, the existence of a weak pointer to an object has no effect on the lifetime of that object. A weak pointer can be de-referenced to find out whether the object it refers to is still alive or not, and if so to return the object itself.

Weak pointers are particularly useful for caches and memo tables. To build a memo table, you build a data structure mapping from the function argument (the key) to its result (the value). When you apply the function to a new argument you first check whether the key/value pair is already in the memo table. The key point is that the memo table itself should not keep the key and value alive. So the table should contain a weak pointer to the key, not an ordinary pointer. The pointer to the value must not be weak, because the only reference to the value might indeed be from the memo table.

So it looks as if the memo table will keep all its values alive for ever. One way to solve this is to purge the table occasionally, by deleting entries whose keys have died.

The weak pointers in this library support another approach, called finalisation. When the key referred to by a weak pointer dies, the storage manager arranges to run a programmer-specified finaliser. In the case of memo tables, for example, the finaliser could remove the key/value pair from the memo table.

Another difficulty with the memo table is that the value of a key/value pair might itself contain a pointer to the key. So the memo table keeps the value alive, which keeps the key alive, even though there may be no other references to the key so both should die. The weak pointers in this library provide a slight generalisation of the basic weak-pointer idea, in which each weak pointer actually contains both a key and a value. We describe this in more detail below.

16.3 The simple interface

        mkWeakPtr    :: a -> IO () -> IO (Weak a)
        deRefWeak    :: Weak a -> IO (Maybe a)
        addFinaliser :: a -> IO () -> IO ()

mkWeakPtr takes a value of any type a, and a finaliser of type IO (), and returns a weak pointer object referring to the value, of type Weak a. It is in the IO monad because it has the side effect of arranging that the finaliser will be run when the object dies. In what follows, a ``weak pointer object'', or ``weak pointer'' for short, means precisely ``a Haskell value of type Weak t'' for some type t. A weak pointer (object) is a first-class Haskell value; it can be passed to functions, stored in data structures, and so on.

deRefWeak dereferences a weak pointer, returning Just v if the value is still alive. If the key has already died, then deRefWeak returns Nothing; that's why it's in the IO monad - the return value of deRefWeak depends on when the garbage collector runs.

addFinaliser is just another name for mkWeakPtr except that it throws the weak pointer itself away. (The runtime system will remember that the weak pointer and hence the finaliser exists even if the program has forgotten it.)

  addFinaliser :: a -> IO () -> IO ()
  addFinaliser v f = do { mkWeakPtr v f; return () }

The effect of addFinaliser is simply that the finaliser runs when the referenced object dies.

The following properties hold:

• deRefWeak returns the original object until that object is considered dead; it returns Nothing subsequently.
• Every finaliser will eventually be run, exactly once, either soon after the object dies, or at the end of the program. There is no requirement for the programmer to hold onto the weak pointer itself; finalisation is completely unaffected by whether the weak pointer itself is alive.
• There may be multiple weak pointers to a single object. In this case, the finalisers for each of these weak pointers will all be run in some arbitrary order, or perhaps concurrently, when the object dies. If the programmer specifies a finaliser that assumes it has the only reference to an object (for example, a file that it wishes to close), then the programmer must ensure that there is only one such finaliser.
• The storage manager attempts to run the finaliser(s) for an object soon after the object dies, but promptness is not guaranteed. (What is guaranteed is that the finaliser will eventually run, exactly once.)
• At the moment when a finaliser is run, a call to deRefWeak will return Nothing.
• A finaliser may contain a pointer to the object, but that pointer will not keep the object alive. For example:

    f :: Show a => a -> IO a
    f x = addFinaliser x (print (show x))
  

  Here the finaliser print (show x) contains a reference to x itself, but that does not keep x alive. When that is the only reference to x, the finaliser is run; and the message appears on the screen.
• A finaliser may even resurrect the object, by (say) storing it in some global data structure.

16.4 The general interface

The Weak library offers a slight generalisation of the simple weak pointers described so far:

        mkWeak :: k -> v -> IO () -> IO (Weak v)

deRefWeak returns the value only, not the key, as its type (given above) implies:

        deRefWeak :: Weak a -> IO (Maybe a)

Simple weak pointers are readily defined in terms of these more general weak pointers:

  mkWeakPtr :: a -> IO () -> IO (Weak a)
  mkWeakPtr v f = mkWeak v v f

These more general weak pointers are enough to implement memo tables properly.

A weak pointer can be finalised early, using the finalise operation:

finalise :: Weak v -> IO ()

When you don't need a finaliser, we provide the following operation:

mkWeakNoFinaliser :: k -> v -> IO (Weak v)
mkWeakNoFinaliser k v = mkWeak k v (return ())

Which creates a weak pointer with a null finaliser. Lots of null finalisers can be expensive, because each one runs in a separate thread, so the intention is that mkWeakNoFinaliser> avoids all the extra costs by generating a special kind of weak pointer without a finaliser. So although the semantics of mkWeakNoFinaliser is as given above, its actual implementation is somewhat different.

16.5 A precise semantics

To avoid this somewhat subtle race condition, we use another type of foreign address, called ForeignObj (see Section Foreign). Historical note: ForeignObj is identical to the old ForeignObj except that it no longer supports finalisation - that's provided by the weak pointer finalisation mechanism above.

A ForeignObj is basically an address, but the ForeignObj itself is a heap-resident object and can therefore be watched by weak pointers. A ForeignObj can be passed to C functions (in which case the C function gets a straightforward pointer), but it cannot be decomposed into an Addr#.