This library exposes a low-level API for creating your own efficient synchronization primitives.

The parking lot

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 WTF::ParkingLot 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 queue lock.

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

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.