M-vars: Synchronized Boxes🔗ℹ

1 Guarantees🔗ℹ

1.1 Ordering and Fairness🔗ℹ

M-var synchronization is fair: if a thread is blocked on an M-var operation, and opportunities for the operation to complete occur infinitely often, the operation is guaranteed to eventually complete. However, the precise order in which threads blocked on a call to mvar-put! or mvar-take! are woken up is not guaranteed.

If a thread is blocked on a call to mvar-peek, the call is guaranteed to complete the next time the M-var is filled, even if another thread is blocked on a call to mvar-take! on the same M-var. In other words, whenever mvar-peek and mvar-take! compete to read the next value of an empty M-var, mvar-peek always wins. Since mvar-peek is not exclusive—that is, it does not preclude another thread from reading the same M-var after it completes—this preference for mvar-peek ensures that the maximum number of threads are woken up each time an M-var is filled.

1.2 Atomicity🔗ℹ

All M-var core operations are atomic: so long as their executing thread is not killed or suspended (see Thread Safety), either none or all of their effects will take place. This atomicity is guaranteed regardless of the way in which the M-var is used.

In contrast, derived operations internally perform multiple core operations in sequence, and those sequences are not intrinsically atomic. However, all derived operations currently provided by this library offer a weaker form of atomicity: they rely on the common M-var usage pattern of treating the M-var like a semaphore-protected box, where each use of mvar-put! is preceded by a use of mvar-take! to acquire exclusive access. This exclusive locking discipline ensures that derived operations are atomic with respect to the M-var’s state—each operation constitutes a non-overlapping “transaction” that is always fully committed or fully rolled back—but following the pattern correctly is the programmer’s responsibility.

1.3 Thread Safety🔗ℹ

M-vars are a concurrent data structure, so all M-var operations are naturally thread-safe. Furthermore, they are also break-safe: if a thread is interrupted via break-thread while executing any M-var operation, its atomicity guarantees will not be compromised, and the M-var will always remain in a valid state.

However, M-vars are not kill-safe. If a thread is killed via kill-thread while executing any M-var operation (including mvar-peek), the operation’s effects may only partially complete, and the M-var may be permanently left in an invalid state. In a similar vein, if a thread is suspended via thread-suspend while executing any M-var operation, the operation may only partially complete, and the M-var may become temporarily unusable until the thread is resumed.

M-var operations also cannot safely be called in atomic mode. Even non-blocking operations like mvar-try-peek may require polling events, which can lead to a deadlock if atomic mode is active.

2 Core Operations🔗ℹ

This section documents the complete list of M-var core operations. All core operations are primitive (they cannot be derived from other operations) and atomic (but not kill-safe; see Thread Safety).

If enable-break? is not #f, breaks are explicitly enabled while waiting on mv. If breaks are disabled when mvar-put! is called, then either mv is filled or an exn:break exception is raised, but not both.

If enable-break? is not #f, breaks are explicitly enabled while waiting on mv. If breaks are disabled when mvar-take! is called, then either mv is emptied or an exn:break exception is raised, but not both.

If enable-break? is not #f, breaks are explicitly enabled while waiting on mv. If breaks are disabled when mvar-peek is called, then either mv is emptied or an exn:break exception is raised, but not both.

Note that mvar-take! followed immediately by a use of mvar-put! to replace the taken value is not equivalent to mvar-peek: since mvar-take! empties the M-var, another thread may fill it with a different value before the removed value can be replaced. In comparison, mvar-peek does not remove the value from the M-var, so it is guaranteed to be atomic. Additionally, a call to mvar-peek is guaranteed to return as soon as the M-var is filled, while mvar-take! is not; see Ordering and Fairness.

This operation is provided for completeness, but note that if mv has multiple readers, the result of this function could become out of date the moment it returns. It is therefore very rarely the right choice, and it is almost always better to use mvar-try-put!, mvar-try-take!, or mvar-try-peek, instead.

Like mvar-empty?, this operation should be used very carefully: even if the event is selected, another thread might fill mv the instant that sync returns, so it is almost always better to use mvar-put!-evt, instead. However, in programs where mv only has a single writer, it can rarely be useful, so it is provided for completeness.

3 Derived Operations🔗ℹ

The bindings documented in this section are derived operations, which codify some common patterns that arise when an M-var is used like a semaphore-protected box. Since they are implemented as sequences of core operations, they are not intrinsically atomic. Instead, atomicity is enforced through a locking discipline: each operation expects to receive an M-var that is normally kept full, and it uses mvar-take! to acquire an exclusive lock on its contents. When the operation returns, it uses mvar-put! to simultaneously update the contents and release the lock.

Since all of the bindings in this section follow this locking discipline, an easy recipe to ensure atomicity is to never use mvar-take! or mvar-put! directly on any M-var used as a semaphore-protected box. Doing this comes at the risk of accidentally failing to either acquire or release the lock, which is especially easy to do if the critical section fails with an exception or is interrupted by a break. The higher-level, derived operations documented in this section make those accidents impossible, so they should be preferred whenever the lower-level, channel-style operations are not needed.

Since mvar-swap! is implemented using mvar-take! followed by mvar-put!, it is not intrinsically atomic. To ensure atomicity, mvar-swap! should only be used on M-vars that follow the required locking discipline.

Since mvar-update! is implemented using mvar-take! followed by mvar-put!, it is not intrinsically atomic. To ensure atomicity, mvar-update! should only be used on M-vars that follow the required locking discipline.

call-with-mvar is useful if mv contains a handle to a shared resource that cannot be used by more than one thread at a time. For example, mv might hold an output port, and a writer thread might use call-with-mvar to obtain exclusive access to the port while it writes a packet, which must not be interleaved with other writes. Once the packet has been written and body-proc returns, call-with-mvar puts the output port back in mv, making it available for acquisition by some other thread.

Since call-with-mvar is implemented using mvar-take! followed by mvar-put!, it is not intrinsically atomic. To ensure atomicity, call-with-mvar should only be used on M-vars that follow the required locking discipline.

In other words, call-with-mvar! is effectively a combination of call-with-mvar and mvar-update!: body-proc determines both the value put back into mv and the result (or results) of the overall call.

Since call-with-mvar! is implemented using mvar-take! followed by mvar-put!, it is not intrinsically atomic. To ensure atomicity, call-with-mvar! should only be used on M-vars that follow the required locking discipline.

4 Contracts🔗ℹ

If in-ctc and out-ctc are both chaperone contracts, the result will be a chaperone contract. Otherwise, the result will be an impersonator contract.

5 Chaperones and Impersonators🔗ℹ

If get-proc is not #f, the result of each use of mvar-take! or mvar-peek on the impersonator is redirected through get-proc, which must produce a replacement value. Likewise, if put-proc is not #f, the value stored by each use of mvar-put! is redirected through put-proc.

Pairs of prop and prop-val (the number of by-position arguments to impersonate-mvar must be odd) add or override impersonator property values of mv.

6 Comparison with syncvar🔗ℹ

Bibliography🔗ℹ