Data.Mutable

There is a common pattern in Haskell libraries that work with mutable data:

• Two types, a mutable and an immutable variant of the same structure.
• thaw and freeze functions to convert between these.
• Sometimes unsafe variants of thaw and freeze, which avoid a copy but can break referential transparency if misused.

This module abstracts out the above pattern into a generic type family Thaw, and provides some of the common higher-level tools built on top of these primitives.

Note that there's nothing terribly Cap'N Proto specific about this module; we may even factor it out into a separate package at some point.

Documentation

class Thaw a where

The Thaw type class relates mutable and immutable versions of a type. The instance is defined on the immutable variant; Mutable s a is the mutable version of an immutable type a, bound to the state token s.

Minimal complete definition

thaw, freeze

Associated Types

type Mutable s a

The mutable version of a, bound to the state token s.

Methods

thaw :: (PrimMonad m, PrimState m ~ s) => a -> m (Mutable s a)

Convert an immutable value to a mutable one.

freeze :: (PrimMonad m, PrimState m ~ s) => Mutable s a -> m a

Convert a mutable value to an immutable one.

unsafeThaw :: (PrimMonad m, PrimState m ~ s) => a -> m (Mutable s a)

Like thaw, except that the caller is responsible for ensuring that the original value is not subsequently used; doing so may violate referential transparency.

The default implementation of this is just the same as thaw, but typically an instance will override this with a trivial (unsafe) cast, hence the obligation described above.

unsafeFreeze :: (PrimMonad m, PrimState m ~ s) => Mutable s a -> m a

Unsafe version of freeze analagous to unsafeThaw. The caller must ensure that the original value is not used after this call.

Instances

Thaw ConstMsg

Defined in Data.Capnp.Message

Associated Types

type Mutable s ConstMsg :: *

Methods

thaw :: (PrimMonad m, PrimState m ~ s) => ConstMsg -> m (Mutable s ConstMsg)

freeze :: (PrimMonad m, PrimState m ~ s) => Mutable s ConstMsg -> m ConstMsg

unsafeThaw :: (PrimMonad m, PrimState m ~ s) => ConstMsg -> m (Mutable s ConstMsg)

unsafeFreeze :: (PrimMonad m, PrimState m ~ s) => Mutable s ConstMsg -> m ConstMsg

Thaw (Segment ConstMsg)

Defined in Data.Capnp.Message

Associated Types

type Mutable s (Segment ConstMsg) :: *

Methods

thaw :: (PrimMonad m, PrimState m ~ s) => Segment ConstMsg -> m (Mutable s (Segment ConstMsg))

freeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (Segment ConstMsg) -> m (Segment ConstMsg)

unsafeThaw :: (PrimMonad m, PrimState m ~ s) => Segment ConstMsg -> m (Mutable s (Segment ConstMsg))

unsafeFreeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (Segment ConstMsg) -> m (Segment ConstMsg)

Thaw msg => Thaw (Struct msg)

Defined in Data.Capnp.Untyped

Associated Types

type Mutable s (Struct msg) :: *

Methods

thaw :: (PrimMonad m, PrimState m ~ s) => Struct msg -> m (Mutable s (Struct msg))

freeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (Struct msg) -> m (Struct msg)

unsafeThaw :: (PrimMonad m, PrimState m ~ s) => Struct msg -> m (Mutable s (Struct msg))

unsafeFreeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (Struct msg) -> m (Struct msg)

Thaw msg => Thaw (List msg)

Defined in Data.Capnp.Untyped

Associated Types

type Mutable s (List msg) :: *

Methods

thaw :: (PrimMonad m, PrimState m ~ s) => List msg -> m (Mutable s (List msg))

freeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (List msg) -> m (List msg)

unsafeThaw :: (PrimMonad m, PrimState m ~ s) => List msg -> m (Mutable s (List msg))

unsafeFreeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (List msg) -> m (List msg)

Thaw msg => Thaw (Ptr msg)

Defined in Data.Capnp.Untyped

Associated Types

type Mutable s (Ptr msg) :: *

Methods

thaw :: (PrimMonad m, PrimState m ~ s) => Ptr msg -> m (Mutable s (Ptr msg))

freeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (Ptr msg) -> m (Ptr msg)

unsafeThaw :: (PrimMonad m, PrimState m ~ s) => Ptr msg -> m (Mutable s (Ptr msg))

unsafeFreeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (Ptr msg) -> m (Ptr msg)

Thaw msg => Thaw (ListOf msg (Maybe (Ptr msg)))

Defined in Data.Capnp.Untyped

Associated Types

type Mutable s (ListOf msg (Maybe (Ptr msg))) :: *

Methods

thaw :: (PrimMonad m, PrimState m ~ s) => ListOf msg (Maybe (Ptr msg)) -> m (Mutable s (ListOf msg (Maybe (Ptr msg))))

freeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (ListOf msg (Maybe (Ptr msg))) -> m (ListOf msg (Maybe (Ptr msg)))

unsafeThaw :: (PrimMonad m, PrimState m ~ s) => ListOf msg (Maybe (Ptr msg)) -> m (Mutable s (ListOf msg (Maybe (Ptr msg))))

unsafeFreeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (ListOf msg (Maybe (Ptr msg))) -> m (ListOf msg (Maybe (Ptr msg)))

Thaw msg => Thaw (ListOf msg (Struct msg))

Defined in Data.Capnp.Untyped

Associated Types

type Mutable s (ListOf msg (Struct msg)) :: *

Methods

thaw :: (PrimMonad m, PrimState m ~ s) => ListOf msg (Struct msg) -> m (Mutable s (ListOf msg (Struct msg)))

freeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (ListOf msg (Struct msg)) -> m (ListOf msg (Struct msg))

unsafeThaw :: (PrimMonad m, PrimState m ~ s) => ListOf msg (Struct msg) -> m (Mutable s (ListOf msg (Struct msg)))

unsafeFreeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (ListOf msg (Struct msg)) -> m (ListOf msg (Struct msg))

Thaw msg => Thaw (ListOf msg Word64)

Defined in Data.Capnp.Untyped

Associated Types

type Mutable s (ListOf msg Word64) :: *

Methods

thaw :: (PrimMonad m, PrimState m ~ s) => ListOf msg Word64 -> m (Mutable s (ListOf msg Word64))

freeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (ListOf msg Word64) -> m (ListOf msg Word64)

unsafeThaw :: (PrimMonad m, PrimState m ~ s) => ListOf msg Word64 -> m (Mutable s (ListOf msg Word64))

unsafeFreeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (ListOf msg Word64) -> m (ListOf msg Word64)

Thaw msg => Thaw (ListOf msg Word32)

Defined in Data.Capnp.Untyped

Associated Types

type Mutable s (ListOf msg Word32) :: *

Methods

thaw :: (PrimMonad m, PrimState m ~ s) => ListOf msg Word32 -> m (Mutable s (ListOf msg Word32))

freeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (ListOf msg Word32) -> m (ListOf msg Word32)

unsafeThaw :: (PrimMonad m, PrimState m ~ s) => ListOf msg Word32 -> m (Mutable s (ListOf msg Word32))

unsafeFreeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (ListOf msg Word32) -> m (ListOf msg Word32)

Thaw msg => Thaw (ListOf msg Word16)

Defined in Data.Capnp.Untyped

Associated Types

type Mutable s (ListOf msg Word16) :: *

Methods

thaw :: (PrimMonad m, PrimState m ~ s) => ListOf msg Word16 -> m (Mutable s (ListOf msg Word16))

freeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (ListOf msg Word16) -> m (ListOf msg Word16)

unsafeThaw :: (PrimMonad m, PrimState m ~ s) => ListOf msg Word16 -> m (Mutable s (ListOf msg Word16))

unsafeFreeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (ListOf msg Word16) -> m (ListOf msg Word16)

Thaw msg => Thaw (ListOf msg Word8)

Defined in Data.Capnp.Untyped

Associated Types

type Mutable s (ListOf msg Word8) :: *

Methods

thaw :: (PrimMonad m, PrimState m ~ s) => ListOf msg Word8 -> m (Mutable s (ListOf msg Word8))

freeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (ListOf msg Word8) -> m (ListOf msg Word8)

unsafeThaw :: (PrimMonad m, PrimState m ~ s) => ListOf msg Word8 -> m (Mutable s (ListOf msg Word8))

unsafeFreeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (ListOf msg Word8) -> m (ListOf msg Word8)

Thaw msg => Thaw (ListOf msg Bool)

Defined in Data.Capnp.Untyped

Associated Types

type Mutable s (ListOf msg Bool) :: *

Methods

thaw :: (PrimMonad m, PrimState m ~ s) => ListOf msg Bool -> m (Mutable s (ListOf msg Bool))

freeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (ListOf msg Bool) -> m (ListOf msg Bool)

unsafeThaw :: (PrimMonad m, PrimState m ~ s) => ListOf msg Bool -> m (Mutable s (ListOf msg Bool))

unsafeFreeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (ListOf msg Bool) -> m (ListOf msg Bool)

Thaw msg => Thaw (ListOf msg ())

Defined in Data.Capnp.Untyped

Associated Types

type Mutable s (ListOf msg ()) :: *

Methods

thaw :: (PrimMonad m, PrimState m ~ s) => ListOf msg () -> m (Mutable s (ListOf msg ()))

freeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (ListOf msg ()) -> m (ListOf msg ())

unsafeThaw :: (PrimMonad m, PrimState m ~ s) => ListOf msg () -> m (Mutable s (ListOf msg ()))

unsafeFreeze :: (PrimMonad m, PrimState m ~ s) => Mutable s (ListOf msg ()) -> m (ListOf msg ())

create :: Thaw a => (forall s. ST s (Mutable s a)) -> a

Create and freeze a mutable value, safely, without doing a full copy. internally, create calls unsafeFreeze, but it cannot be directly used to violate referential transparency, as the value is not available to the caller after freezing.

createT :: (Traversable f, Thaw a) => (forall s. ST s (f (Mutable s a))) -> f a

Like create, but the result is wrapped in an instance of Traversable.