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.
unpark_filtershould perform for each thread.
keydepending on the results of a filter function which inspects the
ParkTokenassociated with each thread.
key_from, optionally unparks the first one and requeues the rest onto the queue associated with