/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef AXUTIL_THREAD_H #define AXUTIL_THREAD_H /** * @file axutil_thread.h * @brief axis2 thread api */ #include #include #include #ifdef __cplusplus extern "C" { #endif /** * @defgroup axutil_thread thread * @ingroup axis2_util * @{ */ /** * Thread callbacks from axis2 functions must be declared with AXIS2_THREAD_FUNC * so that they follow the platform's calling convention. */ /*#define AXIS2_THREAD_FUNC */ /** Thread structure. */ typedef struct axutil_thread_t axutil_thread_t; /** Thread attributes structure. */ typedef struct axutil_threadattr_t axutil_threadattr_t; /** Control variable for one-time atomic variables. */ typedef struct axutil_thread_once_t axutil_thread_once_t; /** * The prototype for any AXIS2 thread worker functions. */ typedef void *( AXIS2_THREAD_FUNC * axutil_thread_start_t)( axutil_thread_t *, void *); /** Thread private address space. */ typedef struct axutil_threadkey_t axutil_threadkey_t; /* Thread Function definitions */ /** * Create and initialize a new threadattr variable * @param cont The pool to use * @return Newly created thread attribute */ AXIS2_EXTERN axutil_threadattr_t *AXIS2_CALL axutil_threadattr_create( axutil_allocator_t * allocator); /** * Set if newly created threads should be created in detached state. * @param attr The threadattr to affect * @param on Non-zero if detached threads should be created. * @return The status of the operation */ AXIS2_EXTERN axis2_status_t AXIS2_CALL axutil_threadattr_detach_set( axutil_threadattr_t * attr, axis2_bool_t detached); /** * Get the detach state for this threadattr. * @param attr The threadattr to reference * @return AXIS2_TRUE if threads are to be detached, or AXIS2_FALSE * if threads are to be joinable. */ AXIS2_EXTERN axis2_bool_t AXIS2_CALL axutil_threadattr_is_detach( axutil_threadattr_t * attr, axutil_allocator_t * allocator); /** * Create a new thread of execution * @param attr The threadattr to use to determine how to create the thread * @param func The function to start the new thread in * @param data Any data to be passed to the starting function * @param cont The pool to use * @return The newly created thread handle. */ AXIS2_EXTERN axutil_thread_t *AXIS2_CALL axutil_thread_create( axutil_allocator_t * allocator, axutil_threadattr_t * attr, axutil_thread_start_t func, void *data); /** * Stop the current thread * @param thd The thread to stop * @return The status of the operation */ AXIS2_EXTERN axis2_status_t AXIS2_CALL axutil_thread_exit( axutil_thread_t * thd, axutil_allocator_t * allocator); /** * Block until the desired thread stops executing. * @param thd The thread to join * @return The status of the operation */ AXIS2_EXTERN axis2_status_t AXIS2_CALL axutil_thread_join( axutil_thread_t * thd); /** * force the current thread to yield the processor */ AXIS2_EXTERN void AXIS2_CALL axutil_thread_yield(void ); /** * function is used to allocate a new key. This key now becomes valid for all threads in our process. * When a key is created, the value it points to defaults to NULL. Later on each thread may change * its copy of the value as it wishes. */ AXIS2_EXTERN axis2_status_t AXIS2_CALL axutil_thread_key_create( axutil_threadkey_t * axis2_key); /** * This function is used to get the value of a given key * @return void*. A key's value is simply a void pointer (void*) */ AXIS2_EXTERN void *AXIS2_CALL axutil_thread_getspecific( axutil_threadkey_t * axis2_key); /** * This function is used to get the value of a given key * @param keys value. A key's value is simply a void pointer (void*), so we can * store in it anything that we want */ AXIS2_EXTERN axis2_status_t AXIS2_CALL axutil_thread_setspecific( axutil_threadkey_t * axis2_key, void *value); /** * This function is used free the tls key. */ AXIS2_EXTERN void AXIS2_CALL axutil_thread_key_free( axutil_threadkey_t * axis2_key); /** * Initialize the control variable for axutil_thread_once. * @param control The control variable to initialize * @return The status of the operation */ AXIS2_EXTERN axutil_thread_once_t *AXIS2_CALL axutil_thread_once_init( axutil_allocator_t * allocator); /** * Run the specified function one time, regardless of how many threads * call it. * @param 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. * @param func The function to call. * @return The status of the operation */ AXIS2_EXTERN axis2_status_t AXIS2_CALL axutil_thread_once( axutil_thread_once_t * control, void(*func)(void)); /** * detach a thread * @param thd The thread to detach * @return The status of the operation */ AXIS2_EXTERN axis2_status_t AXIS2_CALL axutil_thread_detach( axutil_thread_t * thd); /*************************Thread locking functions*****************************/ /** Opaque thread-local mutex structure */ typedef struct axutil_thread_mutex_t axutil_thread_mutex_t; #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 */ /** * Create and initialize a mutex that can be used to synchronize threads. * @param 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 axutil_thread_mutex_t *AXIS2_CALL axutil_thread_mutex_create( axutil_allocator_t * allocator, unsigned int flags); /** * 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. * @param mutex the mutex on which to acquire the lock. */ AXIS2_EXTERN axis2_status_t AXIS2_CALL axutil_thread_mutex_lock( 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 * @param mutex the mutex on which to attempt the lock acquiring. */ AXIS2_EXTERN axis2_status_t AXIS2_CALL axutil_thread_mutex_trylock( axutil_thread_mutex_t * mutex); /** * Release the lock for the given mutex. * @param mutex the mutex from which to release the lock. */ AXIS2_EXTERN axis2_status_t AXIS2_CALL axutil_thread_mutex_unlock( axutil_thread_mutex_t * mutex); /** * Destroy the mutex and free the memory associated with the lock. * @param mutex the mutex to destroy. */ AXIS2_EXTERN axis2_status_t AXIS2_CALL axutil_thread_mutex_destroy( axutil_thread_mutex_t * mutex); /** @} */ #ifdef __cplusplus } #endif #endif /* AXIS2_THREAD_H */