ouroboros-consensus-0.1.0.0: Consensus layer for the Ouroboros blockchain protocol
Safe HaskellNone
LanguageHaskell2010

Ouroboros.Consensus.Util.MonadSTM.StrictMVar

Synopsis

Documentation

castStrictMVar ∷ (TMVar m ~ TMVar n, TVar m ~ TVar n) ⇒ StrictMVar m a → StrictMVar n a Source #

modifyMVar ∷ (MonadSTM m, MonadCatch m, HasCallStack) ⇒ StrictMVar m a → (a → m (a, b)) → m b Source #

modifyMVar_ ∷ (MonadSTM m, MonadCatch m, HasCallStack) ⇒ StrictMVar m a → (a → m a) → m () Source #

newEmptyMVarMonadSTM m ⇒ a → m (StrictMVar m a) Source #

newEmptyMVarWithInvariant Source #

Arguments

MonadSTM m 
⇒ (a → Maybe String)

Invariant (expect Nothing)

→ a

The initial stale value

→ m (StrictMVar m a) 

Create an initially empty StrictMVar

NOTE: Since readMVarSTM allows to read the StrictMVar even when it is empty, we need an initial value of a even though the StrictMVar starts out empty. However, we are NOT strict in this value, to allow it to be error.

newMVarMonadSTM m ⇒ a → m (StrictMVar m a) Source #

newMVarWithInvariant Source #

Arguments

∷ (MonadSTM m, HasCallStack) 
⇒ (a → Maybe String)

Invariant (expect Nothing)

→ a 
→ m (StrictMVar m a) 

putMVar ∷ (MonadSTM m, HasCallStack) ⇒ StrictMVar m a → a → m () Source #

readMVarMonadSTM m ⇒ StrictMVar m a → m a Source #

readMVarSTMMonadSTM m ⇒ StrictMVar m a → STM m a Source #

Read the possibly-stale value of the MVar

Will return the current value of the MVar if it non-empty, or the last known value otherwise.

swapMVar ∷ (MonadSTM m, HasCallStack) ⇒ StrictMVar m a → a → m a Source #

Swap value of a StrictMVar

NOTE: Since swapping the value can't leave the StrictMVar empty, we could check the invariant first and only then swap. We nonetheless swap first and check the invariant after to keep the semantics the same with putMVar, otherwise it will be difficult to understand when a StrictMVar is updated and when it is not.

takeMVarMonadSTM m ⇒ StrictMVar m a → m a Source #

tryPutMVar ∷ (MonadSTM m, HasCallStack) ⇒ StrictMVar m a → a → m Bool Source #

tryReadMVarMonadSTM m ⇒ StrictMVar m a → m (Maybe a) Source #

tryTakeMVarMonadSTM m ⇒ StrictMVar m a → m (Maybe a) Source #

updateMVar ∷ (MonadSTM m, HasCallStack) ⇒ StrictMVar m a → (a → (a, b)) → m b Source #

updateMVar_ ∷ (MonadSTM m, HasCallStack) ⇒ StrictMVar m a → (a → a) → m () Source #

constructors exported for benefit of tests

data StrictMVar m a Source #

Strict MVar (modelled using a lazy TMVar under the hood)

The StrictMVar API is slightly stronger than the usual MVar one, as we offer a primitive to read the value of the MVar even if it is empty (in which case we will return the oldest known stale one). See readMVarSTM.

There is a weaker invariant for a StrictMVar than for a StrictTVar: although all functions that modify the StrictMVar check the invariant, we do not guarantee that the value inside the StrictMVar always satisfies the invariant. Instead, we do guarantee that if the StrictMVar is updated with a value that does not satisfy the invariant, an exception is thrown. The reason for this weaker guarantee is that leaving an MVar empty can lead to very hard to debug "blocked indefinitely" problems.

This is also the reason we do not offer support for an invariant in StrictTMVar: if we throw an exception from an STM transaction, the STM transaction is not executed, and so we would not even be able to provide the weaker guarantee that we provide for StrictMVar.

Constructors

StrictMVar 

Fields

  • invariant ∷ !(a → Maybe String)

    Invariant checked whenever updating the StrictMVar.

  • tmvar ∷ !(TMVar m a)

    The main TMVar supporting this StrictMVar

  • tvar ∷ !(TVar m a)

    TVar for supporting readMVarSTM

    This TVar is always kept up to date with the TMVar, but holds on the old value of the TMVar when it is empty. This is very useful to support single writer/many reader scenarios.

    NOTE: We should always update the tmvar before the tvar so that if the update to the tmvar fails, the 'tvar is left unchanged.

Instances

Instances details
NoThunks a ⇒ NoThunks (StrictMVar IO a) Source # 
Instance details

Defined in Ouroboros.Consensus.Util.MonadSTM.StrictMVar

Methods

noThunks ∷ Context → StrictMVar IO a → IO (Maybe ThunkInfo) #

wNoThunks ∷ Context → StrictMVar IO a → IO (Maybe ThunkInfo) #

showTypeOfProxy (StrictMVar IO a) → String #