base-4.14.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 HaskellSafe
LanguageHaskell2010

System.Mem.StableName

Contents

Description

Stable names are a way of performing fast ( \(\mathcal{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 a Source #

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 makeStableName 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

Instances details
Eq (StableName a) Source #

Since: 2.1

Instance details

Defined in GHC.StableName

Methods

(==) :: StableName a -> StableName a -> Bool #

(/=) :: StableName a -> StableName a -> Bool #

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 -> Int Source #

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 -> Bool Source #

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

Since: 4.7.0.0