Thread Mutex Routines

Collaboration diagram for Thread Mutex Routines:

Macros
#define	APR_THREAD_MUTEX_DEFAULT   0x0
#define	APR_THREAD_MUTEX_NESTED   0x1
#define	APR_THREAD_MUTEX_UNNESTED   0x2
#define	APR_THREAD_MUTEX_TIMED   0x4

Typedefs
typedef struct apr_thread_mutex_t	apr_thread_mutex_t

Functions
apr_status_t	apr_thread_mutex_create (apr_thread_mutex_t **mutex, unsigned int flags, apr_pool_t *pool)
apr_status_t	apr_thread_mutex_lock (apr_thread_mutex_t *mutex)
apr_status_t	apr_thread_mutex_trylock (apr_thread_mutex_t *mutex)
apr_status_t	apr_thread_mutex_timedlock (apr_thread_mutex_t *mutex, apr_interval_time_t timeout)
apr_status_t	apr_thread_mutex_unlock (apr_thread_mutex_t *mutex)
apr_status_t	apr_thread_mutex_destroy (apr_thread_mutex_t *mutex)
	APR_POOL_DECLARE_ACCESSOR (thread_mutex)

Detailed Description

Macro Definition Documentation

APR_THREAD_MUTEX_DEFAULT

#define APR_THREAD_MUTEX_DEFAULT   0x0

platform-optimal lock behavior

APR_THREAD_MUTEX_NESTED

#define APR_THREAD_MUTEX_NESTED   0x1

enable nested (recursive) locks

APR_THREAD_MUTEX_TIMED

#define APR_THREAD_MUTEX_TIMED   0x4

enable timed locks

APR_THREAD_MUTEX_UNNESTED

#define APR_THREAD_MUTEX_UNNESTED   0x2

disable nested locks

Typedef Documentation

apr_thread_mutex_t

typedef struct apr_thread_mutex_t apr_thread_mutex_t

Opaque thread-local mutex structure

Function Documentation

APR_POOL_DECLARE_ACCESSOR()

APR_POOL_DECLARE_ACCESSOR

(

thread_mutex

)

Get the pool used by this thread_mutex.

Returns

apr_pool_t the pool

apr_thread_mutex_create()

apr_status_t apr_thread_mutex_create	(	apr_thread_mutex_t **	mutex,
		unsigned int	flags,
		apr_pool_t *	pool
	)

Create and initialize a mutex that can be used to synchronize threads.

Parameters

mutex	the memory address where the newly created mutex will be stored.
flags	Or'ed value of: APR_THREAD_MUTEX_DEFAULT platform-optimal lock behavior. APR_THREAD_MUTEX_NESTED enable nested (recursive) locks. APR_THREAD_MUTEX_UNNESTED disable nested locks (non-recursive).
pool	the pool from which to allocate the mutex.

Warning

Be cautious in using APR_THREAD_MUTEX_DEFAULT. While this is the most optimal mutex based on a given platform's performance characteristics, it will behave as either a nested or an unnested lock.

apr_thread_mutex_destroy()

apr_status_t apr_thread_mutex_destroy

(

apr_thread_mutex_t *

mutex

)

Destroy the mutex and free the memory associated with the lock.

Parameters

mutex

the mutex to destroy.

apr_thread_mutex_lock()

apr_status_t apr_thread_mutex_lock

(

apr_thread_mutex_t *

mutex

)

Acquire the lock for the given mutex. If the mutex is already locked, the current thread will be put to sleep until the lock becomes available.

Parameters

mutex

the mutex on which to acquire the lock.

apr_thread_mutex_timedlock()

apr_status_t apr_thread_mutex_timedlock	(	apr_thread_mutex_t *	mutex,
		apr_interval_time_t	timeout
	)

Attempt to acquire the lock for the given mutex until timeout expires. If the acquisition time outs, the call returns with APR_TIMEUP.

Parameters

mutex	the mutex on which to attempt the lock acquiring.
timeout	the relative timeout (microseconds).

Note

A timeout negative or nul means immediate attempt, returning APR_TIMEUP without blocking if it the lock is already acquired.

apr_thread_mutex_trylock()

apr_status_t apr_thread_mutex_trylock

(

apr_thread_mutex_t *

mutex

)

Attempt to acquire the lock for the given mutex. If the mutex has already been acquired, the call returns immediately with APR_EBUSY. Note: it is important that the APR_STATUS_IS_EBUSY(s) macro be used to determine if the return value was APR_EBUSY, for portability reasons.

Parameters

mutex

the mutex on which to attempt the lock acquiring.

apr_thread_mutex_unlock()

apr_status_t apr_thread_mutex_unlock

(

apr_thread_mutex_t *

mutex

)

Release the lock for the given mutex.

Parameters

mutex

the mutex from which to release the lock.