Control.Concurrent.Process.StoredMVar

This module is an adaptation of MVar to an interprocess communication (IPC). The IPC setting implies a few changes to the interface.

1. StoredMVar resides in a shared memory region.
2. We use Storable instance to serialize and deserialize a value.
3. Point (2) implies the value is always fully evaluated before being stored.
4. Scheduling is done by OS, thus the module does not guarantee FIFO order.
5. Using StoredMVar is only safe if Storable instance for its content is correct and peek does not throw exceptions. If peek throws an exception inside takeMVar or swapMVar, the original content of StoredMVar is not restored

Documentation

data StoredMVar a

An StoredMVar is a synchronising variable, used for communication between concurrent processes or threads. It can be thought of as a a box, which may be empty or full.

StoredMVar tries to mimic vanilla MVar, though it behaves quite differently. It uses Storable instance to make the value accessible in different memory spaces. Thus, the content of StoredMVar is forced to be fully evaluated and serialized.

Instances

Eq (StoredMVar a)

Defined in Control.Concurrent.Process.StoredMVar

Methods

(==) :: StoredMVar a -> StoredMVar a -> Bool

(/=) :: StoredMVar a -> StoredMVar a -> Bool

mVarName :: StoredMVar a -> SOName (StoredMVar a)

Get a global reference to the StoredMVar. Send this reference to another process to lookup this StoredMVar and start interprocess communication.

newEmptyMVar :: forall a. Storable a => IO (StoredMVar a)

Create a StoredMVar which is initially empty.

newMVar :: Storable a => a -> IO (StoredMVar a)

Create a StoredMVar which is initially empty.

lookupMVar :: Storable a => SOName (StoredMVar a) -> IO (StoredMVar a)

Find a StoredMVar created in another process ot thread by its reference.

takeMVar :: Storable a => StoredMVar a -> IO a

Return the contents of the StoredMVar. If the StoredMVar is currently empty, takeMVar will wait until it is full. After a takeMVar, the StoredMVar is left empty.

• takeMVar is single-wakeup. That is, if there are multiple processes blocked in takeMVar, and the StoredMVar becomes full, only one thread will be woken up.
• The library makes no guarantees about the order in which processes are woken up. This is all up to implementation-dependent OS scheduling.

putMVar :: Storable a => StoredMVar a -> a -> IO ()

Put a value into an StoredMVar. If the StoredMVar is currently full, putMVar will wait until it becomes empty.

• putMVar is single-wakeup. That is, if there are multiple threads or processes blocked in putMVar, and the StoredMVar becomes empty, only one thread will be woken up.
• The library makes no guarantees about the order in which processes are woken up. This is all up to implementation-dependent OS scheduling.

readMVar :: Storable a => StoredMVar a -> IO a

Atomically read the contents of an StoredMVar. If the StoredMVar is currently empty, readMVar will wait until its full. readMVar is guaranteed to receive the next putMVar.

readMVar is multiple-wakeup, so when multiple readers are blocked on an StoredMVar, all of them are woken up at the same time.

swapMVar :: Storable a => StoredMVar a -> a -> IO a

Atomically take a value from an StoredMVar, put a new value into the StoredMVar and return the value taken.

tryTakeMVar :: Storable a => StoredMVar a -> IO (Maybe a)

A non-blocking version of takeMVar. The tryTakeMVar function returns immediately, with Nothing if the StoredMVar was empty, or Just a if the StoredMVar was full with contents a. After tryTakeMVar, the StoredMVar is left empty.

tryPutMVar :: Storable a => StoredMVar a -> a -> IO Bool

A non-blocking version of putMVar. The tryPutMVar function attempts to put the value a into the StoredMVar, returning True if it was successful, or False otherwise.

tryReadMVar :: Storable a => StoredMVar a -> IO (Maybe a)

A non-blocking version of readMVar. The tryReadMVar function returns immediately, with Nothing if the StoredMVar was empty, or Just a if the StoredMVar was full with contents a.

trySwapMVar :: Storable a => StoredMVar a -> a -> IO (Maybe a)

A non-blocking version of swapMVar. Atomically attempt take a value from an StoredMVar, put a new value into the StoredMVar and return the value taken (thus, leave the StoredMVar full). Return Nothing if the StoredMVar was empty (and leave it empty).

isEmptyMVar :: StoredMVar a -> IO Bool

Check whether a given StoredMVar is empty.

Notice that the boolean value returned is just a snapshot of the state of the MVar. By the time you get to react on its result, the MVar may have been filled (or emptied) - so be extremely careful when using this operation. Use tryTakeMVar instead if possible.

withMVar :: Storable a => StoredMVar a -> (a -> IO b) -> IO b

withMVar is an exception-safe wrapper for operating on the contents of an StoredMVar. This operation is exception-safe: it will replace the original contents of the StoredMVar if an exception is raised (see Control.Exception). However, it is only atomic if there are no other producers for this StoredMVar.

withMVarMasked :: Storable a => StoredMVar a -> (a -> IO b) -> IO b

Like withMVar, but the IO action in the second argument is executed with asynchronous exceptions masked.

modifyMVar :: Storable a => StoredMVar a -> (a -> IO (a, b)) -> IO b

A slight variation on modifyMVar_ that allows a value to be returned (b) in addition to the modified value of the StoredMVar.

modifyMVar_ :: Storable a => StoredMVar a -> (a -> IO a) -> IO ()

An exception-safe wrapper for modifying the contents of an StoredMVar. Like withMVar, modifyMVar will replace the original contents of the StoredMVar if an exception is raised during the operation. This function is only atomic if there are no other producers for this StoredMVar.

modifyMVarMasked :: Storable a => StoredMVar a -> (a -> IO (a, b)) -> IO b

Like modifyMVar, but the IO action in the second argument is executed with asynchronous exceptions masked.

modifyMVarMasked_ :: Storable a => StoredMVar a -> (a -> IO a) -> IO ()

Like modifyMVar_, but the IO action in the second argument is executed with asynchronous exceptions masked.