SubHask.Mutable

In the SubHask library, every type has both a mutable and immutable version. Normally we work with the immutable version; however, certain algorithms require the mutable version for efficiency. This module defines the interface to the mutable types.

Documentation

data family Mutable m a

The mutable version of an immutable data type. This is equivalent to the PrimRef type, which generalizes STRef and IORef.

Unlike PrimRef, Mutable is implemented using a data family. This means that data types can provide more efficient implementations. The canonical example is Vector. Vectors in standard Haskell use a different interface than the standard PrimRef. This requires the programmer learn multiple interfaces, and prevents the programmer from reusing code. Very un-Haskelly. This implementation of mutability gives a consistent interface for all data types.

Instances

(Show a, IsMutable a, PrimBase m) => Show (Mutable m a)

(IsMutable a, PrimBase m, Arbitrary a) => Arbitrary (Mutable m a)

data Mutable m Int = Mutable_ConT_GHC_Types_Int (PrimRef m Int)

data Mutable m Integer = Mutable_ConT_GHC_Integer_Type_Integer (PrimRef m Integer)

data Mutable m Rational = Mutable_ConT_GHC_Real_Rational (PrimRef m Rational)

data Mutable m Float = Mutable_ConT_GHC_Types_Float (PrimRef m Float)

data Mutable m Double = Mutable_ConT_GHC_Types_Double (PrimRef m Double)

data Mutable m Bool = Mutable_ConT_GHC_Types_Bool (PrimRef m Bool)

data Mutable m () = Mutable_TupleT_0 (PrimRef m ())

data Mutable m POrdering = Mutable_ConT_SubHask_Algebra_POrdering (PrimRef m POrdering)

data Mutable m Ordering = Mutable_ConT_GHC_Types_Ordering (PrimRef m Ordering)

data Mutable m [a0] = Mutable_AppT_ListT__VarT_a_1627457055_ (PrimRef m [a])

data Mutable m (Maybe a0) = Mutable_AppT__ConT_GHC_Base_Maybe___VarT_a_1627508821_ (PrimRef m (Maybe a))

data Mutable m (Maybe' a0) = Mutable_AppT__ConT_SubHask_Algebra_Maybe'___VarT_a_1627508936_ (PrimRef m (Maybe' a))

data Mutable m (WithPreludeOrd a0) = Mutable_WithPreludeOrd (Mutable m a)

data Mutable m (NonNegative t0) = Mutable_NonNegative (Mutable m t)

data Mutable m (VedicSquare n0) = Mutable_VedicSquare (Mutable m (Z n))

data Mutable m (Ball b0) = Mutable_AppT__ConT_SubHask_Algebra_Metric_Ball___VarT_b_1627656400_ (PrimRef m (Ball b))

data Mutable m (ZIndex a0) = Mutable_ZIndex (Mutable m (Z (Order a)))

data Mutable m (IO a0) = Mutable_AppT__ConT_GHC_Types_IO___VarT_a_1627710632_ (PrimRef m (IO a))

data Mutable m (BArray e0) = Mutable_AppT__ConT_SubHask_Algebra_Array_BArray___VarT_e_1627972045_ (PrimRef m (BArray e))

data Mutable m (UArray e0) = Mutable_AppT__ConT_SubHask_Algebra_Array_UArray___VarT_e_1627973270_ (PrimRef m (UArray e))

data Mutable m (Forward a0) = Mutable_AppT__ConT_SubHask_Category_Trans_Derivative_Forward___VarT_a_1628012176_ (PrimRef m (Forward a))

data Mutable m (Box v0) = Mutable_AppT__ConT_SubHask_Algebra_Container_Box___VarT_v_1628020028_ (PrimRef m (Box v))

data Mutable m (Jaccard a0) = Mutable_Jaccard (Mutable m a)

data Mutable m (Hamming a0) = Mutable_Hamming (Mutable m a)

data Mutable m (Levenshtein a0) = Mutable_Levenshtein (Mutable m a)

data Mutable m (Uncompensated s0) = Mutable_Uncompensated (Mutable m s)

data Mutable m (Lexical a0) = Mutable_Lexical (Mutable m a)

data Mutable m (ComponentWise a0) = Mutable_ComponentWise (Mutable m a)

data Mutable m (Goedel_ r0) = Mutable_Goedel_ (Mutable m r)

data Mutable m (Boolean2Ring b0) = Mutable_Boolean2Ring (Mutable m b)

data Mutable m (Seq a0) = Mutable_AppT__ConT_SubHask_Compatibility_Containers_Seq___VarT_a_1628103216_ (PrimRef m (Seq a))

data Mutable m (IntMap a0) = Mutable_AppT__ConT_SubHask_Compatibility_Containers_IntMap___VarT_a_1628106664_ (PrimRef m (IntMap a))

data Mutable m (IntMap' a0) = Mutable_AppT__ConT_SubHask_Compatibility_Containers_IntMap'___VarT_a_1628107561_ (PrimRef m (IntMap' a))

data Mutable m (Set a0) = Mutable_AppT__ConT_SubHask_Compatibility_Containers_Set___VarT_a_1628108370_ (PrimRef m (Set a))

data Mutable m (LexSet a0) = Mutable_AppT__ConT_SubHask_Compatibility_Containers_LexSet___VarT_a_1628109321_ (PrimRef m (LexSet a))

data Mutable m (ByteString a0) = Mutable_AppT__ConT_SubHask_Compatibility_ByteString_ByteString___VarT_a_1628156234_ (PrimRef m (ByteString a))

data Mutable m (PartitionOnNewline a0) = Mutable_PartitionOnNewline (Mutable m a)

data Mutable m (a0, b0) = Mutable_AppT__AppT__TupleT_2___VarT_a_1627457252____VarT_b_1627457253_ (PrimRef m (a, b))

data Mutable m (a0 -> b0) = Mutable_AppT__AppT_ArrowT__VarT_a_1627457532____VarT_b_1627457533_ (PrimRef m (a -> b))

data Mutable m (Any cxt0 x0) = Mutable_AppT__AppT__ConT_SubHask_Algebra_Any___VarT_cxt_1627508297____VarT_x_1627508298_ (PrimRef m (Any cxt x))

data Mutable m (Labeled' a0 b0) = Mutable_AppT__AppT__ConT_SubHask_Algebra_Labeled'___VarT_a_1627509060____VarT_b_1627509061_ (PrimRef m (Labeled' a b))

data Mutable m (Galois p0 k0) = Mutable_Galois (Mutable m (Z ((^) p k)))

data Mutable m (Polynomial_ a0 b0) = Mutable_AppT__AppT__ConT_SubHask_Category_Polynomial_Polynomial____VarT_a_1627677154____VarT_b_1627677155_ (PrimRef m (Polynomial_ a b))

data Mutable m (Either a0 b0) = Mutable_AppT__AppT__ConT_Data_Either_Either___VarT_a_1627710905____VarT_b_1627710906_ (PrimRef m (Either a b))

data Mutable m ((+>) a0 b0) = Mutable_AppT__AppT__ConT_SubHask_Algebra_Vector______VarT_a_1627758364____VarT_b_1627758365_ (PrimRef m ((+>) a b))

data Mutable m (BloomFilter n0 a0) = Mutable_AppT__AppT__ConT_SubHask_Compatibility_BloomFilter_BloomFilter___VarT_n_1628101621____VarT_a_1628101622_ (PrimRef m (BloomFilter n a))

data Mutable m (Map i0 e0) = Mutable_AppT__AppT__ConT_SubHask_Compatibility_Containers_Map___VarT_i_1628104360____VarT_e_1628104361_ (PrimRef m (Map i e))

data Mutable m (Map' i0 e0) = Mutable_AppT__AppT__ConT_SubHask_Compatibility_Containers_Map'___VarT_i_1628105501____VarT_e_1628105502_ (PrimRef m (Map' i e))

data Mutable m (a0, b0, c0) = Mutable_AppT__AppT__AppT__TupleT_3___VarT_a_1627457391____VarT_b_1627457392____VarT_c_1627457393_ (PrimRef m (a, b, c))

data Mutable m ((/) k a0 b0) = Mutable_Mod (Mutable m a)

data Mutable m (ProofOf * Polynomial_ a0) = Mutable_AppT__AppT__ConT_SubHask_Category_ProofOf___ConT_SubHask_Category_Polynomial_Polynomial_____VarT_a_1627677543_ (PrimRef m (ProofOf * Polynomial_ a))

data Mutable m (IncreasingT cat0 a0 b0) = Mutable_AppT__AppT__AppT__ConT_SubHask_Category_Trans_Monotonic_IncreasingT___VarT_cat_1627694221____VarT_a_1627694222____VarT_b_1627694223_ (PrimRef m (IncreasingT cat a b))

data Mutable m (ProofOf * (IncreasingT cat0) a0) = Mutable_AppT__AppT__ConT_SubHask_Category_ProofOf___AppT__ConT_SubHask_Category_Trans_Monotonic_IncreasingT___VarT_cat_1627694764_____VarT_a_1627694763_ (PrimRef m (ProofOf * (IncreasingT cat) a))

data Mutable m (SVector Nat n r) = Mutable_SVector_Nat (ForeignPtr r)

data Mutable m (SVector Symbol n r) = Mutable_SVector (PrimRef m (SVector Symbol n r))

data Mutable m (UVector Symbol n r) = Mutable_UVector (PrimRef m (UVector Symbol n r))

data Mutable m (Diff n0 a0 b0) = Mutable_AppT__AppT__AppT__ConT_SubHask_Category_Trans_Derivative_Diff___VarT_n_1628013694____VarT_a_1628013695____VarT_b_1628013696_ (PrimRef m (Diff n a b))

data Mutable m (HyperLogLog k k1 p0 a0) = Mutable_AppT__AppT__ConT_SubHask_Compatibility_HyperLogLog_HyperLogLog___VarT_p_1628153617____VarT_a_1628153618_ (PrimRef m (HyperLogLog k k p a))

class IsMutable a where

This class implements conversion between mutable and immutable data types. It is the equivalent of the functions provided in Contol.Monad.Primitive, but we use the names of from the Data.Vector interface because they are simpler and more intuitive.

Every data type is an instance of this class using a default implementation based on PrimRefs. We use OverlappingInstances to allow some instances to provide more efficient implementations. We require that any overlapping instance be semantically equivalent to prevent unsafe behavior. The use of OverlappingInstances should only affect you if your creating your own specialized instances of the class. You shouldn't have to do this unless you are very concerned about performance on a complex type.

FIXME: It's disappointing that we still require this class, the Primitive class, and the Storable class. Can these all be unified?

Minimal complete definition

freeze, thaw, write

Methods

freeze :: PrimBase m => Mutable m a -> m a

Convert a mutable object into an immutable one. The implementation is guaranteed to copy the object within memory. The overhead is linear with the size of the object.

thaw :: PrimBase m => a -> m (Mutable m a)

Convert an immutable object into a mutable one The implementation is guaranteed to copy the object within memory. The overhead is linear with the size of the object.

write :: PrimBase m => Mutable m a -> a -> m ()

Assigns the value of the mutable variable to the immutable one.

copy :: PrimBase m => Mutable m a -> m (Mutable m a)

Return a copy of the mutable object. Changes to the copy do not update in the original, and vice-versa.

unsafeFreeze :: PrimBase m => Mutable m a -> m a

Like "freeze", but much faster on some types because the implementation is not required to perform a memory copy.

WARNING: You must not modify the mutable variable after calling unsafeFreeze. This might change the value of the immutable variable. This breaks referential transparency and is very bad.

unsafeThaw :: PrimBase m => a -> m (Mutable m a)

Like "thaw", but much faster on some types because the implementation is not required to perform a memory copy.

WARNING: You must not access the immutable variable after calling unsafeThaw. The contents of this variable might have changed arbitrarily. This breaks referential transparency and is very bad.

Instances

IsMutable Bool

IsMutable Double

IsMutable Float

IsMutable Int

IsMutable Integer

IsMutable Rational

IsMutable ()

IsMutable POrdering

IsMutable [a]

IsMutable (Maybe' a)

IsMutable a0 => IsMutable (WithPreludeOrd a)

IsMutable t0 => IsMutable (NonNegative t)

IsMutable (VedicSquare n)

IsMutable (Ball b)

IsMutable (Componentwise v)

IsMutable a0 => IsMutable (ZIndex a)

IsMutable (BArray e)

IsMutable (UArray e)

IsMutable (Forward a)

IsMutable (Box v)

IsMutable a0 => IsMutable (Jaccard a)

IsMutable a0 => IsMutable (Hamming a)

IsMutable a0 => IsMutable (Levenshtein a)

IsMutable s0 => IsMutable (Uncompensated s)

IsMutable a0 => IsMutable (Lexical a)

IsMutable a0 => IsMutable (ComponentWise a)

IsMutable r0 => IsMutable (Goedel_ r)

IsMutable b0 => IsMutable (Boolean2Ring b)

IsMutable (Seq a)

IsMutable (IntMap a)

IsMutable (IntMap' a)

IsMutable (Set a)

IsMutable (LexSet a)

IsMutable (ByteString a)

IsMutable a0 => IsMutable (PartitionOnNewline a)

IsMutable (a -> b)

IsMutable (a, b)

IsMutable (Any cxt x)

IsMutable (Labeled' a b)

IsMutable (Galois p k)

IsMutable (Polynomial_ a b)

IsMutable ((+>) a b)

IsMutable (BloomFilter n a)

IsMutable (Map i e)

IsMutable (Map' i e)

IsMutable (a, b, c)

IsMutable (ProofOf * Polynomial_ a)

IsMutable (ProofOf * (IncreasingT cat) a)

IsMutable a0 => IsMutable ((/) k a b)

IsMutable (IncreasingT cat a b)

(KnownNat n, ValidSVector Nat n r) => IsMutable (SVector Nat n r)

ValidSVector Symbol n r => IsMutable (SVector Symbol n r)

Prim r => IsMutable (UVector Symbol n r)

IsMutable (Diff n a b)

IsMutable (HyperLogLog k k p a)

immutable2mutable :: IsMutable a => (a -> b -> a) -> PrimBase m => Mutable m a -> b -> m ()

A Simple default implementation for mutable operations.

mutable2immutable :: IsMutable a => (forall m. PrimBase m => Mutable m a -> b -> m ()) -> a -> b -> a

A Simple default implementation for immutable operations.

unsafeRunMutableProperty :: PrimBase m => m a -> a

This function should only be used from within quickcheck properties. All other uses are unsafe.

mkMutable :: Q Type -> Q [Dec]

Inspects the given type and creates the most efficient Mutable instance possible.

FIXME: implement properly

Primitive types

class PrimMonad m => PrimBase m

Class of primitive monads for state-transformer actions.

Unlike PrimMonad, this typeclass requires that the Monad be fully expressed as a state transformer, therefore disallowing other monad transformers on top of the base IO or ST.

Minimal complete definition

internal

Instances

PrimBase IO

PrimBase (ST s)

type family PrimState m :: *

State token type

Instances

type PrimState IO = RealWorld

type PrimState (ST s) = s

type PrimState (IdentityT m) = PrimState m

type PrimState (ListT m) = PrimState m

type PrimState (MaybeT m) = PrimState m

type PrimState (ErrorT e m) = PrimState m

type PrimState (ReaderT r m) = PrimState m

type PrimState (StateT s m) = PrimState m

type PrimState (StateT s m) = PrimState m

type PrimState (ExceptT e m) = PrimState m

type PrimState (WriterT w m) = PrimState m

type PrimState (WriterT w m) = PrimState m

type PrimState (RWST r w s m) = PrimState m

type PrimState (RWST r w s m) = PrimState m

Internal

These exports should never be used directly. They are required by the "mkMutable" TH function.

data PrimRef m a :: (* -> *) -> * -> *

Mutable variable which full analog of IORef or STRef but could use either of the monads. Unfortunately there's no way to convert PrimRef to STRef or IORef.

readPrimRef :: PrimMonad m => PrimRef m a -> m a

Read value of PrimRef.

writePrimRef :: PrimMonad m => PrimRef m a -> a -> m ()

Write value to PrimRef.

newPrimRef :: PrimMonad m => a -> m (PrimRef m a)

Create new mutable variable with initial value a.

helper_liftM :: Monad m => (a -> b) -> m a -> m b

We need to export this function for deriving of Monadic functions to work