# thread mutex routines
[utilities]

## Defines
#define | AXIS2_THREAD_MUTEX_DEFAULT 0x0
#define | AXIS2_THREAD_MUTEX_NESTED 0x1
#define | AXIS2_THREAD_MUTEX_UNNESTED 0x2
## Typedefs
typedef struct axutil_thread_mutex_t | axutil_thread_mutex_t
## Functions
AXIS2_EXTERN axutil_thread_mutex_t * | axutil_thread_mutex_create (axutil_allocator_t *allocator, unsigned int flags)
AXIS2_EXTERN axis2_status_t | axutil_thread_mutex_lock (axutil_thread_mutex_t *mutex)
AXIS2_EXTERN axis2_status_t | axutil_thread_mutex_trylock (axutil_thread_mutex_t *mutex)
AXIS2_EXTERN axis2_status_t | axutil_thread_mutex_unlock (axutil_thread_mutex_t *mutex)
AXIS2_EXTERN axis2_status_t | axutil_thread_mutex_destroy (axutil_thread_mutex_t *mutex)

## Define Documentation

#define AXIS2_THREAD_MUTEX_DEFAULT 0x0

platform-optimal lock behavior

#define AXIS2_THREAD_MUTEX_NESTED 0x1

enable nested (recursive) locks

#define AXIS2_THREAD_MUTEX_UNNESTED 0x2

disable nested locks

## Typedef Documentation

typedef struct axutil_thread_mutex_t axutil_thread_mutex_t

Opaque thread-local mutex structure

## Function Documentation

AXIS2_EXTERN axutil_thread_mutex_t* axutil_thread_mutex_create | ( | axutil_allocator_t * | allocator,
|  | unsigned int | flags |
| ) |  |  |

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

Parameters:

  | flags | Or'ed value of:
                 AXIS2_THREAD_MUTEX_DEFAULT   platform-optimal lock behavior.
                 AXIS2_THREAD_MUTEX_NESTED    enable nested (recursive) locks.
                 AXIS2_THREAD_MUTEX_UNNESTED  disable nested locks (non-recursive).
  | allocator | the allocator from which to allocate the mutex.

Returns:
  mutex the memory address where the newly created mutex will be stored.

Warning:
  Be cautious in using AXIS2_THREAD_MUTEX_DEFAULT. While this is the most optimial mutex based on a given platform's performance charateristics, it will behave as either a nested or an unnested lock.

AXIS2_EXTERN axis2_status_t axutil_thread_mutex_destroy | ( | axutil_thread_mutex_t * | mutex | ) |

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

Parameters:

  | mutex | the mutex to destroy.

AXIS2_EXTERN axis2_status_t axutil_thread_mutex_lock | ( | axutil_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.

AXIS2_EXTERN axis2_status_t axutil_thread_mutex_trylock | ( | axutil_thread_mutex_t * | mutex | ) |

Attempt to acquire the lock for the given mutex. If the mutex has already been acquired, the call returns immediately

Parameters:

  | mutex | the mutex on which to attempt the lock acquiring.

AXIS2_EXTERN axis2_status_t axutil_thread_mutex_unlock | ( | axutil_thread_mutex_t * | mutex | ) |

Release the lock for the given mutex.

Parameters:

  | mutex | the mutex from which to release the lock.