NAME

ACE_Thread_Manager - Manages a pool of threads.

SYNOPSIS

#include <ace/Thread_Manager.h>

class ACE_Thread_Manager { public: friend class ACE_Thread_Control; typedef int (ACE_Thread_Manager::*ACE_THR_MEMBER_FUNC)( ACE_Thread_Descriptor *, int ); ACE_Thread_Manager (size_t size = 0); virtual ~ACE_Thread_Manager (void); static ACE_Thread_Manager *instance (void); static ACE_Thread_Manager *instance (ACE_Thread_Manager *); static void close_singleton (void); int open (size_t size = 0); int close (); int spawn ( ACE_THR_FUNC func, void *args = 0, long flags = THR_NEW_LWP, 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, 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 ); void *exit (void *status, int do_thread_exit = 1); int wait ( const ACE_Time_Value *timeout = 0, int abandon_detached_threads = 0 ); int wait_grp (int grp_id); ACE_Thread_Descriptor *thread_desc_self (void); ACE_Thread_Descriptor *thread_descriptor (ACE_thread_t); ACE_Thread_Descriptor *hthread_descriptor (ACE_hthread_t); int thr_self (ACE_hthread_t &); ACE_thread_t thr_self (void); ACE_Task_Base *task (void); int suspend_all (void); int suspend (ACE_thread_t); int suspend_grp (int grp_id); int testsuspend (ACE_thread_t t_id); int resume_all (void); int resume (ACE_thread_t); int resume_grp (int grp_id); 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 (void); int cancel (ACE_thread_t); int cancel_grp (int grp_id); int testcancel (ACE_thread_t t_id); int set_grp (ACE_thread_t, int grp_id); int get_grp (ACE_thread_t, int &grp_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 num_tasks_in_group (int grp_id); int num_threads_in_task (ACE_Task_Base *task); int task_list (int grp_id, ACE_Task_Base *task_list[], size_t n); int thread_list ( ACE_Task_Base *task, ACE_thread_t thread_list[], size_t n ); int hthread_list ( ACE_Task_Base *task, ACE_hthread_t hthread_list[], size_t n ); int set_grp (ACE_Task_Base *task, int grp_id); int get_grp (ACE_Task_Base *task, int &grp_id); int at_exit ( void *object, ACE_CLEANUP_FUNC cleanup_hook, void *param ); int acquire_release (void); void wait_on_exit (int dowait); int wait_on_exit (void); void dump (void); ACE_ALLOC_HOOK_DECLARE; protected: 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 ); void run_thread_exit_hooks (int i); 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, int index = -1 ); int insert_thr ( ACE_thread_t t_id, ACE_hthread_t, int grp_id = -1, long flags = 0 ); int append_thr ( ACE_thread_t t_id, ACE_hthread_t, ACE_Thread_State, 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); void remove_thr_all (void); int check_state (ACE_Thread_State state, ACE_thread_t thread); int apply_task ( ACE_Task_Base *task, ACE_THR_MEMBER_FUNC, int = 0 ); int apply_grp (int grp_id, ACE_THR_MEMBER_FUNC func, int arg = 0); int apply_all (ACE_THR_MEMBER_FUNC, int = 0); int join_thr (ACE_Thread_Descriptor *td, int = 0); int resume_thr (ACE_Thread_Descriptor *td, int = 0); int suspend_thr (ACE_Thread_Descriptor *td, int = 0); int kill_thr (ACE_Thread_Descriptor *td, int signum); int cancel_thr (ACE_Thread_Descriptor *td, int = 0); ACE_Double_Linked_List<ACE_Thread_Descriptor> thr_list_; ACE_Unbounded_Queue<ACE_Thread_Descriptor> terminated_thr_queue_; ACE_Unbounded_Queue<ACE_Thread_Descriptor*> thr_to_be_removed_; int grp_id_; int automatic_wait_; ACE_Thread_Mutex lock_; ACE_Condition_Thread_Mutex zero_cond_; private: static ACE_Thread_Manager *thr_mgr_; static int delete_thr_mgr_; };

DESCRIPTION

This class allows operations on groups of threads atomically. The default behavior 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 diable 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.

Initialization and termination methods.

ACE_Thread_Manager (size_t size = 0);

virtual ~ACE_Thread_Manager (void);

static ACE_Thread_Manager *instance (void);

static ACE_Thread_Manager *instance (ACE_Thread_Manager *);

static void close_singleton (void);

int open (size_t size = 0);

int close ();

int spawn (
    ACE_THR_FUNC func,
    void *args = 0,
    long flags = THR_NEW_LWP,
    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,
    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
    );

void *exit (void *status, int do_thread_exit = 1);

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

int wait_grp (int grp_id);

Accessors for ACE_Thread_Descriptors.

ACE_Thread_Descriptor *thread_desc_self (void);

ACE_Thread_Descriptor *thread_descriptor (ACE_thread_t);

ACE_Thread_Descriptor *hthread_descriptor (ACE_hthread_t);

int thr_self (ACE_hthread_t &);

ACE_thread_t thr_self (void);

ACE_Task_Base *task (void);

Suspend methods, which isn't supported on POSIX pthreads (will not block).

int suspend_all (void);

int suspend (ACE_thread_t);

int suspend_grp (int grp_id);

int testsuspend (ACE_thread_t t_id);

Resume methods, which isn't supported on POSIX pthreads (will not block).

int resume_all (void);

int resume (ACE_thread_t);

int resume_grp (int grp_id);

int testresume (ACE_thread_t t_id);

Kill methods, send signals -- which isn't supported on Win32 (will not block).

int kill_all (int signum);

int kill (ACE_thread_t, int signum);

int kill_grp (int grp_id, int signum);

Cancel methods, which provides a cooperative thread-termination mechanism (will not block).

int cancel_all (void);

int cancel (ACE_thread_t);

int cancel_grp (int grp_id);

int testcancel (ACE_thread_t t_id);

Set/get group ids for a particular thread id.

int set_grp (ACE_thread_t, int grp_id);

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.

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

The following method provide new functionality. They do not

follow the same design as current methods. They provide new functionality.
int num_tasks_in_group (int grp_id);

int num_threads_in_task (ACE_Task_Base *task);

int task_list (int grp_id, ACE_Task_Base *task_list[], size_t n);

int thread_list (
    ACE_Task_Base *task,
    ACE_thread_t thread_list[],
    size_t n
    );

int hthread_list (
    ACE_Task_Base *task,
    ACE_hthread_t hthread_list[],
    size_t n
    );

Set/get group ids for a particular task.

int set_grp (ACE_Task_Base *task, int grp_id);

int get_grp (ACE_Task_Base *task, int &grp_id);

int at_exit (
    void *object,
    ACE_CLEANUP_FUNC cleanup_hook,
    void *param
    );

int acquire_release (void);

void wait_on_exit (int dowait);

int wait_on_exit (void);

void dump (void);

ACE_ALLOC_HOOK_DECLARE;

The following four methods implement a simple scheme for

operating on a collection of threads atomically.
int check_state (ACE_Thread_State state, ACE_thread_t thread);

int apply_task (ACE_Task_Base *task, ACE_THR_MEMBER_FUNC, int = 0);

int apply_grp (int grp_id, ACE_THR_MEMBER_FUNC func, int arg = 0);

int apply_all (ACE_THR_MEMBER_FUNC, int = 0);

int join_thr (ACE_Thread_Descriptor *td, int = 0);

int resume_thr (ACE_Thread_Descriptor *td, int = 0);

int suspend_thr (ACE_Thread_Descriptor *td, int = 0);

int kill_thr (ACE_Thread_Descriptor *td, int signum);

int cancel_thr (ACE_Thread_Descriptor *td, int = 0);

ACE_Double_Linked_List<ACE_Thread_Descriptor> thr_list_;

ACE_Unbounded_Queue<ACE_Thread_Descriptor> terminated_thr_queue_;

ACE_Unbounded_Queue<ACE_Thread_Descriptor*> thr_to_be_removed_;

int grp_id_;

int automatic_wait_;

ACE_Thread_Mutex and condition variable for synchronizing termination.

ACE_Thread_Mutex lock_;

ACE_Condition_Thread_Mutex zero_cond_;

AUTHOR

Doug Schmidt

LIBRARY

ace