HORIZON HASKELLDocslts/ghc-9.10.x248f8f02026-10-05Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · 248f8f0 · 2026-10-05

Modulelinear-base-0.4.0Haskell2010

Foreign.Marshal.Pure

This module introduces primitives to safely allocate and discard system heap memory (not GC heap memory) for storing values explicitly. (Basically, a haskell program has a GC that at runtime, manages its own heap by freeing and allocating space from the system heap.) Values discarded explicitly don't need to be managed by the garbage collector (GC), which therefore has less work to do. Less work for the GC can sometimes mean more predictable request latencies in multi-threaded and distributed applications.

This module is meant to be imported qualified.

The Interface

Run a computation that uses heap memory by passing a continuation to withPool of type Pool %1-> Ur b. Allocate and free with alloc and deconstruct. Make as many or as few pools you need, by using the Dupable and Consumable instances of Pool.

A toy example:

Example5 expressions
:set -XLinearTypesimport Preludeimport Data.Unrestricted.Linearimport qualified Foreign.Marshal.Pure as Manual:{  nothingWith3 :: Pool %1-> Ur Int  nothingWith3 pool = move (Manual.deconstruct (Manual.alloc 3 pool)):}
Example1 expression
unur (Manual.withPool nothingWith3)3
What are Pools?

Pools are memory pools from which a user can safely allocate and use heap memory manually by passing withPool a continuation. An alternative design would have allowed passing continuations to allocation functions but this could break tail-recursion in certain cases.

Pools play another role: resilience to exceptions. If an exception is raised, all the data in the pool is deallocated.

Note that data from one pool can refer to data in another pool and vice versa.

Large Examples

You can find example data structure implementations in Foreign.List and Foreign.Heap here.

  • 2 types
  • 3 classes
  • 3 values

Allocating and using values on the heap

5 declarations
datadata Pool where
#

Pools represent collections of values. A Pool can be consume-ed. This is a no-op: it does not deallocate the data in that pool. It cannot do so, because accessible values might still exist. Consuming a pool simply makes it impossible to add new data to the pool.

Instances2Consumable, Dupable
  • Consumable PoolDefined in linear-base-0.4.0 · Foreign.Marshal.Pure.Internal
  • Dupable PoolDefined in linear-base-0.4.0 · Foreign.Marshal.Pure.Internal
valuewithPool :: (Pool %1 -> Ur b) %1 -> Ur b
#

Given a linear computation that manages memory, run that computation.

datadata Box a where
#

'Box a' is the abstract type of manually managed data. It can be used as part of data type definitions in order to store linked data structure off heap. See Foreign.List and Foreign.Pair in the examples directory of the source repository.

Instances4Storable, KnownRepresentable, Representable, AsKnown
  • Storable (Box a)Defined in linear-base-0.4.0 · Foreign.Marshal.Pure.Internal
  • KnownRepresentable (Box a)Defined in linear-base-0.4.0 · Foreign.Marshal.Pure.Internal
  • Representable (Box a)Defined in linear-base-0.4.0 · Foreign.Marshal.Pure.Internal
  • type AsKnown (Box a) = Box aDefined in linear-base-0.4.0 · Foreign.Marshal.Pure.Internal

Typeclasses for values that can be allocated

3 declarations
classclass KnownRepresentable a where
#

This abstract type class represents values natively known to have a GC-less implementation. Basically, these are sequences (represented as tuples) of base types.

Instances9KnownRepresentable, …
classclass KnownRepresentable (AsKnown a) => Representable a where
#

Laws of Representable:

  • toKnown must be total

  • ofKnown may be partial, but must be total on the image of toKnown

  • ofKnown . toKnown == id

Associated types

Methods

Instances8Representable, …
classclass Representable b => MkRepresentable a b | a -> b where
#

This is an easier way to create an instance of Representable. It is a bit abusive to use a type class for this (after all, it almost never makes sense to use this as a constraint). But it works in practice.

To use, define an instance of MkRepresentable myType intermediateType then declare the following instance:

instance Representable myType where {type AsKnown = AsKnown intermediateType}

And the default instance mechanism will create the appropriate Representable instance.

Laws of MkRepresentable:

  • toRepr must be total

  • ofRepr may be partial, but must be total on the image of toRepr

  • ofRepr . toRepr = id

Methods