Crate parking_lot_core

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.

Modules

• deadlock
  [Experimental] Deadlock detection

Structs

• ParkToken
  A value associated with a parked thread which can be used by unpark_filter.
• SpinWait
  A counter used to perform exponential backoff in spin loops.
• UnparkResult
  Result of an unpark operation.
• UnparkToken
  A value which is passed from an unparker to a parked thread.

Enums

• FilterOp
  Operation that unpark_filter should perform for each thread.
• ParkResult
  Result of a park operation.
• RequeueOp
  Operation that unpark_requeue should perform.

Constants

• DEFAULT_PARK_TOKEN
  A default park token to use.
• DEFAULT_UNPARK_TOKEN
  A default unpark token to use.

Functions

• park^⚠
  Parks the current thread in the queue associated with the given key.
• unpark_all^⚠
  Unparks all threads in the queue associated with the given key.
• unpark_filter^⚠
  Unparks a number of threads from the front of the queue associated with key depending on the results of a filter function which inspects the ParkToken associated with each thread.
• unpark_one^⚠
  Unparks one thread from the queue associated with the given key.
• unpark_requeue^⚠
  Removes all threads from the queue associated with key_from, optionally unparks the first one and requeues the rest onto the queue associated with key_to.