Safe Haskell	Safe-Inferred
Language	GHC2021

Control.Concurrent.Class.MonadSTM.RWVar

Description

A read-write-locked mutable variable with a bias towards write locks.

This module is intended to be imported qualified:

  import           Control.Concurrent.Class.MonadSTM.RWVar (RWVar)
  import qualified Control.Concurrent.Class.MonadSTM.RWVar as RW

Synopsis

newtype RWVar m a = RWVar (StrictTVar m (RWState a))
data RWState a
- = Reading !Word64 !a
- | WaitingToWrite !Word64 !a
- | Writing
new :: MonadSTM m => a -> m (RWVar m a)
unsafeAcquireReadAccess :: MonadSTM m => RWVar m a -> STM m a
unsafeReleaseReadAccess :: MonadSTM m => RWVar m a -> STM m ()
withReadAccess :: (MonadSTM m, MonadThrow m) => RWVar m a -> (a -> m b) -> m b
unsafeAcquireWriteAccess :: (MonadSTM m, MonadCatch m) => RWVar m a -> m a
unsafeReleaseWriteAccess :: MonadSTM m => RWVar m a -> a -> STM m ()
withWriteAccess :: (MonadSTM m, MonadCatch m) => RWVar m a -> (a -> m (a, b)) -> m b
withWriteAccess_ :: (MonadSTM m, MonadCatch m) => RWVar m a -> (a -> m a) -> m ()

Documentation

newtype RWVar m a Source #

A read-write-locked mutable variable with a bias towards write-locks.

Constructors

RWVar (StrictTVar m (RWState a))

Instances

Instances details

NFData (RWVar m a) Source #	NOTE: Only strict in the reference and not the referenced value.
Instance details Defined in Control.Concurrent.Class.MonadSTM.RWVar Methods rnf :: RWVar m a -> () #

data RWState a Source #

Constructors

Reading !Word64 !a	`n` concurrent readers and no writer.
WaitingToWrite !Word64 !a	`n` concurrent readers and no writer, but no new readers can get access.
Writing	A single writer and no concurrent readers.

new :: MonadSTM m => a -> m (RWVar m a) Source #

unsafeAcquireReadAccess :: MonadSTM m => RWVar m a -> STM m a Source #

unsafeReleaseReadAccess :: MonadSTM m => RWVar m a -> STM m () Source #

withReadAccess :: (MonadSTM m, MonadThrow m) => RWVar m a -> (a -> m b) -> m b Source #

unsafeAcquireWriteAccess :: (MonadSTM m, MonadCatch m) => RWVar m a -> m a Source #

Acquire write access. This function assumes that it runs in a masked context, and that is properly paired with an unsafeReleaseWriteAccess!

If multiple threads try to acquire write access concurrently, then they will race for access. However, if a thread has set RWState to WaitingToWrite, then it is guaranteed that the same thread will acquire write access when all readers have finished. That is, other writes can not "jump the queue". When the writer finishes, then all other waiting threads will race for write access again.

TODO: unsafeReleaseWriteAccess will set RWState to Reading 0. In case we have readers *and* writers waiting for a writer to finish, once the writer is finished there will be a race. In this race, readers and writers are just as likely to acquire access first. However, if we wanted to make RWVar even more biased towards writers, then we could ensure that all waiting writers get access before the readers get a chance. This would probably require us to change RWState to represent the case where writers are waiting for a writer to finish.

unsafeReleaseWriteAccess :: MonadSTM m => RWVar m a -> a -> STM m () Source #

Release write access. This function assumes that it runs in a masked context, and that is properly paired with an unsafeAcquireWriteAccess!

withWriteAccess :: (MonadSTM m, MonadCatch m) => RWVar m a -> (a -> m (a, b)) -> m b Source #

withWriteAccess_ :: (MonadSTM m, MonadCatch m) => RWVar m a -> (a -> m a) -> m () Source #