Class shared_spin_mutex

Class Documentation

class concore::v1::shared_spin_mutex

A shared (read-write) mutex class that uses CPU spinning.

For mutexes that protect very small regions of code, a shared_spin_mutex can be much faster than a traditional shared_mutex. Instead of taking a lock, this will spin on the CPU, trying to avoid yielding the CPU quanta.

The ownership of the mutex can fall in 3 categories:

  • no ownership no thread is using the mutex

  • exclusive ownership only one thread can access the mutex, exclusively (WRITE operations)

  • shared ownership multiple threads can access the mutex in a shared way (READ operations)

While one threads acquires exclusive ownership, no other thread can have shared ownership. Multiple threads can have a shared ownership over the mutex.

This implementation favors exclusive ownership versus shared ownership. If a thread is waiting for exclusive ownership and one thread is waiting for the shared ownership, the thread that waits on the exclusive ownership will be granted the ownership first.

This uses an exponential backoff spinner. If after some time doing small waits it cannot enter the critical section, it will yield the CPU quanta of the current thread.

Spin shared mutexes should only be used to protect very-small regions of code; a handful of CPU instructions. For larger scopes, a traditional shared mutex may be faster; but then, think about using rw_serializer to avoid mutexes completely.

See

spin_mutex, spin_backoff, rw_serializer

Public Functions

shared_spin_mutex() = default

Default constructor.

Constructs a shared spin mutex that is in the no ownership state.

~shared_spin_mutex() = default
shared_spin_mutex(const shared_spin_mutex&) = delete

Copy constructor is DISABLED.

shared_spin_mutex &operator=(const shared_spin_mutex&) = delete

Copy assignment is DISABLED.

shared_spin_mutex(shared_spin_mutex&&) = delete

Move constructor is DIABLED.

shared_spin_mutex &operator=(shared_spin_mutex&&) = delete

Move assignment is DIABLED.

void lock()

Acquires exclusive ownership of the mutex.

This will put the mutex in the exclusive ownership case. If other threads have exclusive or shared ownership, this will wait until those threads are done

Uses a spin_backoff to spin while waiting for the ownership to be free. When exiting this function the mutex will be exclusively owned by the current thread.

An unlock() call must be made for each call to lock().

See

try_lock(), unlock(), lock_shared()

bool try_lock()

Tries to acquire exclusive ownership; returns false it fails the acquisition.

This is similar to

lock() but does not wait for the mutex to be free again. If the mutex is acquired by a different thread, or if the mutex has shared ownership this will return false.
Return

True if the mutex exclusive ownership was acquired; false if the mutex is busy

An unlock() call must be made for each call to this method that returns true.

See

lock(), unlock()

void unlock()

Releases the exclusive ownership on the mutex.

This needs to be called for every lock() and for every try_lock() that returns true. It should not be called without a matching lock() or try_lock().

See

lock(), try_lock()

void lock_shared()

Acquires shared ownership of the mutex.

This will put the mutex in the shared ownership case. If other threads have exclusive ownership, this will wait until those threads are done.

Uses a spin_backoff to spin while waiting for the ownership to be free. When exiting this function the mutex will be exclusively owned by the current thread.

An unlock_shared() call must be made for each call to lock().

See

try_lock_shared(), unlock_shared(), lock()

bool try_lock_shared()

Tries to acquire shared ownership; returns false it fails the acquisition.

This is similar to

lock_shared() but does not wait for the mutex to be free again. If the mutex is exclusively acquired by a different thread this will return false.
Return

True if the mutex shared ownership was acquired; false if the mutex is busy

An unlock_shared() call must be made for each call to this method that returns true.

See

lock_shared(), unlock_shared()

void unlock_shared()

Releases the sjared ownership on the mutex.

This needs to be called for every lock_shared() and for every try_lock_shared() that returns true. It should not be called without a matching lock_shared() or try_lock_shared().

See

lock_shared(), try_lock_shared()