# thread
[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_t | axutil_thread_t
typedef struct axutil_threadattr_t | axutil_threadattr_t
typedef struct axutil_thread_once_t | axutil_thread_once_t
typedef void *(AXIS2_THREAD_FUNC * | axutil_thread_start_t )(axutil_thread_t *, void *)
typedef struct axutil_threadkey_t | axutil_threadkey_t
typedef struct axutil_thread_mutex_t | axutil_thread_mutex_t
## Functions
AXIS2_EXTERN axutil_threadattr_t * | axutil_threadattr_create (axutil_allocator_t *allocator)
AXIS2_EXTERN axis2_status_t | axutil_threadattr_detach_set (axutil_threadattr_t *attr, axis2_bool_t detached)
AXIS2_EXTERN axis2_bool_t | axutil_threadattr_is_detach (axutil_threadattr_t *attr, axutil_allocator_t *allocator)
AXIS2_EXTERN axutil_thread_t * | axutil_thread_create (axutil_allocator_t *allocator, axutil_threadattr_t *attr, axutil_thread_start_t func, void *data)
AXIS2_EXTERN axis2_status_t | axutil_thread_exit (axutil_thread_t *thd, axutil_allocator_t *allocator)
AXIS2_EXTERN axis2_status_t | axutil_thread_join (axutil_thread_t *thd)
AXIS2_EXTERN void | axutil_thread_yield (void)
AXIS2_EXTERN axutil_thread_once_t * | axutil_thread_once_init (axutil_allocator_t *allocator)
AXIS2_EXTERN axis2_status_t | axutil_thread_once (axutil_thread_once_t *control, void(*func)(void))
AXIS2_EXTERN axis2_status_t | axutil_thread_detach (axutil_thread_t *thd)
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

typedef struct axutil_thread_once_t axutil_thread_once_t

Control variable for one-time atomic variables.

typedef void*( AXIS2_THREAD_FUNC * axutil_thread_start_t)(axutil_thread_t *, void *)

The prototype for any AXIS2 thread worker functions.

typedef struct axutil_thread_t axutil_thread_t

Thread callbacks from axis2 functions must be declared with AXIS2_THREAD_FUNC so that they follow the platform's calling convention. Thread structure.

typedef struct axutil_threadattr_t axutil_threadattr_t

Thread attributes structure.

typedef struct axutil_threadkey_t axutil_threadkey_t

Thread private address space.

## Function Documentation

AXIS2_EXTERN axutil_thread_t* axutil_thread_create | ( | axutil_allocator_t * | allocator,
|  | axutil_threadattr_t * | attr,
|  | axutil_thread_start_t | func,
|  | void * | data |
| ) |  |  |

Create a new thread of execution

Parameters:

  | attr | The threadattr to use to determine how to create the thread
  | func | The function to start the new thread in
  | data | Any data to be passed to the starting function
  | cont | The pool to use

Returns:
  The newly created thread handle.

AXIS2_EXTERN axis2_status_t axutil_thread_detach | ( | axutil_thread_t * | thd | ) |

detach a thread

Parameters:

  | thd | The thread to detach

Returns:
  The status of the operation

AXIS2_EXTERN axis2_status_t axutil_thread_exit | ( | axutil_thread_t * | thd,
|  | axutil_allocator_t * | allocator |
| ) |  |  |

Stop the current thread

Parameters:

  | thd | The thread to stop

Returns:
  The status of the operation

AXIS2_EXTERN axis2_status_t axutil_thread_join | ( | axutil_thread_t * | thd | ) |

Block until the desired thread stops executing.

Parameters:

  | thd | The thread to join

Returns:
  The status of the operation

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:

  | allocator | Memory allocator to allocate memory for the mutex

Warning:
  Be cautious in using AXIS2_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.

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.

AXIS2_EXTERN axis2_status_t axutil_thread_once | ( | axutil_thread_once_t * | control,
|  | void(*)(void) | func |
| ) |  |  |

Run the specified function one time, regardless of how many threads call it.

Parameters:

  | control | The control variable. The same variable should be passed in each time the function is tried to be called. This is how the underlying functions determine if the function has ever been called before.
  | func | The function to call.

Returns:
  The status of the operation

AXIS2_EXTERN axutil_thread_once_t* axutil_thread_once_init | ( | axutil_allocator_t * | allocator | ) |

Initialize the control variable for axutil_thread_once.

Parameters:

  | control | The control variable to initialize

Returns:
  The status of the operation

AXIS2_EXTERN void axutil_thread_yield | ( | void |  | ) |

force the current thread to yield the processor

AXIS2_EXTERN axutil_threadattr_t* axutil_threadattr_create | ( | axutil_allocator_t * | allocator | ) |

Create and initialize a new threadattr variable

Parameters:

  | cont | The pool to use

Returns:
  Newly created thread attribute

AXIS2_EXTERN axis2_status_t axutil_threadattr_detach_set | ( | axutil_threadattr_t * | attr,
|  | axis2_bool_t | detached |
| ) |  |  |

Set if newly created threads should be created in detached state.

Parameters:

  | attr | The threadattr to affect
  | on | Non-zero if detached threads should be created.

Returns:
  The status of the operation

AXIS2_EXTERN axis2_bool_t axutil_threadattr_is_detach | ( | axutil_threadattr_t * | attr,
|  | axutil_allocator_t * | allocator |
| ) |  |  |

Get the detach state for this threadattr.

Parameters:

  | attr | The threadattr to reference

Returns:
  AXIS2_TRUE if threads are to be detached, or AXIS2_FALSE if threads are to be joinable.