pspinlock.h File Reference

Light-weight atomic spinlock. More...

#include <pmacros.h>
#include <ptypes.h>

Go to the source code of this file.

Typedefs
typedef struct PSpinLock_	PSpinLock
	Spinlock opaque data structure.

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

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.

Definition in file pspinlock.h.

Typedef Documentation

PSpinLock

typedef struct PSpinLock_ PSpinLock

Spinlock opaque data structure.

Definition at line 68 of file pspinlock.h.

Function Documentation

p_spinlock_free()

P_LIB_API void p_spinlock_free

(

PSpinLock *

spinlock

)

Frees PSpinLock object.

Parameters

spinlock

PSpinLock 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

spinlock

PSpinLock 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

spinlock

PSpinLock 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

spinlock

PSpinLock 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.