Data.WeakBag

This module defines the WeakBag type, which represents a mutable collection of items that does not cause the items to be retained in memory. This is useful for situations where a value needs to be inspected or modified if it is still alive, but can be ignored if it is dead.

Documentation

data WeakBag a

A WeakBag holds a set of values of type a, but does not retain them - that is, they can still be garbage-collected. As long as the a values remain alive, the WeakBag will continue to refer to them.

data WeakBagTicket

When inserting an item into a WeakBag, a WeakBagTicket is returned. If the caller retains the ticket, the item is guranteed to stay in memory (and thus in the WeakBag). The ticket can also be used to remove the item from the WeakBag prematurely (i.e. while it is still alive), using remove.

empty :: IO (WeakBag a)

Create an empty WeakBag.

singleton :: a -> IORef (Weak b) -> (b -> IO ()) -> IO (WeakBag a, WeakBagTicket)

Create a WeakBag with one item; equivalent to creating the WeakBag with empty, then using insert.

insert

Arguments

:: a

The item

-> WeakBag a

The WeakBag to insert into

-> IORef (Weak b)

An arbitrary value to be used in the following callback

-> (b -> IO ())

A callback to be invoked when the item is removed (whether automatically by the item being garbage collected or manually via remove)

-> IO WeakBagTicket

Returns a WeakBagTicket that ensures the item is retained and allows the item to be removed.

Insert an item into a WeakBag.

traverse :: MonadIO m => WeakBag a -> (a -> m ()) -> m ()

Visit every node in the given list. If new nodes are appended during the traversal, they will not be visited. Every live node that was in the list when the traversal began will be visited exactly once; however, no guarantee is made about the order of the traversal.

remove :: WeakBagTicket -> IO ()

Remove an item from the WeakBag; does nothing if invoked multiple times on the same WeakBagTicket.

Internal functions

_weakBag_children :: WeakBag a -> IORef (IntMap (Weak a))

The items referenced by the WeakBag