diff options
author | Steve Huston <shuston@riverace.com> | 2008-05-14 20:42:15 +0000 |
---|---|---|
committer | Steve Huston <shuston@riverace.com> | 2008-05-14 20:42:15 +0000 |
commit | d42e391f93c8409389a72e06c060d4b04608ce70 (patch) | |
tree | ebb20e23d1cb37453e3ee07e89593e07330bf943 | |
parent | c095ecd788ef75435a89482bdb371c5cfa4c6f02 (diff) | |
download | ATCD-d42e391f93c8409389a72e06c060d4b04608ce70.tar.gz |
ChangeLogTag:Wed May 14 20:41:17 2008 Steve Huston <shuston@riverace.com>
-rw-r--r-- | ACE/ChangeLog | 5 | ||||
-rw-r--r-- | ACE/ace/Thread_Manager.h | 270 |
2 files changed, 204 insertions, 71 deletions
diff --git a/ACE/ChangeLog b/ACE/ChangeLog index 3d7555284df..89190d16265 100644 --- a/ACE/ChangeLog +++ b/ACE/ChangeLog @@ -1,3 +1,8 @@ +Wed May 14 20:41:17 2008 Steve Huston <shuston@riverace.com> + + * ace/Thread_Manager.h: Expanded the documentation, particularly for + spawn[_n]. + Wed May 14 18:30:15 UTC 2008 Johnny Willemsen <jwillemsen@remedy.nl> * ace/config-irix6.x-common.h: diff --git a/ACE/ace/Thread_Manager.h b/ACE/ace/Thread_Manager.h index bccfab12e1e..f11c638060e 100644 --- a/ACE/ace/Thread_Manager.h +++ b/ACE/ace/Thread_Manager.h @@ -368,13 +368,13 @@ typedef int (ACE_Thread_Manager::*ACE_THR_MEMBER_FUNC)(ACE_Thread_Descriptor *, * all threads under it's management when it gets destructed. * Therefore, remember to remove a thread from thread manager if * you don't want it to wait for the thread. There are also - * function to disable this default wait-on-exit behavior. + * functions to disable this default wait-on-exit behavior. * However, if your program depends on turning this off to run * correctly, you are probably doing something wrong. Rule of * thumb, use ACE_Thread to manage your daemon threads. - * Notice that if there're threads live beyond the scope of - * <main>, you are sure to have resource leaks in your program. - * Remember to wait on threads before exiting <main> if that + * Notice that if there're threads which live beyond the scope of + * main(), you are sure to have resource leaks in your program. + * Remember to wait on threads before exiting your main program if that * could happen in your programs. */ class ACE_Export ACE_Thread_Manager @@ -419,7 +419,6 @@ public: ACE_THR_JOINING = 0x10000000 }; - // = Initialization and termination methods. /** * @brief Initialization and termination methods. * @@ -454,22 +453,68 @@ public: /** * Release all resources. - * By default, this method will wait till all threads - * exit. However, when called from <close_singleton>, most global resources - * are destroyed and thus, we don't try to wait but just clean up the thread - * descriptor list. + * By default, this method will wait until all threads exit. + * However, when called from close_singleton(), most global resources + * are destroyed and thus, close() does not try to wait; it simply cleans + * up internal thread records (the thread descriptor list). */ int close (void); /** * Create a new thread, which executes @a func with argument @a arg. - * Returns: on success a unique group id that can be used to control - * other threads added to the same group. On failure, returns -1. + * + * @param func The function that is called in the spawned thread. + * + * @param arg The value passed to each spawned thread's @a func. + * + * @param flags Flags to control attributes of the spawned threads. + * @sa ACE_OS::thr_create() for descriptions of the + * possible flags values and their interactions. + * + * @param t_id Pointer to a location to receive the spawned thread's + * ID. If 0, the ID is not returned. + * + * @param t_handle Pointer to a location to receive the spawned thread's + * thread handle. If 0, the handle is not returned. + * + * @param priority The priority at which the thread is spawned. + * + * @param grp_id The thread group that the spawned thread is + * added to. If -1 is specified, a new thread group is + * created for the spawned thread. + * + * @param stack Pointers to the base of a pre-allocated stack space + * for the thread's stack. If 0, the platform allocates + * stack space for the thread. If a stack is specified, + * it is recommended that @a stack_size also be supplied + * to specify the size of the stack. + * Not all platforms support pre-allocated stacks. If + * @a stack is specified for a platform which does not + * allow pre-allocated stack space this parameter is + * ignored. + * + * @param stack_size Indicate how large the thread's stack should be, in + * bytes. If a pre-allocated stack pointer is passed in + * @a stack, @a stack_size indicates the size of that + * stack area. If no pre-allocated stack is passed, + * the stack size specified is passed to the + * operating system to request that it allocate a stack + * of the specified size. + * + * @param thr_name Pointer to a name to assign to the spawned thread. + * This is only meaningful for platforms that have a + * capacity to name threads (e.g., VxWorks and some + * varieties of Pthreads). This argument is ignored if + * specified as 0 and on platforms that do not have the + * capability to name threads. + * + * @retval -1 on failure; @c errno contains an error value. + * @retval The group id of the spawned thread. */ int spawn (ACE_THR_FUNC func, void *arg = 0, long flags = THR_NEW_LWP | THR_JOINABLE | THR_INHERIT_SCHED, - ACE_thread_t * = 0, + ACE_thread_t *t_id = 0, ACE_hthread_t *t_handle = 0, long priority = ACE_DEFAULT_THREAD_PRIORITY, int grp_id = -1, @@ -478,33 +523,69 @@ public: const char** thr_name = 0); /** - * Spawn N new threads, which execute @a func with argument @a arg. - * If <thread_ids> != 0 the thread_ids of successfully spawned - * threads will be placed into the <thread_ids> buffer (which must - * be the same size as @a n). If @a stack != 0 it is assumed to be an - * array of @a n pointers to the base of the stacks to use for the - * threads being spawned. If @a stack_size != 0 it is assumed to be - * an array of @a n values indicating how big each of the - * corresponding @a stacks are. If @a thread_handles != 0 it is - * assumed to be an array of @a n thread_handles that will be - * assigned the values of the thread handles being spawned. + * Spawn a specified number of threads, all of which execute @a func + * with argument @a arg. * - * Threads in Thread_Manager can be manipulated in groups based on - * @a grp_id or @a task using functions such as kill_grp() or - * cancel_task(). + * @param n The number of threads to spawn. * - * If @a grp_id is assigned, the newly spawned threads are added into - * the group. Otherwise, the Thread_Manager assigns these @a n - * threads with a grp_id. You should choose either assigning - * @a grp_id everytime, or let the Thread_Manager handles it for - * you consistently. + * @param func The function that is called in the spawned thread. * - * The argument @a task is usually assigned by - * <ACE_Task_Base::activate>. It associates the newly spawned - * threads with an ACE_Task instance, which defaults to @c this. + * @param arg The value passed to each spawned thread's @a func. * - * @retval -1 on failure (@c errno will explain...), otherwise returns the - * group id of the threads. + * @param flags Flags to control attributes of the spawned threads. + * @sa ACE_OS::thr_create() for descriptions of the + * possible flags values and their interactions. + * + * @param priority The priority at which the threads are spawned. + * + * @param grp_id The thread group that the spawned threads are + * added to. If -1 is specified, a new thread group is + * created for the spawned threads. + * + * @param task The ACE_Task that the spawned threads are associated + * with. If 0, the threads are not associated with an + * ACE_Task. This argument is usually assigned by the + * ACE_Task_Base::activate() method to associate the + * spawned threads with the spawning ACE_Task object. + * + * @param thread_handles An array of @a n entries which will receive + * the thread handles of the spawned threads. + * + * @param stack An array of @a n pointers to pre-allocated stack space + * for each thread's stack. If specified as 0, the + * platform allocates stack space for each thread. If + * a stack is specified, it is recommended that a + * @a stack_size element also be supplied that specifies + * the size of the stack. + * Not all platforms support pre-allocated stacks. If + * @a stack is specified for a platform which does not + * allow pre-allocated stack space this parameter is + * ignored. + * + * @param stack_size An array of @a n values which indicate how large + * each thread's stack should be, in bytes. + * If pre-allocated stacks are passed in @a stacks, these + * sizes are for those stacks. If no pre-allocated stacks + * are passed, the stack sizes are specified to the + * operating system to request that it allocate stacks + * of the specified sizes. If an array entry is 0, the + * platform defaults are used for the corresponding thread. + * If a 0 array pointer is specified, platform defaults + * are used for all thread stack sizes. + * + * @param thr_name An array of names to assign to the spawned threads. + * This is only meaningful for platforms that have a + * capacity to name threads (e.g., VxWorks and some + * varieties of Pthreads). This argument is ignored if + * specified as 0 and on platforms that do not have the + * capability to name threads. + * + * ACE_Thread_Manager can manipulate threads in groups based on + * @a grp_id or @a task using functions such as kill_grp() or + * cancel_task(). + * + * @retval -1 on failure; @c errno contains an error value. + * @retval The group id of the threads. */ int spawn_n (size_t n, ACE_THR_FUNC func, @@ -519,33 +600,74 @@ public: const char* thr_name[] = 0); /** - * Spawn N new threads, which execute @a func with argument @a arg. - * If <thread_ids> != 0 the thread_ids of successfully spawned - * threads will be placed into the <thread_ids> buffer (which must - * be the same size as @a n). If @a stack != 0 it is assumed to be an - * array of @a n pointers to the base of the stacks to use for the - * threads being spawned. If @a stack_size != 0 it is assumed to be - * an array of @a n values indicating how big each of the - * corresponding @a stacks are. If @a thread_handles != 0 it is - * assumed to be an array of @a n thread_handles that will be - * assigned the values of the thread handles being spawned. + * Spawn a specified number of threads, all of which execute @a func + * with argument @a arg. * - * Threads in Thread_Manager can be manipulated in groups based on - * @a grp_id or @a task using functions such as kill_grp() or - * cancel_task(). + * @param thread_ids An array to receive the thread IDs of successfully + * spawned buffer. If 0, the thread IDs are not returned. + * If specified, the array must be at least @a n entries. + * + * @param n The number of threads to spawn. + * + * @param func The function that is called in the spawned thread. + * + * @param arg The value passed to each spawned thread's @a func. + * + * @param flags Flags to control attributes of the spawned threads. + * @sa ACE_OS::thr_create() for descriptions of the + * possible flags values and their interactions. + * + * @param priority The priority at which the threads are spawned. * - * If @a grp_id is assigned, the newly spawned threads are added into - * the group. Otherwise, the Thread_Manager assigns these @a n - * threads with a grp_id. You should choose either assigning - * @a grp_id everytime, or let the Thread_Manager handles it for - * you consistently. + * @param grp_id The thread group that the spawned threads are + * added to. If -1 is specified, a new thread group is + * created for the spawned threads. * - * The argument @a task is usually assigned by - * <ACE_Task_Base::activate>. It associates the newly spawned - * threads with an ACE_Task instance, which defaults to @c this. + * @param stack An array of @a n pointers to pre-allocated stack space + * for each thread's stack. If specified as 0, the + * platform allocates stack space for each thread. If + * a stack is specified, it is recommended that a + * @a stack_size element also be supplied that specifies + * the size of the stack. + * Not all platforms support pre-allocated stacks. If + * @a stack is specified for a platform which does not + * allow pre-allocated stack space this parameter is + * ignored. + * + * @param stack_size An array of @a n values which indicate how large + * each thread's stack should be, in bytes. + * If pre-allocated stacks are passed in @a stacks, these + * sizes are for those stacks. If no pre-allocated stacks + * are passed, the stack sizes are specified to the + * operating system to request that it allocate stacks + * of the specified sizes. If an array entry is 0, the + * platform defaults are used for the corresponding thread. + * If a 0 array pointer is specified, platform defaults + * are used for all thread stack sizes. + * + * @param thread_handles An array of @a n entries which will receive + * the thread handles of the spawned threads. + * + * @param task The ACE_Task that the spawned threads are associated + * with. If 0, the threads are not associated with an + * ACE_Task. This argument is usually assigned by the + * ACE_Task_Base::activate() method to associate the + * spawned threads with the spawning ACE_Task object. + * + * @param thr_name An array of names to assign to the spawned threads. + * This is only meaningful for platforms that have a + * capacity to name threads (e.g., VxWorks and some + * varieties of Pthreads). This argument is ignored if + * specified as 0 and on platforms that do not have the + * capability to name threads. + * + * ACE_Thread_Manager can manipulate threads in groups based on + * @a grp_id or @a task using functions such as kill_grp() or + * cancel_task(). * - * @retval -1 on failure (@c errno will explain...), otherwise returns the - * group id of the threads. + * @retval -1 on failure; @c errno contains an error value. + * @retval The group id of the threads. + */ int spawn_n (ACE_thread_t thread_ids[], size_t n, @@ -620,7 +742,7 @@ public: /** * Return the "real" handle to the calling thread, caching it if * necessary in TSS to speed up subsequent lookups. This is - * necessary since on some platforms (e.g., Win32) we can't get this + * necessary since on some platforms (e.g., Windows) we can't get this * handle via direct method calls. Notice that you should *not* * close the handle passed back from this method. It is used * internally by Thread Manager. On the other hand, you *have to* @@ -630,9 +752,8 @@ public: int thr_self (ACE_hthread_t &); /** - * Return the unique ID of the thread. This is not strictly - * necessary (because a thread can always just call - * <ACE_Thread::self>). However, we put it here to be complete. + * Return the unique ID of the calling thread. + * Same as calling ACE_Thread::self(). */ ACE_thread_t thr_self (void); @@ -643,7 +764,14 @@ public: */ ACE_Task_Base *task (void); - // = Suspend methods, which isn't supported on POSIX pthreads (will not block). + /** + * @name Suspend and resume methods + * + * Suspend/resume is not supported on all platforms. For example, Pthreads + * does not support these functions. + */ + //@{ + /// Suspend all threads int suspend_all (void); @@ -659,7 +787,6 @@ public: */ int testsuspend (ACE_thread_t t_id); - // = Resume methods, which isn't supported on POSIX pthreads (will not block). /// Resume all stopped threads int resume_all (void); @@ -675,6 +802,8 @@ public: */ int testresume (ACE_thread_t t_id); + //@} + // = Send signals to one or more threads without blocking. /** * Send @a signum to all stopped threads. Not supported on platforms @@ -730,13 +859,10 @@ public: int get_grp (ACE_thread_t, int &grp_id); - // = The following methods are new methods which resemble current - // methods in <ACE_Thread Manager>. For example, the <apply_task> - // method resembles the <apply_thr> method, and <suspend_task> - // resembles <suspend_thr>. - - // = Operations on ACE_Tasks. - + /** + * @name Task-related operations + */ + //@{ /** * Block until there are no more threads running in a specified task. * This method will not wait for either detached or daemon threads; @@ -774,6 +900,8 @@ public: */ int cancel_task (ACE_Task_Base *task, int async_cancel = 0); + //@} + // = Collect thread handles in the thread manager. Notice that // the collected information is just a snapshot. /// Check if the thread is managed by the thread manager. Return true if |