-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Heterogeneous maps keyed by StableNames
--
-- Provides an API for inserting heterogeneous data in a collection keyed
-- by StableNames and for later retrieving it.
@package stable-maps
@version 0.0.1
-- | Dynamic stable names are a way of performing fast (O(1)),
-- not-quite-exact comparison between objects.
--
-- Dynamic stable names solve the following problem: suppose you want to
-- build a hash table with Haskell objects as keys, but you want to use
-- pointer equality for comparison; maybe because the keys are large and
-- hashing would be slow, or perhaps because the keys are infinite in
-- size. We can't build a hash table using the address of the object as
-- the key, because objects get moved around by the garbage collector,
-- meaning a re-hash would be necessary after every garbage collection.
module System.Mem.StableName.Dynamic
-- | An abstract name for an object, that supports equality and hashing.
--
-- Dynamic stable names have the following property:
--
--
-- - If sn1 :: DynamicStableName and sn2 ::
-- DynamicStableName and sn1 == sn2 then sn1 and
-- sn2 were created by calls to makeStableName on the
-- same object.
--
--
-- The reverse is not necessarily true: if two dynamic stable names are
-- not equal, then the objects they name may still be equal. Note in
-- particular that makeDynamicStableName may return a different
-- DynamicStableName after an object is evaluated.
--
-- Dynamic Stable Names are similar to Stable Pointers
-- (Foreign.StablePtr), but differ in the following ways:
--
--
-- - There is no freeDynamicStableName operation, unlike
-- Foreign.StablePtrs. Dynamic Stable Names are reclaimed by the
-- runtime system when they are no longer needed.
-- - There is no deRefDynamicStableName operation. You can't
-- get back from a dynamic stable name to the original Haskell object.
-- The reason for this is that the existence of a stable name for an
-- object does not guarantee the existence of the object itself; it can
-- still be garbage collected.
--
newtype DynamicStableName
DynamicStableName :: (StableName Any) -> DynamicStableName
-- | Convert a DynamicStableName to an Int. The Int
-- returned is not necessarily unique; several DynamicStableNames
-- may map to the same Int (in practice however, the chances of
-- this are small, so the result of hashDynamicStableName makes a
-- good hash key).
hashDynamicStableName :: DynamicStableName -> Int
-- | Makes a DynamicStableName for an arbitrary object. The object
-- passed as the first argument is not evaluated by
-- makeDynamicStableName.
makeDynamicStableName :: t -> IO DynamicStableName
wrapStableName :: StableName a -> DynamicStableName
instance Eq DynamicStableName
module System.Mem.StableName.Dynamic.Map
data Map a
empty :: Map a
null :: Map a -> Bool
singleton :: DynamicStableName -> a -> Map a
member :: DynamicStableName -> Map a -> Bool
notMember :: DynamicStableName -> Map a -> Bool
insert :: DynamicStableName -> a -> Map a -> Map a
-- | O(log n). Insert with a function for combining the new value
-- and old value. insertWith f key value mp will insert
-- the pair (key, value) into mp if the key does not exist in
-- the map. If the key does exist, the function will insert the pair
-- (key, f new_value old_value)
insertWith :: (a -> a -> a) -> DynamicStableName -> a -> Map a -> Map a
module System.Mem.StableName.Map
empty :: Map f
null :: Map f -> Bool
singleton :: StableName a -> f a -> Map f
member :: StableName a -> Map f -> Bool
notMember :: StableName a -> Map f -> Bool
insert :: StableName a -> f a -> Map f -> Map f
-- | O(log n). Insert with a function for combining the new value
-- and old value. insertWith f key value mp will insert
-- the pair (key, value) into mp if the key does not exist in
-- the map. If the key does exist, the function will insert the pair
-- (key, f new_value old_value)
insertWith :: (f a -> f a -> f a) -> StableName a -> f a -> Map f -> Map f
-- | Same as insertWith, but with the combining function applied
-- strictly.
insertWith' :: (f a -> f a -> f a) -> StableName a -> f a -> Map f -> Map f
adjust :: (f a -> f a) -> StableName a -> Map f -> Map f
-- | O(log n). Lookup the value at a key in the map.
--
-- The function will return the corresponding value as a (Just
-- value) or Nothing if the key isn't in the map.
lookup :: StableName a -> Map f -> Maybe (f a)
find :: StableName a -> Map f -> f a
-- | O(log n). The expression (findWithDefault def k
-- map) returns the value at key k or returns the default
-- value def when the key is not in the map.
findWithDefault :: f a -> StableName a -> Map f -> f a