This library exposes a low-level API for creating your own efficient synchronization primitives.
To keep synchronization primitives small, all thread queuing and suspending
functionality is offloaded to the parking lot. The idea behind this is based
on the Webkit
class, which essentially consists of a hash table mapping of lock addresses
to queues of parked (sleeping) threads. The Webkit parking lot was itself
inspired by Linux futexes,
but it is more powerful since it allows invoking callbacks while holding a
There are two main operations that can be performed on the parking lot:
- Parking refers to suspending the thread while simultaneously enqueuing it on a queue keyed by some address.
- Unparking refers to dequeuing a thread from a queue keyed by some address and resuming it.
See the documentation of the individual functions for more details.
Building custom synchronization primitives is very simple since the parking
lot takes care of all the hard parts for you. A simple example for a
custom primitive would be to integrate a
Mutex inside another data type.
Since a mutex only requires 2 bits, it can share space with other data.
For example, one could create an
ArcMutex type that combines the atomic
reference count and the two mutex bits in the same atomic word.
- [Experimental] Deadlock detection
- A value associated with a parked thread which can be used by
- A counter used to perform exponential backoff in spin loops.
- Result of an unpark operation.
- A value which is passed from an unparker to a parked thread.
- Operation that
unpark_filtershould perform for each thread.
- Result of a park operation.
- Operation that
- A default park token to use.
- A default unpark token to use.
- park⚠Parks the current thread in the queue associated with the given key.
- Unparks all threads in the queue associated with the given key.
- Unparks a number of threads from the front of the queue associated with
keydepending on the results of a filter function which inspects the
ParkTokenassociated with each thread.
- Unparks one thread from the queue associated with the given key.
- Removes all threads from the queue associated with
key_from, optionally unparks the first one and requeues the rest onto the queue associated with