pmutex.h File Reference

Mutex routines. More...

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

Include dependency graph for pmutex.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef typedefP_BEGIN_DECLS struct PMutex_	PMutex
	Mutex opaque data structure. More...

Functions
P_LIB_API PMutex *	p_mutex_new (void)
	Creates a new PMutex object. More...
P_LIB_API pboolean	p_mutex_lock (PMutex *mutex)
	Locks a mutex. More...
P_LIB_API pboolean	p_mutex_trylock (PMutex *mutex)
	Tries to lock a mutex immediately. More...
P_LIB_API pboolean	p_mutex_unlock (PMutex *mutex)
	Releases a locked mutex. More...
P_LIB_API void	p_mutex_free (PMutex *mutex)
	Frees PMutex object. More...

Detailed Description

Mutex routines.

Author

Alexander Saprykin

A mutex is a mutual exclusive (hence mutex) synchronization primitive which allows access to a critical section only to one of the concurrently running threads. It is used to protected shared data structures from concurrent modifications which could lead to unpredictable behavior.

When entering a critical section a thread must call p_mutex_lock() to get a lock. If another thread is already holding the lock all other threads will be suspended until the lock is released with p_mutex_unlock(). After releasing the lock one of the waiting threads is resumed to continue execution. On most systems it is not specified whether a mutex waiting queue is fair (FIFO) or not.

The typical mutex usage:

p_mutex_lock (mutex);

... code in critical section ...

p_mutex_unlock (mutex);

You can also think of the mutex as a binary semaphore.

It is implementation dependent whether recursive locking or non-locked mutex unlocking is allowed, but such actions can lead to unpredictable behavior. Do not rely on such behavior in cross-platform applications.

This is the thread scoped mutex implementation. You could not share this mutex outside the process adress space, but you can share it between the threads of the same process.

Typedef Documentation

PMutex

typedef typedefP_BEGIN_DECLS struct PMutex_ PMutex

Mutex opaque data structure.

Function Documentation

p_mutex_free()

P_LIB_API void p_mutex_free

(

PMutex *

mutex

)

Frees PMutex object.

Parameters

mutex

PMutex to free.

Since

0.0.1

Warning

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

p_mutex_lock()

P_LIB_API pboolean p_mutex_lock

(

PMutex *

mutex

)

Locks a mutex.

Parameters

mutex

PMutex to lock.

Returns

TRUE in case of success, FALSE otherwise.

Since

0.0.1

Warning

Do not lock the mutex recursively - it may lead to an application deadlock (implementation dependent).

Forces the calling thread to sleep until mutex becomes available for locking.

p_mutex_new()

P_LIB_API PMutex* p_mutex_new

(

void

)

Creates a new PMutex object.

Returns

Pointer to a newly created PMutex object.

Since

0.0.1

p_mutex_trylock()

P_LIB_API pboolean p_mutex_trylock

(

PMutex *

mutex

)

Tries to lock a mutex immediately.

Parameters

mutex

PMutex to lock.

Returns

TRUE in case of success, FALSE otherwise.

Since

0.0.1

Warning

Do not lock the mutex recursively - it may lead to an application deadlock (implementation dependent).

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

p_mutex_unlock()

P_LIB_API pboolean p_mutex_unlock

(

PMutex *

mutex

)

Releases a locked mutex.

Parameters

mutex

PMutex to release.

Returns

TRUE in case of success, FALSE otherwise.

Since

0.0.1

Warning

Do not use this function on non-locked mutexes - behavior may be unpredictable.

If mutex was previously locked then it becomes unlocked.

It's implementation dependent whether only the same thread can lock and unlock the same mutex.