Control.Monad.ST2

The ST2 monad is like the ST monad, but with finer-grained control over access to mutable state. The phantom type parameters r and w are used to track the read and write dependencies of the computation. If a computation of type ST2 r w a is polymorphic in w then it does not write any external state. If it is also polymorphic in r then it does not read any external state. Operations which modify state, such as writeST2Ref, are considered to read external state as well as write it, so it is impossible for a computation of type ST2 r w a to be polymorphic in r but not in w. This means that the r type parameter behaves exactly like the s type parameter on the ST monad, but the w type parameter provides extra information which is not available in the ST monad.

Like the ST monad, the ST2 monad allows mutable references and arrays to be created, read, and written within a computation. Provided that the mutable state does not escape, it does not affect the type signature of the top-level computation.

ST2 Monad

data ST2 r w a

The ST2 monad is a newtype of IO. The type parameters r and w are phantom type parameters which are used to track the read and write dependencies of the computation.

Instances

Monad (ST2 r w)

Functor (ST2 r w)

pureST2 :: (forall r w. ST2 r w a) -> ST2 r' w' a

This function checks that the sub-computation is polymorphic in both type parameters. This means that the sub-computation does not read or write any state from the enclosing context.

newtype PureST2 a

runPureST2 is semantically equivalent to pureST2, but uses a newtype to package the forall. Sometimes this packaging is convenient when passing a value of type PureST2 as an argument because it avoids the need for a nested forall in the type signature.

Constructors

PureST2

Fields

runPureST2 :: forall r w. ST2 r w a

readOnlyST2 :: (forall w. ST2 r w a) -> ST2 r w' a

This function checks that the sub-computation is polymorphic in the w type parameter. This means that the sub-computation does not write any state from the enclosing context (but read-only operations are permitted).

newtype ReadOnlyST2 r a

runReadOnlyST2 is semantically equivalent to readOnlyST2, but uses a newtype to package the forall. Sometimes this packaging is convenient when passing a value of type ReadOnlyST2 as an argument because it avoids the need for a nested forall in the type signature.

Constructors

ReadOnlyST2

Fields

runReadOnlyST2 :: forall w. ST2 r w a

ioToST2 :: IO a -> ST2 () () a

IO computations can be converted to ST2 computations, but only with a monomorphic type signature.

st2ToIO :: ST2 () () a -> IO a

ST2 computations can be converted to IO computations, but only with a monomorphic type signature.

ST2 References

data ST2Ref r w a

Mutable reference. ST2Ref is actually just a newtype of an IORef, but the r and w type parameters allow the read and write dependencies to be tracked by the type system.

newST2Ref :: a -> ST2 r w (ST2Ref r w a)

Create a new reference. The r and w type parameters of the reference are unified with the ST2 monad to indicate that new state is created in the enclosing context.

readST2Ref :: ST2Ref r w a -> ST2 r w' a

Read a reference. The w type parameter of the reference is not unified with the ST2 monad to indicate that this access is read-only.

writeST2Ref :: ST2Ref r w a -> a -> ST2 r w ()

Write to a reference. The w type parameter of the reference is unified with the ST2 monad to indicate that state is written in the enclosing context.

modifyST2Ref :: ST2Ref r w a -> (a -> a) -> ST2 r w ()

Modify a reference.

importST2Ref :: IORef a -> ST2Ref () () a

Convert an IORef to an ST2Ref.

exportST2Ref :: ST2Ref () () a -> IORef a

Convert an ST2Ref to an IORef.

ST2 Arrays

data ST2Array r w i a

Mutable array. ST2Array is actually just a newtype of an IOArray, but the r and w type parameters allow the read and write dependencies to be tracked by the type system.

newST2Array :: Ix i => (i, i) -> a -> ST2 r w (ST2Array r w i a)

Create an array with an initial value.

newST2Array_ :: Ix i => (i, i) -> ST2 r w (ST2Array r w i a)

Create an uninitialised array.

readST2Array :: Ix i => ST2Array r w i a -> i -> ST2 r w' a

Read an index of the array. The w type parameter of the reference is not unified with the ST2 monad to indicate that this access is read-only.

writeST2Array :: Ix i => ST2Array r w i a -> i -> a -> ST2 r w ()

Write an index of the array. The w type parameter of the array is unified with the ST2 monad to indicate that state is written in the enclosing context.

boundsST2Array :: Ix i => ST2Array r w i a -> ST2 r' w' (i, i)

Read the size of the array. Neither type parameter is unified with the ST2 monad because the array itself is not accessed. (Conceptually, an ST2Array is a pair, consisting of the size information and the array. This function only accesses the size information, which is immutable.)

importST2Array :: IOArray i a -> ST2Array () () i a

Convert an IOArray to an ST2Array.

exportST2Array :: ST2Array () () i a -> IOArray i a

Convert an ST2Array to an IOArray.

ST2 Read-only Arrays

data ST2RArray r i a

Read-only array. Existential quantification is used to hide the w type parameter. This means that it can escape a ReadOnlyST2 context, and can be read in the enclosing context. However, it is impossible for anyone to write to the array outside of the ReadOnlyST2 context in which the array was created.

mkST2RArray :: ST2Array r w i a -> ST2RArray r i a

Create a read-only array. It is important to note that this function does not make the original ST2Array immutable. It merely creates a read-only reference to the original array. However, the ST2RArray can be returned through a readOnlyST2 or ReadOnlyST2 context and the typing rules ensure that the original ST2Array cannot be modified outside of the ReadOnlyST2 context in which it was created. In other words, the original ST2Array can continue to be modified after the ST2RArray is created, but only until the ST2RArray is returned through a ReadOnlyST2 context.

readST2RArray :: Ix i => ST2RArray r i a -> i -> ST2 r w a

Read an index of the read-only array.

Parallelism

parallelST2 :: Ix i => (i, i) -> (i -> ST2 r w ()) -> ST2 r w ()

Spawn one thread for each index in the range and wait for all the threads to finish. Each thread is parameterised by its index, which is an element of the range.