plibsys
Typedefs | Functions
pspinlock.h File Reference

Light-weight atomic spinlock. More...

#include <pmacros.h>
#include <ptypes.h>
Include dependency graph for pspinlock.h:

Go to the source code of this file.

Typedefs

typedef typedefP_BEGIN_DECLS struct PSpinLock_ PSpinLock
 Spinlock opaque data structure. More...
 

Functions

P_LIB_API PSpinLockp_spinlock_new (void)
 Creates a new PSpinLock object. More...
 
P_LIB_API pboolean p_spinlock_lock (PSpinLock *spinlock)
 Locks a spinlock. More...
 
P_LIB_API pboolean p_spinlock_trylock (PSpinLock *spinlock)
 Tries to lock a spinlock immediately. More...
 
P_LIB_API pboolean p_spinlock_unlock (PSpinLock *spinlock)
 Releases a locked spinlock. More...
 
P_LIB_API void p_spinlock_free (PSpinLock *spinlock)
 Frees PSpinLock object. More...
 

Detailed Description

Light-weight atomic spinlock.

Author
Alexander Saprykin

A spinlock is an inter-thread synchronization primitive based on atomic operations. It allows to guard a critical section from concurrent access of multiple threads at once. It is very similar to a mutex in semantics, but inside it provides a more light-weight and fast locking mechanism without thread sleeping and undesirable context switching. Thus spinlocks should be used only for small code sections, otherwise long-time spinning can cause extensive CPU time waste by waiting threads.

As the spinlock is based on atomic operations it would have the real meaning only if an underlying atomic model is lock-free (not simulated using the mutex). You can check if the atomic model is lock-free with p_atomic_is_lock_free(). Otherwise usage of spinlocks will be the same as the ordinary mutex.

To create a new spinlock primitive the p_spinlock_new() routine should be called, to delete the unused spinlock primitive use p_spinlock_free().

Use p_spinlock_lock() or p_spinlock_trylock() to synchronize access at the beginning of the critical section. Only the one thread is allowed to pass this call, others will wait for the p_spinlock_unlock() call which marks the end of the critical section. This way the critical section code is guarded against concurrent access of multiple threads at once.

Typedef Documentation

◆ PSpinLock

typedef typedefP_BEGIN_DECLS struct PSpinLock_ PSpinLock

Spinlock opaque data structure.

Function Documentation

◆ p_spinlock_free()

P_LIB_API void p_spinlock_free ( PSpinLock spinlock)

Frees PSpinLock object.

Parameters
spinlockPSpinLock to free.
Since
0.0.1

It doesn't unlock spinlock before freeing memory, so you should do it manually.

If the atomic model is not lock-free this call will have the same effect as p_mutex_free().

◆ p_spinlock_lock()

P_LIB_API pboolean p_spinlock_lock ( PSpinLock spinlock)

Locks a spinlock.

Parameters
spinlockPSpinLock to lock.
Returns
TRUE in case of success, FALSE otherwise.
Since
0.0.1

A thread will not sleep in this call if another thread is holding the lock, instead it will try to lock spinlock in an infinite loop.

If the atomic model is not lock-free this call will have the same effect as p_mutex_lock().

Do not lock a spinlock recursively - this may lead to an application deadlock.

◆ p_spinlock_new()

P_LIB_API PSpinLock* p_spinlock_new ( void  )

Creates a new PSpinLock object.

Returns
Pointer to a newly created PSpinLock object.
Since
0.0.1

◆ p_spinlock_trylock()

P_LIB_API pboolean p_spinlock_trylock ( PSpinLock spinlock)

Tries to lock a spinlock immediately.

Parameters
spinlockPSpinLock to lock.
Returns
TRUE in case of success, FALSE otherwise.
Since
0.0.1

Tries to lock spinlock and returns immediately if it is not available for locking.

If the atomic model is not lock-free this call will have the same effect as p_mutex_trylock().

Do not lock a spinlock recursively - this may lead to an application deadlock.

◆ p_spinlock_unlock()

P_LIB_API pboolean p_spinlock_unlock ( PSpinLock spinlock)

Releases a locked spinlock.

Parameters
spinlockPSpinLock to release.
Returns
TRUE in case of success, FALSE otherwise.
Since
0.0.1

If spinlock was previously locked then it becomes unlocked. Any thread can unlock any spinlock. It is also safe to call this routine on an unlocked spinlock.

If the atomic model is not lock-free this call will have the same effect as p_mutex_unlock(), thus it is not safe to call this routine on an unlocked spinlock.