MVar
public final class MVar<A>
An MVar
(pronounced “em-var”) is a synchronising variable, used for communication between concurrent threads.
It can be thought of as a box, which may be empty or full.
An MVar<A>
is mutable location that is either empty or contains a value of type A
. It has two fundamental
operations: put(_:)
which fills an MVar
if it is empty and blocks otherwise, and take()
which empties
an MVar
if it is full and blocks otherwise. They can be used in multiple different ways:
- As synchronized mutable variables,
- As channels, with
take()
andput(_:)
as receive and send, and - As a binary semaphore
MVar<Void>
, withtake()
andput(_:)
as wait and signal.
-
Create an
MVar
which is initially empty.Declaration
Swift
public init()
-
Create an
MVar
which contains the supplied value.Declaration
Swift
public convenience init(value: A)
Parameters
value
initial value
-
Return the contents of the
MVar
. If theMVar
is currently empty,take()
will wait until it is full. After atake()
, theMVar
is left empty.See also
read()
There are two further important properties of
take()
:take()
is single-wakeup. That is, if there are multiple threads blocked intake()
, and theMVar
becomes full, only one thread will be woken up. The runtime guarantees that the woken thread completes itstake()
operation.- When multiple threads are blocked on an
MVar
, they are woken up in FIFO order. This is useful for providing fairness properties of abstractions built usingMVar
s.
Declaration
Swift
public func take() -> A
Return Value
the contents of the
MVar
-
Put a value into an
MVar
. If theMVar
is currently full,put(_:)
will wait until it becomes empty.There are two further important properties of
put(_:)
:put(_:)
is single-wakeup. That is, if there are multiple threads blocked input(_:)
, and theMVar
becomes empty, only one thread will be woken up. The runtime guarantees that the woken thread completes itsput(_:)
operation.- When multiple threads are blocked on an
MVar
, they are woken up in FIFO order. This is useful for providing fairness properties of abstractions built usingMVar
s.
Declaration
Swift
public func put(_ value: A)
Parameters
value
new value
-
Atomically read the contents of an
MVar
. If theMVar
is currently empty,read()
will wait until it is full.read()
is guaranteed to receive the nextput(_:)
.See also
take()
read()
is multiple-wakeup, so when multiple readers are blocked on anMVar
, all of them are woken up at the same time.Declaration
Swift
public func read() -> A
Return Value
the contents of the
MVar
-
Take a value from an
MVar
, put a new value into theMVar
and return the value taken. This function is atomic only if there are no other producers for thisMVar
.Declaration
Swift
public func swap(_ value: A) -> A
Parameters
value
new value
Return Value
old value
-
Check whether a given
MVar
is empty.Note
Notice that the boolean value returned is just a snapshot of the state of theMVar
. By the time you get to react on its result, theMVar
may have been filled (or emptied) - so be extremely careful when using this operation. UsetryTake(_:)
instead if possible.Declaration
Swift
public var isEmpty: Bool { get }
-
with(_:)
is an rethrows wrapper for operating on the contents of anMVar
. This operation rethrow exception iff
raise exception. It won’t replace the original contents of theMVar
if an exception is raised. However, it is only atomic if there are no other producers for thisMVar
.Declaration
Swift
public func with<B>(_ f: (A) throws -> B) rethrows -> B
Parameters
f
ƒ
Return Value
calculated
ƒ(a)
-
A rethrow wrapper for modifying the contents of an
MVar
. Likewith(_:)
,modify_(_:)
won’t replace the original contents of theMVar
if an exception is raised during the operation. This function is only atomic if there are no other producers for thisMVar
.Declaration
Swift
public func modify_(_ f: (A) throws -> A) rethrows
Parameters
f
f
-
A slight variation on
modify_(_:)
that allows a value to be returned (b) in addition to the modified value of theMVar
.Declaration
Swift
public func modify<B>(_ f: (A) throws -> (A, B)) rethrows -> B
Parameters
f
ƒ
Return Value
ƒ(a).1
-
A non-blocking version of
read()
. ThetryRead()
function returns immediately, with.none
if theMVar
was empty, or.some(a)
if theMVar
was full with contentsa
.See also
read(_:)
Declaration
Swift
public func tryRead() -> A?
Return Value
.none
if theMVar
is empty, or.some(a)
if theMVar
was full with contentsa
.