Thread Mutex Routines

Overview

// typedefs

typedef struct apr_thread_mutex_t apr_thread_mutex_t;

// global 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_unlock(apr_thread_mutex_t* mutex);

apr_status_t
apr_thread_mutex_destroy(apr_thread_mutex_t* mutex);

apr_pool_t*
apr_thread_mutex_pool_get(const apr_thread_mutex_t* thethread_mutex);

// macros

#define APR_THREAD_MUTEX_DEFAULT
#define APR_THREAD_MUTEX_NESTED
#define APR_THREAD_MUTEX_UNNESTED

Detailed Documentation

Typedefs

typedef struct apr_thread_mutex_t apr_thread_mutex_t

Opaque thread-local mutex structure

Global Functions

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.

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.

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.

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

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_pool_t*
apr_thread_mutex_pool_get(const apr_thread_mutex_t* thethread_mutex)

Get the pool used by this thread_mutex.

Returns:

apr_pool_t the pool

Macros

#define APR_THREAD_MUTEX_DEFAULT

platform-optimal lock behavior

#define APR_THREAD_MUTEX_NESTED

enable nested (recursive) locks

#define APR_THREAD_MUTEX_UNNESTED

disable nested locks