---

ACE_Thread_Manager Class Reference

Manages a pool of threads. More...

#include <Thread_Manager.h>

Collaboration diagram for ACE_Thread_Manager:

[legend]List of all members.

Public Types
typedef int(ACE_Thread_Manager::*	ACE_THR_MEMBER_FUNC )(ACE_Thread_Descriptor *, int)
enum	{   ACE_THR_IDLE = 0x00000000, ACE_THR_SPAWNED = 0x00000001, ACE_THR_RUNNING = 0x00000002, ACE_THR_SUSPENDED = 0x00000004,   ACE_THR_CANCELLED = 0x00000008, ACE_THR_TERMINATED = 0x00000010, ACE_THR_JOINING = 0x10000000 }
Public Methods
	ACE_Thread_Manager (size_t preaolloc=ACE_DEFAULT_THREAD_MANAGER_PREALLOC, size_t lwm=ACE_DEFAULT_THREAD_MANAGER_LWM, size_t inc=ACE_DEFAULT_THREAD_MANAGER_INC, size_t hwm=ACE_DEFAULT_THREAD_MANAGER_HWM)
	Initialization and termination methods.
virtual	~ACE_Thread_Manager (void)
int	open (size_t size=0)
	No-op. Currently unused.
int	close (void)
int	spawn (ACE_THR_FUNC func, void *args=0, long flags=THR_NEW_LWP|THR_JOINABLE, ACE_thread_t *=0, ACE_hthread_t *t_handle=0, long priority=ACE_DEFAULT_THREAD_PRIORITY, int grp_id=-1, void *stack=0, size_t stack_size=0)
int	spawn_n (size_t n, ACE_THR_FUNC func, void *args=0, long flags=THR_NEW_LWP|THR_JOINABLE, long priority=ACE_DEFAULT_THREAD_PRIORITY, int grp_id=-1, ACE_Task_Base *task=0, ACE_hthread_t thread_handles[]=0, void *stack[]=0, size_t stack_size[]=0)
int	spawn_n (ACE_thread_t thread_ids[], size_t n, ACE_THR_FUNC func, void *args, long flags, long priority=ACE_DEFAULT_THREAD_PRIORITY, int grp_id=-1, void *stack[]=0, size_t stack_size[]=0, ACE_hthread_t thread_handles[]=0, ACE_Task_Base *task=0)
ACE_THR_FUNC_RETURN	exit (ACE_THR_FUNC_RETURN status=0, int do_thread_exit=1)
int	wait (const ACE_Time_Value *timeout=0, int abandon_detached_threads=0)
int	join (ACE_thread_t tid, ACE_THR_FUNC_RETURN *status=0)
	Join a thread specified by <tid>. Do not wait on a detached thread.
int	wait_grp (int grp_id)
int	thr_self (ACE_hthread_t &)
ACE_thread_t	thr_self (void)
ACE_Task_Base *	task (void)
int	suspend_all (void)
	Suspend all threads.
int	suspend (ACE_thread_t)
	Suspend a single thread.
int	suspend_grp (int grp_id)
	Suspend a group of threads.
int	testsuspend (ACE_thread_t t_id)
int	resume_all (void)
	Resume all stopped threads.
int	resume (ACE_thread_t)
	Resume a single thread.
int	resume_grp (int grp_id)
	Resume a group of threads.
int	testresume (ACE_thread_t t_id)
int	kill_all (int signum)
int	kill (ACE_thread_t, int signum)
int	kill_grp (int grp_id, int signum)
int	cancel_all (int async_cancel=0)
int	cancel (ACE_thread_t, int async_cancel=0)
int	cancel_grp (int grp_id, int async_cancel=0)
int	testcancel (ACE_thread_t t_id)
int	set_grp (ACE_thread_t, int grp_id)
	Set group ids for a particular thread id.
int	get_grp (ACE_thread_t, int &grp_id)
	Get group ids for a particular thread id.
int	wait_task (ACE_Task_Base *task)
int	suspend_task (ACE_Task_Base *task)
int	resume_task (ACE_Task_Base *task)
int	kill_task (ACE_Task_Base *task, int signum)
int	cancel_task (ACE_Task_Base *task, int async_cancel=0)
int	hthread_within (ACE_hthread_t handle)
int	thread_within (ACE_thread_t tid)
int	num_tasks_in_group (int grp_id)
	Returns the number of <ACE_Task_Base> in a group.
int	num_threads_in_task (ACE_Task_Base *task)
	Returns the number of threads in an <ACE_Task_Base>.
ssize_t	task_list (int grp_id, ACE_Task_Base *task_list[], size_t n)
ssize_t	thread_list (ACE_Task_Base *task, ACE_thread_t thread_list[], size_t n)
ssize_t	hthread_list (ACE_Task_Base *task, ACE_hthread_t hthread_list[], size_t n)
ssize_t	thread_grp_list (int grp_id, ACE_thread_t thread_list[], size_t n)
ssize_t	hthread_grp_list (int grp_id, ACE_hthread_t hthread_list[], size_t n)
ssize_t	task_all_list (ACE_Task_Base *task_list[], size_t n)
ssize_t	thread_all_list (ACE_thread_t thread_list[], size_t n)
int	set_grp (ACE_Task_Base *task, int grp_id)
	Set group ids for a particular task.
int	get_grp (ACE_Task_Base *task, int &grp_id)
	Get group ids for a particular task.
size_t	count_threads (void) const
int	at_exit (ACE_At_Thread_Exit *cleanup)
int	at_exit (ACE_At_Thread_Exit &cleanup)
int	at_exit (void *object, ACE_CLEANUP_FUNC cleanup_hook, void *param)
void	wait_on_exit (int dowait)
int	wait_on_exit (void)
void	dump (void)
	Dump the state of an object.
Static Public Methods
ACE_Thread_Manager *	instance (void)
	Get pointer to a process-wide <ACE_Thread_Manager>.
ACE_Thread_Manager *	instance (ACE_Thread_Manager *)
void	close_singleton (void)
	Delete the dynamically allocated Singleton.
Public Attributes
	ACE_ALLOC_HOOK_DECLARE
	Declare the dynamic allocation hooks.
Protected Methods
ACE_Thread_Descriptor *	thread_desc_self (void)
ACE_Thread_Descriptor *	thread_descriptor (ACE_thread_t)
ACE_Thread_Descriptor *	hthread_descriptor (ACE_hthread_t)
virtual int	spawn_i (ACE_THR_FUNC func, void *args, long flags, ACE_thread_t *=0, ACE_hthread_t *t_handle=0, long priority=ACE_DEFAULT_THREAD_PRIORITY, int grp_id=-1, void *stack=0, size_t stack_size=0, ACE_Task_Base *task=0)
	Create a new thread (must be called with locks held).
void	run_thread_exit_hooks (int i)
	Run the registered hooks when the thread exits.
ACE_Thread_Descriptor *	find_thread (ACE_thread_t t_id)
ACE_Thread_Descriptor *	find_hthread (ACE_hthread_t h_id)
ACE_Thread_Descriptor *	find_task (ACE_Task_Base *task, size_t slot=0)
int	insert_thr (ACE_thread_t t_id, ACE_hthread_t, int grp_id=-1, long flags=0)
	Insert a thread in the table (checks for duplicates).
int	append_thr (ACE_thread_t t_id, ACE_hthread_t, ACE_UINT32, int grp_id, ACE_Task_Base *task=0, long flags=0, ACE_Thread_Descriptor *td=0)
void	remove_thr (ACE_Thread_Descriptor *td, int close_handler)
	Remove thread from the table.
void	remove_thr_all (void)
	Remove all threads from the table.
int	check_state (ACE_UINT32 state, ACE_thread_t thread, int enable=1)
int	apply_task (ACE_Task_Base *task, ACE_THR_MEMBER_FUNC, int=0)
	Apply <func> to all members of the table that match the <task>.
int	apply_grp (int grp_id, ACE_THR_MEMBER_FUNC func, int arg=0)
	Apply <func> to all members of the table that match the <grp_id>.
int	apply_all (ACE_THR_MEMBER_FUNC, int=0)
	Apply <func> to all members of the table.
int	join_thr (ACE_Thread_Descriptor *td, int=0)
	Join the thread described in <tda>.
int	resume_thr (ACE_Thread_Descriptor *td, int=0)
	Resume the thread described in <tda>.
int	suspend_thr (ACE_Thread_Descriptor *td, int=0)
	Suspend the thread described in <tda>.
int	kill_thr (ACE_Thread_Descriptor *td, int signum)
	Send signal <signum> to the thread described in <tda>.
int	cancel_thr (ACE_Thread_Descriptor *td, int async_cancel=0)
	Set the cancellation flag for the thread described in <tda>.
int	register_as_terminated (ACE_Thread_Descriptor *td)
	Register a thread as terminated and put it into the <terminated_thr_list_>.
Static Protected Methods
int	set_thr_exit (ACE_TSS_TYPE(ACE_Thread_Exit)*ptr)
	Setting the static ACE_TSS_TYPE (ACE_Thread_Exit) *thr_exit_ pointer.
Protected Attributes
ACE_Double_Linked_List< ACE_Thread_Descriptor >	thr_list_
ACE_Double_Linked_List< ACE_Thread_Descriptor_Base >	terminated_thr_list_
	Collect terminated but not yet joined thread entries.
ACE_Unbounded_Queue< ACE_Thread_Descriptor * >	thr_to_be_removed_
	Collect pointers to thread descriptors of threads to be removed later.
int	grp_id_
	Keeps track of the next group id to assign.
int	automatic_wait_
ACE_Thread_Mutex	lock_
	Serialize access to the <zero_cond_>.
ACE_Condition_Thread_Mutex	zero_cond_
	Keep track of when there are no more threads.
ACE_Locked_Free_List< ACE_Thread_Descriptor, ACE_SYNCH_MUTEX >	thread_desc_freelist_
Static Private Methods
	ACE_TSS_TYPE (ACE_Thread_Exit)*thr_exit_
	Global ACE_TSS (ACE_Thread_Exit) object ptr.
Static Private Attributes
ACE_Thread_Manager *	thr_mgr_ = 0
	Pointer to a process-wide <ACE_Thread_Manager>.
int	delete_thr_mgr_ = 0
	Must delete the <thr_mgr_> if non-0.
Friends
class	ACE_Thread_Control
class	ACE_Thread_Exit
class	ACE_Thread_Descriptor

---

Detailed Description

Manages a pool of threads.

This class allows operations on groups of threads atomically. The default behavior of thread manager is to wait on 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. 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 could happen in your programs.

---

Member Typedef Documentation

typedef int(ACE_Thread_Manager::* ACE_Thread_Manager::ACE_THR_MEMBER_FUNC)(ACE_Thread_Descriptor *, int)

---

Member Enumeration Documentation

anonymous enum

Enumeration values: ACE_THR_IDLE  Uninitialized. ACE_THR_SPAWNED  Created but not yet running. ACE_THR_RUNNING  Thread is active (naturally, we don't know if it's actually running* because we aren't the scheduler...). ACE_THR_SUSPENDED  Thread is suspended. ACE_THR_CANCELLED  Thread has been cancelled (which is an indiction that it needs to terminate...). ACE_THR_TERMINATED  Thread has shutdown, but the slot in the thread manager hasn't been reclaimed yet. ACE_THR_JOINING  Join operation has been invoked on the thread by thread manager.

---

Constructor & Destructor Documentation

ACE_Thread_Manager::ACE_Thread_Manager (  size_t    preaolloc = ACE_DEFAULT_THREAD_MANAGER_PREALLOC, size_t    lwm = ACE_DEFAULT_THREAD_MANAGER_LWM, size_t    inc = ACE_DEFAULT_THREAD_MANAGER_INC, size_t    hwm = ACE_DEFAULT_THREAD_MANAGER_HWM )

Initialization and termination methods. Internally, ACE_Thread_Manager keeps a freelist for caching resources it uses to keep track of managed threads (not the threads themselves.) prealloc, lwm, inc, @hwm determine the initial size, the low water mark, increment step, and high water mark of the freelist. See also: ACE_Free_List

ACE_Thread_Manager::~ACE_Thread_Manager (  void    )  [virtual]

---

Member Function Documentation

ACE_Thread_Manager::ACE_TSS_TYPE (  ACE_Thread_Exit    )  [static, private]

Global ACE_TSS (ACE_Thread_Exit) object ptr.

int ACE_Thread_Manager::append_thr (  ACE_thread_t    t_id, ACE_hthread_t   , ACE_UINT32   , int    grp_id, ACE_Task_Base *    task = 0, long    flags = 0, ACE_Thread_Descriptor *    td = 0 )  [protected]

Append a thread in the table (adds at the end, growing the table if necessary).

int ACE_Thread_Manager::apply_all (  ACE_THR_MEMBER_FUNC   , int    = 0 )  [protected]

Apply <func> to all members of the table.

int ACE_Thread_Manager::apply_grp (  int    grp_id, ACE_THR_MEMBER_FUNC    func, int    arg = 0 )  [protected]

Apply <func> to all members of the table that match the <grp_id>.

int ACE_Thread_Manager::apply_task (  ACE_Task_Base *    task, ACE_THR_MEMBER_FUNC   , int    = 0 )  [protected]

Apply <func> to all members of the table that match the <task>.

ACE_INLINE int ACE_Thread_Manager::at_exit (  void *    object, ACE_CLEANUP_FUNC    cleanup_hook, void *    param )

Deprecated: This function is deprecated. Please use the previous two at_exit method. Notice that you should avoid mixing this method with the previous two at_exit methods. Register an object (or array) for cleanup at thread termination. "cleanup_hook" points to a (global, or static member) function that is called for the object or array when it to be destroyed. It may perform any necessary cleanup specific for that object or its class. "param" is passed as the second parameter to the "cleanup_hook" function; the first parameter is the object (or array) to be destroyed. "cleanup_hook", for example, may delete the object (or array). If <cleanup_hook> == 0, the <object> will _NOT_ get cleanup at thread exit. You can use this to cancel the previously added at_exit.

ACE_INLINE int ACE_Thread_Manager::at_exit (  ACE_At_Thread_Exit &    cleanup )

Register an At_Thread_Exit hook and the ownership is retained for the caller. Normally used when the at_exit hook is created in stack.

ACE_INLINE int ACE_Thread_Manager::at_exit (  ACE_At_Thread_Exit *    cleanup )

Register an At_Thread_Exit hook and the ownership is acquire by Thread_Descriptor, this is the usual case when the AT is dynamically allocated.

int ACE_Thread_Manager::cancel (  ACE_thread_t   , int    async_cancel = 0 )

Cancel a single thread.

int ACE_Thread_Manager::cancel_all (  int    async_cancel = 0 )

Cancel's all the threads.

int ACE_Thread_Manager::cancel_grp (  int    grp_id, int    async_cancel = 0 )

Cancel a group of threads.

int ACE_Thread_Manager::cancel_task (  ACE_Task_Base *    task, int    async_cancel = 0 )

Cancel all threads in an <ACE_Task>. If <async_cancel> is non-0, then asynchronously cancel these threads if the OS platform supports cancellation. Otherwise, perform a "cooperative" cancellation.

int ACE_Thread_Manager::cancel_thr (  ACE_Thread_Descriptor *    td, int    async_cancel = 0 )  [protected]

Set the cancellation flag for the thread described in <tda>.

int ACE_Thread_Manager::check_state (  ACE_UINT32    state, ACE_thread_t    thread, int    enable = 1 )  [protected]

Efficiently check whether <thread> is in a particular <state>. This call updates the TSS cache if possible to speed up subsequent searches.

int ACE_Thread_Manager::close (  void    )

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.

void ACE_Thread_Manager::close_singleton (  void    )  [static]

Delete the dynamically allocated Singleton.

ACE_INLINE size_t ACE_Thread_Manager::count_threads (  void    )  const

Return a count of the current number of threads active in the <Thread_Manager>.

void ACE_Thread_Manager::dump (  void    )

Dump the state of an object.

ACE_THR_FUNC_RETURN ACE_Thread_Manager::exit (  ACE_THR_FUNC_RETURN    status = 0, int    do_thread_exit = 1 )

Called to clean up when a thread exits. Parameters: do_thread_exit  If non-0 then ACE_Thread::exit is called to exit the thread status  If ACE_Thread_Exit is called, this is passed as the exit value of the thread. Should _not_ be called by main thread.

ACE_Thread_Descriptor * ACE_Thread_Manager::find_hthread (  ACE_hthread_t    h_id )  [protected]

Locate the index of the table slot occupied by <h_id>. Returns -1 if <h_id> is not in the table doesn't contain <h_id>.

ACE_Thread_Descriptor * ACE_Thread_Manager::find_task (  ACE_Task_Base *    task, size_t    slot = 0 )  [protected]

Locate the thread descriptor address of the list occupied by <task>. Returns 0 if <task> is not in the table doesn't contain <task>.

ACE_Thread_Descriptor * ACE_Thread_Manager::find_thread (  ACE_thread_t    t_id )  [protected]

Locate the index of the table slot occupied by <t_id>. Returns -1 if <t_id> is not in the table doesn't contain <t_id>.

int ACE_Thread_Manager::get_grp (  ACE_Task_Base *    task, int &    grp_id )

Get group ids for a particular task.

int ACE_Thread_Manager::get_grp (  ACE_thread_t   , int &    grp_id )

Get group ids for a particular thread id.

ACE_Thread_Descriptor * ACE_Thread_Manager::hthread_descriptor (  ACE_hthread_t    )  [protected]

Return a pointer to the thread's Thread_Descriptor, 0 if fail.

ssize_t ACE_Thread_Manager::hthread_grp_list (  int    grp_id, ACE_hthread_t    hthread_list[], size_t    n )

Returns in <hthread_list> a list of up to <n> thread handles in a group <grp_id>. The caller must allocate memory for <hthread_list>.

ssize_t ACE_Thread_Manager::hthread_list (  ACE_Task_Base *    task, ACE_hthread_t    hthread_list[], size_t    n )

Returns in <hthread_list> a list of up to <n> thread handles in an <ACE_Task_Base>. The caller must allocate memory for <hthread_list>. In case of an error, -1 is returned. If no requested values are found, 0 is returned, otherwise correct number of retrieved values are returned.

int ACE_Thread_Manager::hthread_within (  ACE_hthread_t    handle )

Check if the thread is managed by the thread manager. Return true if the thread is found, false otherwise.

int ACE_Thread_Manager::insert_thr (  ACE_thread_t    t_id, ACE_hthread_t   , int    grp_id = -1, long    flags = 0 )  [protected]

Insert a thread in the table (checks for duplicates).

ACE_Thread_Manager * ACE_Thread_Manager::instance (  ACE_Thread_Manager *    )  [static]

Set pointer to a process-wide <ACE_Thread_Manager> and return existing pointer.

ACE_Thread_Manager * ACE_Thread_Manager::instance (  void    )  [static]

Get pointer to a process-wide <ACE_Thread_Manager>.

int ACE_Thread_Manager::join (  ACE_thread_t    tid, ACE_THR_FUNC_RETURN *    status = 0 )

Join a thread specified by <tid>. Do not wait on a detached thread.

int ACE_Thread_Manager::join_thr (  ACE_Thread_Descriptor *    td, int    = 0 )  [protected]

Join the thread described in <tda>.

int ACE_Thread_Manager::kill (  ACE_thread_t   , int    signum )

int ACE_Thread_Manager::kill_all (  int    signum )

Send <signum> to all stopped threads. Not supported on platforms that do not have advanced signal support, such as Win32. Send the <signum> to a single thread. Not supported on platforms that do not have advanced signal support, such as Win32. Send <signum> to a group of threads, not supported on platforms that do not have advanced signal support, such as Win32.

int ACE_Thread_Manager::kill_grp (  int    grp_id, int    signum )

int ACE_Thread_Manager::kill_task (  ACE_Task_Base *    task, int    signum )

Send a signal <signum> to all threads in an <ACE_Task>.

int ACE_Thread_Manager::kill_thr (  ACE_Thread_Descriptor *    td, int    signum )  [protected]

Send signal <signum> to the thread described in <tda>.

int ACE_Thread_Manager::num_tasks_in_group (  int    grp_id )

Returns the number of <ACE_Task_Base> in a group.

int ACE_Thread_Manager::num_threads_in_task (  ACE_Task_Base *    task )

Returns the number of threads in an <ACE_Task_Base>.

ACE_INLINE int ACE_Thread_Manager::open (  size_t    size = 0 )

No-op. Currently unused.

ACE_INLINE int ACE_Thread_Manager::register_as_terminated (  ACE_Thread_Descriptor *    td )  [protected]

Register a thread as terminated and put it into the <terminated_thr_list_>.

void ACE_Thread_Manager::remove_thr (  ACE_Thread_Descriptor *    td, int    close_handler )  [protected]

Remove thread from the table.

void ACE_Thread_Manager::remove_thr_all (  void    )  [protected]

Remove all threads from the table.

int ACE_Thread_Manager::resume (  ACE_thread_t    )

Resume a single thread.

int ACE_Thread_Manager::resume_all (  void    )

Resume all stopped threads.

int ACE_Thread_Manager::resume_grp (  int    grp_id )

Resume a group of threads.

int ACE_Thread_Manager::resume_task (  ACE_Task_Base *    task )

Resume all threads in an ACE_Task.

int ACE_Thread_Manager::resume_thr (  ACE_Thread_Descriptor *    td, int    = 0 )  [protected]

Resume the thread described in <tda>.

void ACE_Thread_Manager::run_thread_exit_hooks (  int    i )  [protected]

Run the registered hooks when the thread exits.

int ACE_Thread_Manager::set_grp (  ACE_Task_Base *    task, int    grp_id )

Set group ids for a particular task.

int ACE_Thread_Manager::set_grp (  ACE_thread_t   , int    grp_id )

Set group ids for a particular thread id.

int ACE_Thread_Manager::set_thr_exit (  ACE_TSS_TYPE(ACE_Thread_Exit)*    ptr )  [static, protected]

Setting the static ACE_TSS_TYPE (ACE_Thread_Exit) *thr_exit_ pointer.

int ACE_Thread_Manager::spawn (  ACE_THR_FUNC    func, void *    args = 0, long    flags = THR_NEW_LWP|THR_JOINABLE, ACE_thread_t *    = 0, ACE_hthread_t *    t_handle = 0, long    priority = ACE_DEFAULT_THREAD_PRIORITY, int    grp_id = -1, void *    stack = 0, size_t    stack_size = 0 )

Create a new thread, which executes <func>. Returns: on success a unique group id that can be used to control other threads added to the same group. On failure, returns -1.

int ACE_Thread_Manager::spawn_i (  ACE_THR_FUNC    func, void *    args, long    flags, ACE_thread_t *    = 0, ACE_hthread_t *    t_handle = 0, long    priority = ACE_DEFAULT_THREAD_PRIORITY, int    grp_id = -1, void *    stack = 0, size_t    stack_size = 0, ACE_Task_Base *    task = 0 )  [protected, virtual]

Create a new thread (must be called with locks held).

int ACE_Thread_Manager::spawn_n (  ACE_thread_t    thread_ids[], size_t    n, ACE_THR_FUNC    func, void *    args, long    flags, long    priority = ACE_DEFAULT_THREAD_PRIORITY, int    grp_id = -1, void *    stack[] = 0, size_t    stack_size[] = 0, ACE_hthread_t    thread_handles[] = 0, ACE_Task_Base *    task = 0 )

Spawn N new threads, which execute <func> with argument <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 <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. Threads in Thread_Manager can be manipulated in groups based on <grp_id> or <task> using functions such as kill_grp() or cancel_task(). If <grp_id> is assigned, the newly spawned threads are added into the group. Otherwise, the Thread_Manager assigns these <n> threads with a grp_id. You should choose either assigning <grp_id> everytime, or let the Thread_Manager handles it for you consistently. The argument <task> is usually assigned by <ACE_Task_Base::activate>. It associates the newly spawned threads with an ACE_Task instance, which defaults to <this>. Return values: -1  on failure (<errno> will explain...), otherwise returns the group id of the threads.

int ACE_Thread_Manager::spawn_n (  size_t    n, ACE_THR_FUNC    func, void *    args = 0, long    flags = THR_NEW_LWP|THR_JOINABLE, long    priority = ACE_DEFAULT_THREAD_PRIORITY, int    grp_id = -1, ACE_Task_Base *    task = 0, ACE_hthread_t    thread_handles[] = 0, void *    stack[] = 0, size_t    stack_size[] = 0 )

Spawn N new threads, which execute <func> with argument <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 <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. Threads in Thread_Manager can be manipulated in groups based on <grp_id> or <task> using functions such as kill_grp() or cancel_task(). If <grp_id> is assigned, the newly spawned threads are added into the group. Otherwise, the Thread_Manager assigns these <n> threads with a grp_id. You should choose either assigning <grp_id> everytime, or let the Thread_Manager handles it for you consistently. The argument <task> is usually assigned by <ACE_Task_Base::activate>. It associates the newly spawned threads with an ACE_Task instance, which defaults to <this>. Return values: -1  on failure (<errno> will explain...), otherwise returns the group id of the threads.

int ACE_Thread_Manager::suspend (  ACE_thread_t    )

Suspend a single thread.

int ACE_Thread_Manager::suspend_all (  void    )

Suspend all threads.

int ACE_Thread_Manager::suspend_grp (  int    grp_id )

Suspend a group of threads.

int ACE_Thread_Manager::suspend_task (  ACE_Task_Base *    task )

Suspend all threads in an ACE_Task.

int ACE_Thread_Manager::suspend_thr (  ACE_Thread_Descriptor *    td, int    = 0 )  [protected]

Suspend the thread described in <tda>.

ACE_INLINE ACE_Task_Base * ACE_Thread_Manager::task (  void    )

Returns a pointer to the current <ACE_Task_Base> we're executing in if this thread is indeed running in an <ACE_Task_Base>, else return 0.

ssize_t ACE_Thread_Manager::task_all_list (  ACE_Task_Base *    task_list[], size_t    n )

Returns in <task_list> a list of up to <n> <ACE_Tasks>. The caller must allocate the memory for <task_list>. In case of an error, -1 is returned. If no requested values are found, 0 is returned, otherwise correct number of retrieved values are returned.

ssize_t ACE_Thread_Manager::task_list (  int    grp_id, ACE_Task_Base *    task_list[], size_t    n )

Returns in <task_list> a list of up to <n> <ACE_Tasks> in a group. The caller must allocate the memory for <task_list>. In case of an error, -1 is returned. If no requested values are found, 0 is returned, otherwise correct number of retrieved values are returned.

int ACE_Thread_Manager::testcancel (  ACE_thread_t    t_id )

True if <t_id> is cancelled, else false. Always return false if <t_id> is not managed by the Thread_Manager.

int ACE_Thread_Manager::testresume (  ACE_thread_t    t_id )

True if <t_id> is active (i.e., resumed), else false. Always return false if <t_id> is not managed by the Thread_Manager.

int ACE_Thread_Manager::testsuspend (  ACE_thread_t    t_id )

True if <t_id> is inactive (i.e., suspended), else false. Always return false if <t_id> is not managed by the Thread_Manager.

ACE_INLINE ACE_thread_t ACE_Thread_Manager::thr_self (  void    )

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.

int ACE_Thread_Manager::thr_self (  ACE_hthread_t &    )

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 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* use this internal thread handle when working on Thread_Manager. Return -1 if fail.

ssize_t ACE_Thread_Manager::thread_all_list (  ACE_thread_t    thread_list[], size_t    n )

Returns in <thread_list> a list of up to <n> thread ids. The caller must allocate the memory for <thread_list>. In case of an error, -1 is returned. If no requested values are found, 0 is returned, otherwise correct number of retrieved values are returned.

ACE_INLINE ACE_Thread_Descriptor * ACE_Thread_Manager::thread_desc_self (  void    )  [protected]

Get a pointer to the calling thread's own thread_descriptor. This must be called from a spawn thread. This function will fetch the info from TSS.

ACE_Thread_Descriptor * ACE_Thread_Manager::thread_descriptor (  ACE_thread_t    )  [protected]

Return a pointer to the thread's Thread_Descriptor, 0 if fail.

ssize_t ACE_Thread_Manager::thread_grp_list (  int    grp_id, ACE_thread_t    thread_list[], size_t    n )

Returns in <thread_list> a list of up to <n> thread ids in a group <grp_id>. The caller must allocate the memory for <thread_list>. In case of an error, -1 is returned. If no requested values are found, 0 is returned, otherwise correct number of retrieved values are returned.

ssize_t ACE_Thread_Manager::thread_list (  ACE_Task_Base *    task, ACE_thread_t    thread_list[], size_t    n )

Returns in <thread_list> a list of up to <n> thread ids in an <ACE_Task_Base>. The caller must allocate the memory for <thread_list>. In case of an error, -1 is returned. If no requested values are found, 0 is returned, otherwise correct number of retrieved values are returned.

int ACE_Thread_Manager::thread_within (  ACE_thread_t    tid )

int ACE_Thread_Manager::wait (  const ACE_Time_Value *    timeout = 0, int    abandon_detached_threads = 0 )

Block until there are no more threads running in the <Thread_Manager> or <timeout> expires. Note that <timeout> is treated as "absolute" time. Returns 0 on success and -1 on failure. If <abandon_detached_threads> is set, wait will first check thru its thread list for threads with THR_DETACHED or THR_DAEMON flags set and remove these threads. Notice that unlike other wait_* function, by default, <wait> does wait on all thread spawned by this thread_manager no matter the detached flags are set or not unless it is called with <abandon_detached_threads> flag set. NOTE that if this function is called while the ACE_Object_Manager is shutting down (as a result of program rundown via ACE::fini), it will not wait for any threads to complete. If you must wait for threads spawned by this thread manager to complete and you are in a ACE rundown situation (such as your object is being destroyed by the ACE_Object_Manager) you can use wait_grp instead.

int ACE_Thread_Manager::wait_grp (  int    grp_id )

Block until there are no more threads running in a group. Returns 0 on success and -1 on failure. Notice that wait_grp will not wait on detached threads.

ACE_INLINE int ACE_Thread_Manager::wait_on_exit (  void    )

ACE_INLINE void ACE_Thread_Manager::wait_on_exit (  int    dowait )

Access function to determine whether the Thread_Manager will wait for its thread to exit or not when being closing down.

int ACE_Thread_Manager::wait_task (  ACE_Task_Base *    task )

Block until there are no more threads running in a specified task. This method will not wait for either detached or daemon threads; the threads must have been spawned with the THR_JOINABLE flag. Upon successful completion, the threads have been joined, so further attempts to join with any of the waited-for threads will fail. Parameters: task  The ACE_Task_Base object whose threads are to waited for. Return values: 0  Success. -1  Failure (consult errno for further information).

---

Friends And Related Function Documentation

friend class ACE_Thread_Control [friend]

friend class ACE_Thread_Descriptor [friend]

friend class ACE_Thread_Exit [friend]

---

Member Data Documentation

ACE_Thread_Manager::ACE_ALLOC_HOOK_DECLARE

Declare the dynamic allocation hooks.

int ACE_Thread_Manager::automatic_wait_ [protected]

Set if we want the Thread_Manager to wait on all threads before being closed, reset otherwise.

int ACE_Thread_Manager::delete_thr_mgr_ = 0 [static, private]

Must delete the <thr_mgr_> if non-0.

int ACE_Thread_Manager::grp_id_ [protected]

Keeps track of the next group id to assign.

ACE_Thread_Mutex ACE_Thread_Manager::lock_ [protected]

Serialize access to the <zero_cond_>.

ACE_Double_Linked_List<ACE_Thread_Descriptor_Base> ACE_Thread_Manager::terminated_thr_list_ [protected]

Collect terminated but not yet joined thread entries.

ACE_Double_Linked_List<ACE_Thread_Descriptor> ACE_Thread_Manager::thr_list_ [protected]

Keeping a list of thread descriptors within the thread manager. Double-linked list enables us to cache the entries in TSS and adding/removing thread descriptor entries without affecting other thread's descriptor entries.

ACE_Thread_Manager * ACE_Thread_Manager::thr_mgr_ = 0 [static, private]

Pointer to a process-wide <ACE_Thread_Manager>.

ACE_Unbounded_Queue<ACE_Thread_Descriptor*> ACE_Thread_Manager::thr_to_be_removed_ [protected]

Collect pointers to thread descriptors of threads to be removed later.

ACE_Locked_Free_List<ACE_Thread_Descriptor, ACE_SYNCH_MUTEX> ACE_Thread_Manager::thread_desc_freelist_ [protected]

ACE_Condition_Thread_Mutex ACE_Thread_Manager::zero_cond_ [protected]

Keep track of when there are no more threads.

---

The documentation for this class was generated from the following files:

• /export2/deucetmp/bala/release_try/ACE_wrappers/ace/Thread_Manager.h
• /export2/deucetmp/bala/release_try/ACE_wrappers/ace/Thread_Manager.cpp
• /export2/deucetmp/bala/release_try/ACE_wrappers/ace/Thread_Manager.i

---