summaryrefslogtreecommitdiffstats
path: root/util/include/axutil_thread.h
diff options
context:
space:
mode:
authorGravatar gmcdonald2010-02-13 01:32:03 +0000
committerGravatar gmcdonald2010-02-13 01:32:03 +0000
commit0425aadc78680e53000fd0108b540d6eca048516 (patch)
tree8ec7ab8e015d454c5ec586dfc91e05a2dce1cfc0 /util/include/axutil_thread.h
downloadaxis2c-0425aadc78680e53000fd0108b540d6eca048516.tar.gz
axis2c-0425aadc78680e53000fd0108b540d6eca048516.tar.bz2
Moving axis svn, part of TLP move INFRA-2441
git-svn-id: http://svn.apache.org/repos/asf/axis/axis2/c/core/trunk@909681 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'util/include/axutil_thread.h')
-rw-r--r--util/include/axutil_thread.h272
1 files changed, 272 insertions, 0 deletions
diff --git a/util/include/axutil_thread.h b/util/include/axutil_thread.h
new file mode 100644
index 0000000..271c2aa
--- /dev/null
+++ b/util/include/axutil_thread.h
@@ -0,0 +1,272 @@
+
+/*
+ * 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 */