| |
| /* |
| * 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 <axutil_allocator.h> |
| #include <axutil_utils_defines.h> |
| #include <axutil_error.h> |
| |
| #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 */ |
