ACE_Thread_Manager Class Reference

Manages a pool of threads. More...

#include <Thread_Manager.h>

Collaboration diagram for ACE_Thread_Manager:
Collaboration graph
[legend]

List of all members.

Public Types

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
}
typedef int(ACE_Thread_Manager::* ACE_THR_MEMBER_FUNC )(ACE_Thread_Descriptor *, int)

Public Member Functions

 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.
 ~ACE_Thread_Manager (void)
int open (size_t size=0)
 No-op. Currently unused.
int close (void)
int spawn (ACE_THR_FUNC func, void *arg=0, long flags=THR_NEW_LWP|THR_JOINABLE|THR_INHERIT_SCHED, ACE_thread_t *t_id=0, ACE_hthread_t *t_handle=0, long priority=ACE_DEFAULT_THREAD_PRIORITY, int grp_id=-1, void *stack=0, size_t stack_size=ACE_DEFAULT_THREAD_STACKSIZE, const char **thr_name=0)
int spawn_n (size_t n, ACE_THR_FUNC func, void *arg=0, long flags=THR_NEW_LWP|THR_JOINABLE|THR_INHERIT_SCHED, 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, const char *thr_name[]=0)
int spawn_n (ACE_thread_t thread_ids[], size_t n, ACE_THR_FUNC func, void *arg, 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, const char *thr_name[]=0)
ACE_THR_FUNC_RETURN exit (ACE_THR_FUNC_RETURN status=0, bool do_thread_exit=true)
int wait (const ACE_Time_Value *timeout=0, bool abandon_detached_threads=false, bool use_absolute_time=true)
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_Basetask (void)
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 testterminate (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 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 thr_state (ACE_thread_t id, ACE_UINT32 &state)
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.
Suspend and resume methods

Suspend/resume is not supported on all platforms. For example, Pthreads does not support these functions.

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)
Task-related operations

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)

Static Public Member Functions

static ACE_Thread_Managerinstance (void)
 Get pointer to a process-wide ACE_Thread_Manager.
static ACE_Thread_Managerinstance (ACE_Thread_Manager *)
static void close_singleton (void)
 Delete the dynamically allocated Singleton.

Public Attributes

 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks.

Protected Member Functions

ACE_Thread_Descriptorthread_desc_self (void)
ACE_Thread_Descriptorthread_descriptor (ACE_thread_t)
ACE_Thread_Descriptorhthread_descriptor (ACE_hthread_t)
int spawn_i (ACE_THR_FUNC func, void *arg, 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, const char **thr_name=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_Descriptorfind_thread (ACE_thread_t t_id)
ACE_Thread_Descriptorfind_hthread (ACE_hthread_t h_id)
ACE_Thread_Descriptorfind_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 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 td.
int resume_thr (ACE_Thread_Descriptor *td, int=0)
 Resume the thread described in td.
int suspend_thr (ACE_Thread_Descriptor *td, int=0)
 Suspend the thread described in td.
int kill_thr (ACE_Thread_Descriptor *td, int signum)
 Send signal signum to the thread described in td.
int cancel_thr (ACE_Thread_Descriptor *td, int async_cancel=0)
 Set the cancellation flag for the thread described in td.
int register_as_terminated (ACE_Thread_Descriptor *td)
 Register a thread as terminated and put it into the <terminated_thr_list_>.

Static Protected Member Functions

static 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 Member Functions

static ACE_TSS_TYPE (ACE_Thread_Exit)*thr_exit_
 Global ACE_TSS (ACE_Thread_Exit) object ptr.

Static Private Attributes

static ACE_Thread_Managerthr_mgr_ = 0
 Pointer to a process-wide ACE_Thread_Manager.
static bool delete_thr_mgr_ = false
 Must delete the thr_mgr_ if true.

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 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 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.


Member Typedef Documentation

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

Member Enumeration Documentation

anonymous enum

These are the various states a thread managed by the ACE_Thread_Manager can be in.

Enumerator:
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, 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   ) 

Member Function Documentation

static 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  t_handle,
ACE_UINT32  thr_state,
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  func,
int  arg = 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  func,
int  arg = 0 
) [protected]

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

int ACE_Thread_Manager::at_exit ( void *  object,
ACE_CLEANUP_FUNC  cleanup_hook,
void *  param 
) [inline]
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.

int ACE_Thread_Manager::at_exit ( ACE_At_Thread_Exit cleanup  )  [inline]

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.

int ACE_Thread_Manager::at_exit ( ACE_At_Thread_Exit cleanup  )  [inline]

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  t_id,
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 td.

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 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).

void ACE_Thread_Manager::close_singleton ( void   )  [static]

Delete the dynamically allocated Singleton.

size_t ACE_Thread_Manager::count_threads ( void   )  const [inline]

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,
bool  do_thread_exit = true 
)

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  t_id,
int &  grp_id 
)

Get group ids for a particular thread id.

ACE_Thread_Descriptor * ACE_Thread_Manager::hthread_descriptor ( ACE_hthread_t  thr_handle  )  [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  t_handle,
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 tm  )  [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 td.

int ACE_Thread_Manager::kill ( ACE_thread_t  t_id,
int  signum 
)

Send the signum to a single thread. Not supported on platforms that do not have advanced signal support, such as Win32.

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.

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

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_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 td.

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.

int ACE_Thread_Manager::open ( size_t  size = 0  )  [inline]

No-op. Currently unused.

int ACE_Thread_Manager::register_as_terminated ( ACE_Thread_Descriptor td  )  [inline, 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  t_id  ) 

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 td.

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  t_id,
int  grp_id 
)

Set group ids for a particular thread id.

static 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 *  arg = 0,
long  flags = THR_NEW_LWP | THR_JOINABLE | THR_INHERIT_SCHED,
ACE_thread_t t_id = 0,
ACE_hthread_t t_handle = 0,
long  priority = ACE_DEFAULT_THREAD_PRIORITY,
int  grp_id = -1,
void *  stack = 0,
size_t  stack_size = ACE_DEFAULT_THREAD_STACKSIZE,
const char **  thr_name = 0 
)

Create a new thread, which executes func with argument arg.

Parameters:
func The function that is called in the spawned thread.
arg The value passed to each spawned thread's func.
flags Flags to control attributes of the spawned threads.
See also:
ACE_OS::thr_create() for descriptions of the possible flags values and their interactions.
Parameters:
t_id Pointer to a location to receive the spawned thread's ID. If 0, the ID is not returned.
t_handle Pointer to a location to receive the spawned thread's thread handle. If 0, the handle is not returned.
priority The priority at which the thread is spawned.
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.
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 stack_size also be supplied to specify the size of the stack. Not all platforms support pre-allocated stacks. If stack is specified for a platform which does not allow pre-allocated stack space this parameter is ignored.
stack_size Indicate how large the thread's stack should be, in bytes. If a pre-allocated stack pointer is passed in stack, 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.
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.
Return values:
-1 on failure; errno contains an error value.
The group id of the spawned thread.
int ACE_Thread_Manager::spawn_i ( ACE_THR_FUNC  func,
void *  arg,
long  flags,
ACE_thread_t t_id = 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,
const char **  thr_name = 0 
) [protected]

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 *  arg,
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,
const char *  thr_name[] = 0 
)

Spawn a specified number of threads, all of which execute func with argument arg.

Parameters:
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 n entries.
n The number of threads to spawn.
func The function that is called in the spawned thread.
arg The value passed to each spawned thread's func.
flags Flags to control attributes of the spawned threads.
See also:
ACE_OS::thr_create() for descriptions of the possible flags values and their interactions.
Parameters:
priority The priority at which the threads are spawned.
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.
stack An array of 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 stack_size element also be supplied that specifies the size of the stack. Not all platforms support pre-allocated stacks. If stack is specified for a platform which does not allow pre-allocated stack space this parameter is ignored.
stack_size An array of n values which indicate how large each thread's stack should be, in bytes. If pre-allocated stacks are passed in 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.
thread_handles An array of n entries which will receive the thread handles of the spawned threads.
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.
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 grp_id or task using functions such as kill_grp() or cancel_task().

Return values:
-1 on failure; errno contains an error value.
The group id of the threads.
int ACE_Thread_Manager::spawn_n ( size_t  n,
ACE_THR_FUNC  func,
void *  arg = 0,
long  flags = THR_NEW_LWP | THR_JOINABLE | THR_INHERIT_SCHED,
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,
const char *  thr_name[] = 0 
)

Spawn a specified number of threads, all of which execute func with argument arg.

Parameters:
n The number of threads to spawn.
func The function that is called in the spawned thread.
arg The value passed to each spawned thread's func.
flags Flags to control attributes of the spawned threads.
See also:
ACE_OS::thr_create() for descriptions of the possible flags values and their interactions.
Parameters:
priority The priority at which the threads are spawned.
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.
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.
thread_handles An array of n entries which will receive the thread handles of the spawned threads.
stack An array of 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 stack_size element also be supplied that specifies the size of the stack. Not all platforms support pre-allocated stacks. If stack is specified for a platform which does not allow pre-allocated stack space this parameter is ignored.
stack_size An array of n values which indicate how large each thread's stack should be, in bytes. If pre-allocated stacks are passed in 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.
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 grp_id or task using functions such as kill_grp() or cancel_task().

Return values:
-1 on failure; errno contains an error value.
The group id of the threads.
int ACE_Thread_Manager::suspend ( ACE_thread_t  t_id  ) 

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 td.

ACE_Task_Base * ACE_Thread_Manager::task ( void   )  [inline]

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 a list of ACE_Task_Base pointers corresponding to the tasks that have active threads managed by this instance.

Parameters:
task_list is a pointer to an array to receive the list of pointers. The caller is responsible for supplying an array with at least

  • n entries.
n The maximum number of ACE_Task_Base pointers to write in

  • task_list.
Return values:
If successful, the number of pointers returned, which will be no greater than

  • n. Returns -1 on error.
Note:
This method has no way to indicate if there are more than
  • n ACE_Task_Base pointers available. Therefore, it may be wise to guess a larger value of
  • n than one thinks in cases where the exact number of tasks is not known.
See also:
count_threads()
ssize_t ACE_Thread_Manager::task_list ( int  grp_id,
ACE_Task_Base task_list[],
size_t  n 
)

Returns a list of ACE_Task_Base pointers corresponding to the tasks that have active threads in a specified thread group.

Parameters:
grp_id The thread group ID to obtain task pointers for.
task_list is a pointer to an array to receive the list of pointers. The caller is responsible for supplying an array with at least

  • n entries.
n The maximum number of ACE_Task_Base pointers to write in

  • task_list.
Return values:
If successful, the number of pointers returned, which will be no greater than

  • n. Returns -1 on error.
Note:
This method has no way to indicate if there are more than
  • n ACE_Task_Base pointers available. Therefore, it may be wise to guess a larger value of
  • n than one thinks in cases where the exact number of tasks is not known.
See also:
num_tasks_in_group(), task_all_list()
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.

int ACE_Thread_Manager::testterminate ( ACE_thread_t  t_id  ) 

True if t_id has terminated (i.e., is no longer running), but the slot in the thread manager hasn't been reclaimed yet, else false. Always return false if t_id is not managed by the Thread_Manager.

ACE_thread_t ACE_Thread_Manager::thr_self ( void   )  [inline]

Return the unique ID of the calling thread. Same as calling ACE_Thread::self().

int ACE_Thread_Manager::thr_self ( ACE_hthread_t self  ) 

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

int ACE_Thread_Manager::thr_state ( ACE_thread_t  id,
ACE_UINT32 &  state 
)

Get the state of the thread. Returns false if the thread is not managed by this thread manager.

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_Thread_Descriptor * ACE_Thread_Manager::thread_desc_self ( void   )  [inline, 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  thr_id  )  [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,
bool  abandon_detached_threads = false,
bool  use_absolute_time = true 
)

Block until there are no more threads running in this thread manager or timeout expires.

Parameters:
timeout is treated as "absolute" time by default, but this can be changed to "relative" time by setting the use_absolute_time to false.
abandon_detached_threads If true, 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_*() methods, 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.
use_absolute_time If true then treat timeout as absolute time, else relative time.
Returns:
0 on success * and -1 on failure.
Note:
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.

int ACE_Thread_Manager::wait_on_exit ( void   )  [inline]
void ACE_Thread_Manager::wait_on_exit ( int  dowait  )  [inline]

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

Declare the dynamic allocation hooks.

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

bool ACE_Thread_Manager::delete_thr_mgr_ = false [static, private]

Must delete the thr_mgr_ if true.

int ACE_Thread_Manager::grp_id_ [protected]

Keeps track of the next group id to assign.

Serialize access to the <zero_cond_>.

Collect terminated but not yet joined thread entries.

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.

Pointer to a process-wide ACE_Thread_Manager.

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

Keep track of when there are no more threads.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated by  doxygen 1.6.2