diff options
Diffstat (limited to 'ace/Thread.h')
| -rw-r--r-- | ace/Thread.h | 237 |
1 files changed, 124 insertions, 113 deletions
diff --git a/ace/Thread.h b/ace/Thread.h index 0f76790c930..9473d3ab498 100644 --- a/ace/Thread.h +++ b/ace/Thread.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Thread.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Thread.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_THREAD_H #define ACE_THREAD_H @@ -25,19 +22,50 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Thread + * + * @brief Provides a wrapper for threads. + * + * This class provides a common interface that is mapped onto + * POSIX Pthreads, Solaris threads, Win32 threads, VxWorks + * threads, or pSoS threads. Note, however, that it is + * generally a better idea to use the <ACE_Thread_Manager> + * programming API rather than the <ACE_Thread> API since the + * thread manager is more powerful. + */ class ACE_Export ACE_Thread { - // = TITLE - // Provides a wrapper for threads. - // - // = DESCRIPTION - // This class provides a common interface that is mapped onto - // POSIX Pthreads, Solaris threads, Win32 threads, VxWorks - // threads, or pSoS threads. Note, however, that it is - // generally a better idea to use the <ACE_Thread_Manager> - // programming API rather than the <ACE_Thread> API since the - // thread manager is more powerful. public: + /** + * Creates a new thread having <flags> attributes and running <func> + * with <args> (if <thread_adapter> is non-0 then <func> and <args> + * are ignored and are obtained from <thread_adapter>). <thr_id> + * and <t_handle> are set to the thread's ID and handle (?), + * respectively. The thread runs at <priority> priority (see + * below). + * + * The <flags> are a bitwise-OR of the following: + * = BEGIN<INDENT> + * THR_CANCEL_DISABLE, THR_CANCEL_ENABLE, THR_CANCEL_DEFERRED, + * THR_CANCEL_ASYNCHRONOUS, THR_BOUND, THR_NEW_LWP, THR_DETACHED, + * THR_SUSPENDED, THR_DAEMON, THR_JOINABLE, THR_SCHED_FIFO, + * THR_SCHED_RR, THR_SCHED_DEFAULT + * = END<INDENT> + * + * By default, or if <priority> is set to + * ACE_DEFAULT_THREAD_PRIORITY, an "appropriate" priority value for + * the given scheduling policy (specified in <flags}>, e.g., + * <THR_SCHED_DEFAULT>) is used. This value is calculated + * dynamically, and is the median value between the minimum and + * maximum priority values for the given policy. If an explicit + * value is given, it is used. Note that actual priority values are + * EXTREMEMLY implementation-dependent, and are probably best + * avoided. + * + * Note that <thread_adapter> is always deleted by <thr_create>, + * therefore it must be allocated with global operator new. + */ static int spawn (ACE_THR_FUNC func, void *arg = 0, long flags = THR_NEW_LWP | THR_JOINABLE, @@ -47,34 +75,21 @@ public: void *stack = 0, size_t stack_size = 0, ACE_Thread_Adapter *thread_adapter = 0); - // Creates a new thread having <flags> attributes and running <func> - // with <args> (if <thread_adapter> is non-0 then <func> and <args> - // are ignored and are obtained from <thread_adapter>). <thr_id> - // and <t_handle> are set to the thread's ID and handle (?), - // respectively. The thread runs at <priority> priority (see - // below). - // - // The <flags> are a bitwise-OR of the following: - // = BEGIN<INDENT> - // THR_CANCEL_DISABLE, THR_CANCEL_ENABLE, THR_CANCEL_DEFERRED, - // THR_CANCEL_ASYNCHRONOUS, THR_BOUND, THR_NEW_LWP, THR_DETACHED, - // THR_SUSPENDED, THR_DAEMON, THR_JOINABLE, THR_SCHED_FIFO, - // THR_SCHED_RR, THR_SCHED_DEFAULT - // = END<INDENT> - // - // By default, or if <priority> is set to - // ACE_DEFAULT_THREAD_PRIORITY, an "appropriate" priority value for - // the given scheduling policy (specified in <flags}>, e.g., - // <THR_SCHED_DEFAULT>) is used. This value is calculated - // dynamically, and is the median value between the minimum and - // maximum priority values for the given policy. If an explicit - // value is given, it is used. Note that actual priority values are - // EXTREMEMLY implementation-dependent, and are probably best - // avoided. - // - // Note that <thread_adapter> is always deleted by <thr_create>, - // therefore it must be allocated with global operator new. + /** + * Spawn N new threads, which execute <func> with argument <arg> (if + * <thread_adapter> is non-0 then <func> and <args> are ignored and + * are obtained from <thread_adapter>). If <stack> != 0 it is + * assumed to be an array of <n> pointers to the base of the stacks + * to use for the threads being spawned. Likewise, if <stack_size> + * != 0 it is assumed to be an array of <n> values indicating how + * big each of the corresponding <stack>s are. Returns the number + * of threads actually spawned (if this doesn't equal the number + * requested then something has gone wrong and <errno> will + * explain...). + * + * See also <spawn>. + */ static int spawn_n (size_t n, ACE_THR_FUNC func, void *arg = 0, @@ -83,19 +98,25 @@ public: void *stack[] = 0, size_t stack_size[] = 0, ACE_Thread_Adapter *thread_adapter = 0); - // Spawn N new threads, which execute <func> with argument <arg> (if - // <thread_adapter> is non-0 then <func> and <args> are ignored and - // are obtained from <thread_adapter>). If <stack> != 0 it is - // assumed to be an array of <n> pointers to the base of the stacks - // to use for the threads being spawned. Likewise, if <stack_size> - // != 0 it is assumed to be an array of <n> values indicating how - // big each of the corresponding <stack>s are. Returns the number - // of threads actually spawned (if this doesn't equal the number - // requested then something has gone wrong and <errno> will - // explain...). - // - // See also <spawn>. + /** + * Spawn <n> new threads, which execute <func> with argument <arg> + * (if <thread_adapter> is non-0 then <func> and <args> are ignored + * and are obtained from <thread_adapter>). The thread_ids of + * successfully spawned threads will be placed into the <thread_ids> + * buffer (which must be the same size as <n>). If <stack> != 0 it + * is assumed to be an array of <n> pointers to the base of the + * stacks to use for the threads being spawned. If <stack_size> != + * 0 it is assumed to be an array of <n> values indicating how big + * each of the corresponding <stack>s are. If <thread_handles> != 0 + * it is assumed to be an array of <n> thread_handles that will be + * assigned the values of the thread handles being spawned. Returns + * the number of threads actually spawned (if this doesn't equal the + * number requested then something has gone wrong and <errno> will + * explain...). + * + * See also <spawn>. + */ static int spawn_n (ACE_thread_t thread_ids[], size_t n, ACE_THR_FUNC func, @@ -106,73 +127,59 @@ public: size_t stack_size[] = 0, ACE_hthread_t thread_handles[] = 0, ACE_Thread_Adapter *thread_adapter = 0); - // Spawn <n> new threads, which execute <func> with argument <arg> - // (if <thread_adapter> is non-0 then <func> and <args> are ignored - // and are obtained from <thread_adapter>). The thread_ids of - // successfully spawned threads will be placed into the <thread_ids> - // buffer (which must be the same size as <n>). If <stack> != 0 it - // is assumed to be an array of <n> pointers to the base of the - // stacks to use for the threads being spawned. If <stack_size> != - // 0 it is assumed to be an array of <n> values indicating how big - // each of the corresponding <stack>s are. If <thread_handles> != 0 - // it is assumed to be an array of <n> thread_handles that will be - // assigned the values of the thread handles being spawned. Returns - // the number of threads actually spawned (if this doesn't equal the - // number requested then something has gone wrong and <errno> will - // explain...). - // - // See also <spawn>. + /// Wait for one or more threads to exit. static int join (ACE_thread_t, ACE_thread_t *, void **status = 0); - // Wait for one or more threads to exit. + /// Wait for one thread to exit. static int join (ACE_hthread_t, void ** = 0); - // Wait for one thread to exit. + /// Continue the execution of a previously suspended thread. static int resume (ACE_hthread_t); - // Continue the execution of a previously suspended thread. + /// Suspend the execution of a particular thread. static int suspend (ACE_hthread_t); - // Suspend the execution of a particular thread. + /// Get the priority of a particular thread. static int getprio (ACE_hthread_t, int &prio); - // Get the priority of a particular thread. + /// Set the priority of a particular thread. static int setprio (ACE_hthread_t, int prio); - // Set the priority of a particular thread. + /// Send a signal to the thread. static int kill (ACE_thread_t, int signum); - // Send a signal to the thread. + /// Yield the thread to another. static void yield (void); - // Yield the thread to another. + /** + * Return the unique kernel handle of the thread. Note that on + * Win32 this is actually a pseudohandle, which cannot be shared + * with other processes or waited on by threads. To locate the real + * handle, please use the <ACE_Thread_Manager::thr_self> method. + */ static void self (ACE_hthread_t &t_handle); - // Return the unique kernel handle of the thread. Note that on - // Win32 this is actually a pseudohandle, which cannot be shared - // with other processes or waited on by threads. To locate the real - // handle, please use the <ACE_Thread_Manager::thr_self> method. + /// Return the unique ID of the thread. static ACE_thread_t self (void); - // Return the unique ID of the thread. + /// Exit the current thread and return "status". + /// Should _not_ be called by main thread. static void exit (void *status = 0); - // Exit the current thread and return "status". - // Should _not_ be called by main thread. + /// Get the LWP concurrency level of the process. static int getconcurrency (void); - // Get the LWP concurrency level of the process. + /// Set the LWP concurrency level of the process. static int setconcurrency (int new_level); - // Set the LWP concurrency level of the process. + /// Change and/or examine calling thread's signal mask. static int sigsetmask (int how, const sigset_t *sigset, sigset_t *osigset = 0); - // Change and/or examine calling thread's signal mask. static int keycreate (ACE_thread_key_t *keyp, #if defined (ACE_HAS_THR_C_DEST) @@ -180,46 +187,50 @@ public: #else ACE_THR_DEST destructor, #endif /* ACE_HAS_THR_C_DEST */ + /** + * Allocates a <keyp> that is used to identify data that is specific + * to each thread in the process. The key is global to all threads + * in the process. + */ void * = 0); - // Allocates a <keyp> that is used to identify data that is specific - // to each thread in the process. The key is global to all threads - // in the process. + /// Free up the key so that other threads can reuse it. static int keyfree (ACE_thread_key_t key); - // Free up the key so that other threads can reuse it. + /// Bind value to the thread-specific data key, <key>, for the calling + /// thread. static int setspecific (ACE_thread_key_t key, void *value); - // Bind value to the thread-specific data key, <key>, for the calling - // thread. + /// Stores the current value bound to <key> for the calling thread + /// into the location pointed to by <valuep>. static int getspecific (ACE_thread_key_t key, void **valuep); - // Stores the current value bound to <key> for the calling thread - // into the location pointed to by <valuep>. + /// Disable thread cancellation. static int disablecancel (struct cancel_state *old_state); - // Disable thread cancellation. + /// Enable thread cancellation. static int enablecancel (struct cancel_state *old_state, int flag); - // Enable thread cancellation. + /// Set the cancellation state. static int setcancelstate (struct cancel_state &new_state, struct cancel_state *old_state); - // Set the cancellation state. + /** + * Cancel a thread. Note that this method is only portable on + * platforms, such as POSIX pthreads, that support thread + * cancellation. + */ static int cancel (ACE_thread_t t_id); - // Cancel a thread. Note that this method is only portable on - // platforms, such as POSIX pthreads, that support thread - // cancellation. + /// Test the cancel. static void testcancel (void); - // Test the cancel. private: + /// Ensure that we don't get instantiated. ACE_Thread (void); - // Ensure that we don't get instantiated. }; #if defined (__ACE_INLINE__) |