base-4.7.0.0: Basic libraries

Copyright(c) The University of Glasgow 2001
LicenseBSD-style (see the file libraries/base/LICENSE)
Maintainerlibraries@haskell.org
Stabilityexperimental
Portabilitynon-portable
Safe HaskellTrustworthy
LanguageHaskell2010

System.Mem.StableName

Contents

Description

Stable names are a way of performing fast (O(1)), not-quite-exact comparison between objects.

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.

Synopsis

Stable Names

data StableName aSource

An abstract name for an object, that supports equality and hashing.

Stable names have the following property:

  • If sn1 :: StableName and sn2 :: StableName 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 stable names are not equal, then the objects they name may still be equal. Note in particular that mkStableName may return a different StableName after an object is evaluated.

Stable Names are similar to Stable Pointers (Foreign.StablePtr), but differ in the following ways:

  • There is no freeStableName operation, unlike Foreign.StablePtrs. Stable names are reclaimed by the runtime system when they are no longer needed.
  • There is no deRefStableName operation. You can't get back from a 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.

Instances

makeStableName :: a -> IO (StableName a)Source

Makes a StableName for an arbitrary object. The object passed as the first argument is not evaluated by makeStableName.

hashStableName :: StableName a -> IntSource

Convert a StableName to an Int. The Int returned is not necessarily unique; several StableNames may map to the same Int (in practice however, the chances of this are small, so the result of hashStableName makes a good hash key).

eqStableName :: StableName a -> StableName b -> BoolSource

Equality on StableName that does not require that the types of the arguments match.

Since: 4.7.0.0