Crate spinlock

A reader/writer spin lock implementation. A spin lock is a particular kind of lock which will not put the thread to sleep when it tries to acquire a lock already hold by another thread or codepath. Instead, the thread will spin on the lock, which means it will loop trying to acquire it again and again.

Timeouts

This implementation has a timeout. Spinlock are fast but should only be used to protect short critical sections and a lock holder should only hold the lock for a very short period of time to avoid wasting CPU cycles. If a thread tries to acquire a lock for more than MAX_WAIT nanoseconds, it will panic.

Optimistic

The implementation is Optimistic. The acquire codepath assumes that the lock operation will succeed and doesn't try to minimize the cost of the initial acquire operation. If the access is contested, the implementation then tries to minimize the pressure on the CPU cache until it it can actually acquire the lock. After SPIN_COUNT retries, the acquire path will call thread::yield_now() between each retry to allow for other threads to run and drop the lock.

Favor exclusive access

If a thread is spinning in an contested exclusive access attempt, no new shared access will be granted. This is designed to avoid Reader DOSing the Writers.

Poisonning

If an exclusive holder panics while holding the lock, it might void the coherency rules. Indeed, the protected data might be in a state in which it is not supposed to be. To prevent this, if an exclusive holder panics, the lock is poisonned and no other access to the lock will be granted.

Structs

PoisonError	A type of error which can be returned whenever a lock is acquired.
SpinLock	A Reader/Writer spinlock
SpinLockReadGuard	RAII structure used to release the shared read access of a lock when dropped.
SpinLockWriteGuard	RAII structure used to release the exclusive write access of a lock when dropped.

Enums

TryLockError

An enumeration of possible errors which can occur while calling the try_lock method.

Constants

MAX_WAIT	Maximum time spent in spinning in constested path in nanoseconds
SPIN_COUNT	Number of spin retry in contested path

Type Definitions

LockResult
TryLockResult