-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | shared heap regions between local mutable state threads -- -- This library implements the ST2 monad, a type using GDP (ghosts of -- departed proofs) to define shared regions of memory between local -- mutable state threads. This allows us to define a region of the heap -- in more minute contours, with each state thread having explicit access -- to regions in memory. This is achieved using the function -- runST2, which in effects lets the user run a computation that -- makes use of two partially-overlapping memory regions. Within that -- computation, the user can run sub-computations bound to one or the -- other memory region. Furthermore, a sub-computation can move any -- variable that it owns into the common overlap via share. -- -- An example is shown in the documentation, where one sub-computation -- creates two cells: one private, and the other shared. A second -- sub-computation has unconstrained access to the shared cell. Yet even -- though the private reference is also in scope during the second -- sub-computation, any attempts to access it there will fail to compile. @package st2 @version 0.1.0.2 -- | This library implements the ST2 monad, a type using GDP (ghosts of -- departed proofs) to define shared regions of memory between local -- mutable state threads. This allows us to define a region of the heap -- in more minute contours, with each state thread having explicit access -- to regions in memory. This is achieved using the function -- runST2, which in effects lets the user run a computation that -- makes use of two partially-overlapping memory regions. Within that -- computation, the user can run sub-computations bound to one or the -- other memory region. Furthermore, a sub-computation can move any -- variable that it owns into the common overlap via share. -- -- An example is shown in below, where one sub-computation creates two -- cells: one private, and the other shared. A second sub-computation has -- unconstrained access to the shared cell. Yet even though the private -- reference is also in scope during the second sub-computation, any -- attempts to access it there will fail to compile. -- -- 
--   >>> :{
--   stSharingDemo :: Bool
--   stSharingDemo = runST2 $ do
--     -- In the "left" memory region, create and return
--     -- two references; one shared, and one not shared.
--     (secret, ref) <- liftL $ do
--       unshared <- newSTRef 42
--       shared   <- share =<< newSTRef 17
--       return (unshared, shared)
--     -- In the "right" memory region, mutate the shared
--     -- reference. If we attempt to access the non-shared
--     -- reference here, the program will not compile.
--     liftR $ do
--       let mine = use (symm ref)
--       x <- readSTRef mine
--       writeSTRef mine (x + 1)
--     -- Back in the "left" memory region, verify that the
--     -- unshared reference still holds its original value.
--     liftL $ do
--       check <- readSTRef secret
--       return (check == 42) 
--   :}
--
module Control.Monad.ST2 -- | The strict state-transformer monad. A computation of type -- ST s a transforms an internal state indexed by -- s, and returns a value of type a. The s -- parameter is either -- -- -- -- It serves to keep the internal states of different invocations of -- runST separate from each other and from invocations of -- stToIO. -- -- The >>= and >> operations are strict in the -- state (though not in values stored in the state). For example, -- -- 
--   runST (writeSTRef _|_ v >>= f) = _|_
--
newtype ST s a ST :: STRep (Any ~~ s) a -> ST s a -- | Convenience type alias for expressing ST computations more succintly. type STRep s a = State# s -> (# State# s, a #) -- | Allow the result of a state transformer computation to be used -- (lazily) inside the computation. -- -- Note that if f is strict, fixST f = _|_. fixST :: (a -> ST s a) -> ST s a -- | liftST is useful when we want a lifted result from an ST -- computation. See fixST below. liftST :: ST s a -> State# s -> STret s a -- | Return the value computed by a state transformer computation. The -- forall ensures that the internal state used by the ST -- computation is inaccessible to the rest of the program. runST :: (forall s. ST s a) -> a -- | A value of type STRef s a is a mutable variable in state -- thread s, containing a value of type a data STRef s a STRef :: MutVar# s a -> STRef s a -- | Build a new STRef in the current state thread newSTRef :: a -> ST s (STRef s a) -- | Read the value of an STRef readSTRef :: STRef s a -> ST s a -- | Write a new value into an STRef writeSTRef :: STRef s a -> a -> ST s () -- | A pretty type alias for Common. type s ∩ s' = Common s s' -- | A type that shows that the state threads s and s' refer to a heap -- region that overlaps in some way such that s and s' can both access -- the overlap, while maintaining privacy in their own heap regions. data Common s s' -- | Move a variable that you own into a region with common overlap. share :: STRef s a -> ST s (STRef (Common s s') a) -- | Lift an ST computation into a context with another heap region liftL :: ST s a -> ST (Common s s') a -- | Lift an ST computation into a context with another heap region liftR :: ST s' a -> ST (Common s s') a -- | Given proof that one has access to the heap regions s and s', yield an -- STRef to the region s. use :: STRef (Common s s') a -> STRef s a -- | Given proof that one has access to the heap regions s and s', yield an -- STRef that swaps the order of the regions. symm :: STRef (Common s s') a -> STRef (Common s' s) a -- | Return the value computed by a state transformer computation over a -- shared heap. The forall ensures that the internal state(s) -- used by the ST computation is inaccessible to the rest of the -- program. runST2 :: (forall s s'. ST (Common s s') a) -> a -- | Convert an ST2 to an ST toBaseST :: ST s a -> ST s a -- | Convert an ST to an ST2 fromBaseST :: ST s a -> ST s a -- | A simple product type containing both the state thread and value -- inside of the ST data STret s a -- | unsafeInterleaveST allows an ST computation to be -- deferred lazily. When passed a value of type ST a, the -- ST computation will only be performed when the value of the -- a is demanded. unsafeInterleaveST :: ST s a -> ST s a -- | unsafeDupableInterleaveST allows an ST computation to be -- deferred lazily. When passed a value of type ST a, the -- ST computation will only be performed when the value of the -- a is demanded. -- -- The computation may be performed multiple times by different threads, -- possibly at the same time. To prevent this, use -- unsafeInterleaveST instead. unsafeDupableInterleaveST :: ST s a -> ST s a -- | Convert an ST action to a PrimMonad. stToPrim :: PrimMonad m => ST (PrimState m) a -> m a -- | Convert any PrimBase to ST with an arbitrary state -- token. This operation is highly unsafe! unsafePrimToST :: PrimBase m => m a -> ST s a -- | Convert an ST action with an arbitrary state token to any -- PrimMonad. This operation is highly unsafe! unsafeSTToPrim :: PrimBase m => ST s a -> m a -- | Extract the value out of the ST computation. Compare this to -- runST; in this case, the rest of the program is permitted to -- reference the state thread s. This operation is highly -- unsafe! unsafeInlineST :: ST s a -> a -- | Embed a strict state transformer in an IO action. The -- RealWorld parameter indicates that the internal state used by -- the ST computation is a special one supplied by the IO -- monad, and thus distinct from those used by invocations of -- runST. stToIO :: ST RealWorld a -> IO a -- | Convert an IO action into an ST action. The type of the -- result is constrained to use a RealWorld state, and therefore -- the result cannot be passed to runST. ioToST :: IO a -> ST RealWorld a -- | RealWorld is deeply magical. It is primitive, but it -- is not unlifted (hence ptrArg). We never manipulate -- values of type RealWorld; it's only used in the type system, -- to parameterise State#. data RealWorld :: Type instance GHC.Classes.Eq (Control.Monad.ST2.STRef s a) instance Control.Monad.Primitive.PrimMonad (Control.Monad.ST2.ST s) instance Control.Monad.Primitive.PrimBase (Control.Monad.ST2.ST s) instance GHC.Base.Functor (Control.Monad.ST2.ST s) instance GHC.Base.Applicative (Control.Monad.ST2.ST s) instance GHC.Base.Monad (Control.Monad.ST2.ST s) instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Control.Monad.ST2.ST s a) instance GHC.Base.Monoid a => GHC.Base.Monoid (Control.Monad.ST2.ST s a) instance GHC.Show.Show (Control.Monad.ST2.ST s a)