GHC.Internal.StaticPtr

ghc-internal-9.1001.0: Basic libraries

Copyright | (C) 2014 I/O Tweag
License | see libraries/base/LICENSE
Maintainer | ghc-devs@haskell.org
Stability | internal
Portability | non-portable (GHC Extensions)
Safe Haskell | None
Language | Haskell2010

GHC.Internal.StaticPtr

Description

Symbolic references to values.

References to values are usually implemented with memory addresses, and this is practical when communicating values between the different pieces of a single process.

When values are communicated across different processes running in possibly different machines, though, addresses are no longer useful since each process may use different addresses to store a given value.

To solve such concern, the references provided by this module offer a key that can be used to locate the values on each process. Each process maintains a global table of references which can be looked up with a given key. This table is known as the Static Pointer Table. The reference can then be dereferenced to obtain the value.

The various communicating processes need to agree on the keys used to refer to the values in the Static Pointer Table, or lookups will fail. Only processes launched from the same program binary are guaranteed to use the same set of keys.

Synopsis

- data StaticPtr a
- deRefStaticPtr :: StaticPtr a -> a
- type StaticKey = Fingerprint
- staticKey :: StaticPtr a -> StaticKey
- unsafeLookupStaticPtr :: StaticKey -> IO (Maybe (StaticPtr a))
- data StaticPtrInfo = StaticPtrInfo {
  - spInfoUnitId :: String
  - spInfoModuleName :: String
  - spInfoSrcLoc :: (Int, Int)
  }
- staticPtrInfo :: StaticPtr a -> StaticPtrInfo
- staticPtrKeys :: IO [StaticKey]
- class IsStatic (p :: Type -> Type) where
  - fromStaticPtr :: Typeable a => StaticPtr a -> p a

# Documentation

data StaticPtr a Source #

A reference to a value of type `a`.

#### Instances

Instances details

IsStatic StaticPtr Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.StaticPtr Methods fromStaticPtr :: Typeable a => StaticPtr a -> StaticPtr a Source #

deRefStaticPtr :: StaticPtr a -> a Source #

Dereferences a static pointer.

type StaticKey = Fingerprint Source #

A key for `StaticPtr`s that can be serialized and used with `unsafeLookupStaticPtr`.

staticKey :: StaticPtr a -> StaticKey Source #

The `StaticKey` that can be used to look up the given `StaticPtr`.

unsafeLookupStaticPtr :: StaticKey -> IO (Maybe (StaticPtr a)) Source #

Looks up a `StaticPtr` by its `StaticKey`.

If the `StaticPtr` is not found returns `Nothing`.

This function is unsafe because the program behavior is undefined if the type of the returned `StaticPtr` does not match the expected one.

data StaticPtrInfo Source #

Miscellaneous information available for debugging purposes.

Constructors

StaticPtrInfo |
Fields spInfoUnitId :: String Package key of the package where the static pointer is defined spInfoModuleName :: String Name of the module where the static pointer is defined spInfoSrcLoc :: (Int, Int) Source location of the definition of the static pointer as a `(Line, Column)` pair.

#### Instances

Instances details

Show StaticPtrInfo Source # | @since base-4.8.0.0
Instance details Defined in GHC.Internal.StaticPtr Methods showsPrec :: Int -> StaticPtrInfo -> ShowS Source # show :: StaticPtrInfo -> String Source # showList :: [StaticPtrInfo] -> ShowS Source #

staticPtrInfo :: StaticPtr a -> StaticPtrInfo Source #

`StaticPtrInfo` of the given `StaticPtr`.

staticPtrKeys :: IO [StaticKey] Source #

A list of all known keys.

class IsStatic (p :: Type -> Type) where Source #

A class for things buildable from static pointers.

GHC wraps each use of the `static` keyword with `fromStaticPtr`. Because the `static` keyword requires its argument to be an instance of `Typeable`, `fromStaticPtr` carries a `Typeable` constraint as well.

Methods

fromStaticPtr :: Typeable a => StaticPtr a -> p a Source #

#### Instances

Instances details

IsStatic StaticPtr Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.StaticPtr Methods fromStaticPtr :: Typeable a => StaticPtr a -> StaticPtr a Source #