Module sunrise_kernel::sync::mutex

Preemptive Mutex

Behaviour

Lock that preempts if it cannot be obtained immediately. See the sync module.

The mutex holds a queue of the waiters, and when unlocking it checks if there is contention, in which case it wakes up the head of the queue by popping it and adding it to the schedule queue.

The lock performs additional checks around the owner of the lock, and panics if double-locking is detected.

When there is contention and the thread is put to sleep, it is removed from the schedule queue, and an Arc to its ThreadStruct is put in the waiters queue. This means that the thread will stay alive at least until it is waked up.

Most of this module is copy-pasted from std Mutexes, and try to preserve the same structure, while the documentation has been re-written.

However we don't implement poisons, as kernel thread panicking while holding a Mutex should simply kernel panic, and abort.

Internal workings

The secret about these mutex is that they're just fancy wrappers around a SpinLock.

This SpinLock protects the queue. When checking for contention, we take the SpinLock, which arbitrates all concurrent operations for us, and then simply check if the queue of waiters is empty.

If necessary we add ourselves to the queue, and then both unschedule ourselves and unlock it simultaneously.

Unlocking performs pretty much the same operation.

Structs

Mutex	A mutual exclusion primitive useful for protecting shared data
MutexGuard	An RAII implementation of a "scoped lock" of a mutex. When this structure is dropped (falls out of scope), the lock will be unlocked.
MutexInner	The type responsible of actually performing the locking of the mutex.
MutexInnerInner	The bookkeeping of a Mutex. Knows the current owner, and holds the waiters queue.

Type Definitions

TryLockResult

A type alias for the result of a nonblocking locking method.