ACE
6.3.3
|
Manages a group of processes. More...
#include <Process_Manager.h>
Classes | |
struct | Process_Descriptor |
Information describing each process that's controlled by an ACE_Process_Manager. More... | |
Public Types | |
enum | { DEFAULT_SIZE = 100 } |
Public Member Functions | |
Initialization and termination methods | |
ACE_Process_Manager (size_t size=ACE_Process_Manager::DEFAULT_SIZE, ACE_Reactor *reactor=0) | |
int | open (size_t size=ACE_Process_Manager::DEFAULT_SIZE, ACE_Reactor *r=0) |
int | close (void) |
Release all resources. Do not wait for processes to exit. More... | |
virtual | ~ACE_Process_Manager (void) |
Process creation methods | |
pid_t | spawn (ACE_Process *proc, ACE_Process_Options &options, ACE_Event_Handler *event_handler=0) |
pid_t | spawn (ACE_Process_Options &options, ACE_Event_Handler *event_handler=0) |
int | spawn_n (size_t n, ACE_Process_Options &options, pid_t *child_pids=0, ACE_Event_Handler *event_Handler=0) |
Process synchronization operations | |
int | terminate (pid_t pid) |
int | terminate (pid_t pid, int sig) |
int | wait (const ACE_Time_Value &timeout=ACE_Time_Value::max_time) |
pid_t | wait (pid_t pid, const ACE_Time_Value &timeout, ACE_exitcode *status=0) |
pid_t | wait (pid_t pid, ACE_exitcode *status=0) |
Static Public Member Functions | |
Singleton access and control | |
static ACE_Process_Manager * | instance (void) |
Get pointer to a process-wide ACE_Process_Manager. More... | |
static ACE_Process_Manager * | instance (ACE_Process_Manager *) |
static void | close_singleton (void) |
Delete the dynamically allocated singleton. More... | |
static void | cleanup (void *instance, void *arg) |
Protected Member Functions | |
virtual int | handle_signal (int signum, siginfo_t *=0, ucontext_t *=0) |
Protected Member Functions inherited from ACE_Event_Handler | |
ACE_Event_Handler (ACE_Reactor *=0, int priority=ACE_Event_Handler::LO_PRIORITY) | |
Force ACE_Event_Handler to be an abstract base class. More... | |
virtual | ~ACE_Event_Handler (void) |
Destructor is virtual to enable proper cleanup. More... | |
virtual ACE_HANDLE | get_handle (void) const |
Get the I/O handle. More... | |
virtual void | set_handle (ACE_HANDLE) |
Set the I/O handle. More... | |
virtual int | priority (void) const |
virtual void | priority (int priority) |
Set the priority of the Event_Handler. More... | |
virtual int | handle_input (ACE_HANDLE fd=ACE_INVALID_HANDLE) |
Called when input events occur (e.g., connection or data). More... | |
virtual int | handle_output (ACE_HANDLE fd=ACE_INVALID_HANDLE) |
virtual int | handle_exception (ACE_HANDLE fd=ACE_INVALID_HANDLE) |
Called when an exceptional events occur (e.g., SIGURG). More... | |
virtual int | handle_timeout (const ACE_Time_Value ¤t_time, const void *act=0) |
virtual int | handle_exit (ACE_Process *) |
Called when a process exits. More... | |
virtual int | handle_close (ACE_HANDLE handle, ACE_Reactor_Mask close_mask) |
virtual int | resume_handler (void) |
virtual int | handle_qos (ACE_HANDLE=ACE_INVALID_HANDLE) |
virtual int | handle_group_qos (ACE_HANDLE=ACE_INVALID_HANDLE) |
virtual void | reactor (ACE_Reactor *reactor) |
Set the event demultiplexors. More... | |
virtual ACE_Reactor * | reactor (void) const |
Get the event demultiplexors. More... | |
virtual ACE_Reactor_Timer_Interface * | reactor_timer_interface (void) const |
Get only the reactor's timer related interface. More... | |
virtual Reference_Count | add_reference (void) |
Increment reference count on the handler. More... | |
virtual Reference_Count | remove_reference (void) |
Decrement reference count on the handler. More... | |
Reference_Counting_Policy & | reference_counting_policy (void) |
Current Reference_Counting_Policy. More... | |
Private Member Functions | |
int | resize (size_t) |
Resize the pool of Process_Descriptors. More... | |
ssize_t | find_proc (pid_t process_id) |
ssize_t | find_proc (ACE_HANDLE process_handle) |
int | insert_proc (ACE_Process *process, ACE_Event_Handler *event_handler=0) |
int | append_proc (ACE_Process *process, ACE_Event_Handler *event_handler=0) |
int | remove_proc (size_t n) |
int | notify_proc_handler (size_t n, ACE_exitcode status) |
Private Attributes | |
Process_Descriptor * | process_table_ |
Vector that describes process state within the Process_Manager. More... | |
size_t | max_process_table_size_ |
size_t | current_count_ |
Current number of processes we are managing. More... | |
ACE_Event_Handler * | default_exit_handler_ |
ACE_Recursive_Thread_Mutex | lock_ |
This lock protects access/ops on process_table_ . More... | |
Static Private Attributes | |
static ACE_Process_Manager * | instance_ = 0 |
Singleton pointer. More... | |
static bool | delete_instance_ = false |
Friends | |
class | ACE_Process_Control |
Utility methods | |
ACE_ALLOC_HOOK_DECLARE | |
Declare the dynamic allocation hooks. More... | |
int | register_handler (ACE_Event_Handler *event_handler, pid_t pid=ACE_INVALID_PID) |
int | remove (pid_t pid) |
size_t | managed (void) const |
Return the number of managed processes. More... | |
int | set_scheduler (const ACE_Sched_Params ¶ms, pid_t pid) |
int | set_scheduler_all (const ACE_Sched_Params ¶ms) |
void | dump (void) const |
Dump the state of an object. More... | |
Additional Inherited Members | |
Protected Types inherited from ACE_Event_Handler | |
typedef ACE_Atomic_Op< ACE_SYNCH_MUTEX, Reference_Count > | Atomic_Reference_Count |
Typedef for implementation of reference counting. More... | |
enum | { LO_PRIORITY = 0, HI_PRIORITY = 10, NULL_MASK = 0, READ_MASK = (1 << 0), WRITE_MASK = (1 << 1), EXCEPT_MASK = (1 << 2), ACCEPT_MASK = (1 << 3), CONNECT_MASK = (1 << 4), TIMER_MASK = (1 << 5), QOS_MASK = (1 << 6), GROUP_QOS_MASK = (1 << 7), SIGNAL_MASK = (1 << 8), ALL_EVENTS_MASK, RWE_MASK, DONT_CALL = (1 << 9) } |
enum | { ACE_EVENT_HANDLER_NOT_RESUMED = -1, ACE_REACTOR_RESUMES_HANDLER = 0, ACE_APPLICATION_RESUMES_HANDLER } |
typedef long | Reference_Count |
Reference count type. More... | |
Static Protected Member Functions inherited from ACE_Event_Handler | |
static ACE_THR_FUNC_RETURN | read_adapter (void *event_handler) |
static int | register_stdin_handler (ACE_Event_Handler *eh, ACE_Reactor *reactor, ACE_Thread_Manager *thr_mgr, int flags=THR_DETACHED) |
static int | remove_stdin_handler (ACE_Reactor *reactor, ACE_Thread_Manager *thr_mgr) |
Performs the inverse of the register_stdin_handler() method. More... | |
Protected Attributes inherited from ACE_Event_Handler | |
Atomic_Reference_Count | reference_count_ |
Reference count. More... | |
Manages a group of processes.
This class allows applications to control groups of processes, similar to the way ACE_Thread_Manager controls groups of threads. Naturally, it doesn't work at all on platforms, such as VxWorks or pSoS, that don't support multiple processes. There are two main ways of using ACE_Process_Manager, depending on how involved you wish to be with the termination of managed processes. If you want processes to simply go away when they're finished, register the ACE_Process_Manager with an ACE_Reactor that can handle notifications of child process exit:
In this usage scenario, the ACE_Process_Manager will clean up after any processes that it spawns. (On Unix, this means executing a wait(2) to collect the exit status and avoid zombie processes; on Win32, it means closing the process and thread HANDLEs that are created when CreateProcess is called.)
If, on the other hand you want to wait "in line" to handle the terminated process cleanup code, call one of the wait functions whenever there might be managed processes that have exited.
Note that in either case, ACE_Process_Manager allows you to register an ACE_Event_Handler to be called when a specific spawned process exits, or when any process without a specific ACE_Event_Handler exits. When a process exits, the appropriate ACE_Event_Handler's handle_input() method is called; the ACE_HANDLE passed is either the process's HANDLE (on Windows), or its pid cast to an ACE_HANDLE (on POSIX). It is also possible to call the wait() functions even when the ACE_Process_Manager is registered with a reactor.
ACE_Process_Manager::ACE_Process_Manager | ( | size_t | size = ACE_Process_Manager::DEFAULT_SIZE , |
ACE_Reactor * | reactor = 0 |
||
) |
Initialize an ACE_Process_Manager with a table containing up to size processes. This table resizes itself automatically as needed. If a reactor is provided, this ACE_Process_Manager uses it to notify an application when a process it controls exits. By default, however, we don't use an ACE_Reactor.
|
virtual |
Destructor releases all resources and does not wait for processes to exit.
|
private |
Append information about a process, i.e., its <process_id> in the process_table_
. Each entry is added at the end, growing the table if necessary. Register event_handler to be called back when the process exits.
|
static |
Cleanup method, used by the ACE_Object_Manager to destroy the singleton.
int ACE_Process_Manager::close | ( | void | ) |
Release all resources. Do not wait for processes to exit.
|
static |
Delete the dynamically allocated singleton.
void ACE_Process_Manager::dump | ( | void | ) | const |
Dump the state of an object.
|
private |
Locate the index of the table slot occupied by process_id. Returns -1 if process_id is not in the process_table_
|
private |
Locate the index of the table slot occupied by process_handle. Returns ~0 if process_handle is not in the process_table_
|
protectedvirtual |
On Unix, this routine is called asynchronously when a SIGCHLD is received. We just tweak the reactor so that it'll call back our <handle_input> function, which allows us to handle Process exits synchronously.
On Win32, this routine is called synchronously, and is passed the HANDLE of the Process that exited, so we can do all our work here
Reimplemented from ACE_Event_Handler.
|
private |
Insert a process in the table (checks for duplicates). Omitting the process handle won't work on Win32... Register event_handler to be called back when the process exits.
|
static |
Get pointer to a process-wide ACE_Process_Manager.
|
static |
Set pointer to a process-wide ACE_Process_Manager and return existing pointer.
|
inline |
Return the number of managed processes.
|
private |
If there's a specific handler for the Process at index n in the table, or there's a default handler, call it.
int ACE_Process_Manager::open | ( | size_t | size = ACE_Process_Manager::DEFAULT_SIZE , |
ACE_Reactor * | r = 0 |
||
) |
Initialize an ACE_Process_Manager with a table containing up to size processes. This table resizes itself automatically as needed. If a reactor is provided, this ACE_Process_Manager uses it to notify an application when a process it controls exits. By default, however, we don't use an ACE_Reactor.
int ACE_Process_Manager::register_handler | ( | ACE_Event_Handler * | event_handler, |
pid_t | pid = ACE_INVALID_PID |
||
) |
Register an event handler to be called back when the specified process exits. If pid == ACE_INVALID_PID this handler is called when any process with no specific handler exits.
int ACE_Process_Manager::remove | ( | pid_t | pid | ) |
Remove process pid from the ACE_Process_Manager's internal records. This is called automatically by the wait() method if the waited process exits. This method can also be called after calling terminate() if there's no need to wait() for the terminated process.
|
private |
Actually removes the process at index n from the table. This method must be called with locks held.
|
private |
Resize the pool of Process_Descriptors.
int ACE_Process_Manager::set_scheduler | ( | const ACE_Sched_Params & | params, |
pid_t | pid | ||
) |
Sets the scheduling parameters for process identified by pid by passing params, pid to ACE_OS::sched_params().
0 | on success, -1 on failure, and ACE_INVALID_PID when the specified pid is not managed by this ACE_Process_Manager. |
int ACE_Process_Manager::set_scheduler_all | ( | const ACE_Sched_Params & | params | ) |
Sets the scheduling parameters for all the processes managed by this ACE_Process_Manager by passing params to ACE_OS::sched_params().
0 | on success, -1 on failure. |
pid_t ACE_Process_Manager::spawn | ( | ACE_Process * | proc, |
ACE_Process_Options & | options, | ||
ACE_Event_Handler * | event_handler = 0 |
||
) |
Create a new process with specified options. Register event_handler to be called back when the process exits. The proc object's ACE_Process::unmanage() method is called when the process is removed from ACE_Process_Manager.
On success, returns the process id of the child that was created. On failure, returns ACE_INVALID_PID.
pid_t ACE_Process_Manager::spawn | ( | ACE_Process_Options & | options, |
ACE_Event_Handler * | event_handler = 0 |
||
) |
Create a new process with the specified options. Register event_handler to be called back when the process exits.
On success, returns the process id of the child that was created. On failure, returns ACE_INVALID_PID.
int ACE_Process_Manager::spawn_n | ( | size_t | n, |
ACE_Process_Options & | options, | ||
pid_t * | child_pids = 0 , |
||
ACE_Event_Handler * | event_Handler = 0 |
||
) |
Create n new processes with the same options. If child_pids is non-0 it is expected to be an array of at least n pid_t, which are filled in with the process IDs of the spawned processes. Register event_handler to be called back when each process exits. Returns 0 on success and -1 on failure.
int ACE_Process_Manager::terminate | ( | pid_t | pid | ) |
Abruptly terminate a single process with id pid using the ACE::terminate_process() method which works on both signal-capable systems and on Windows.
0 | on success and -1 on failure. |
int ACE_Process_Manager::terminate | ( | pid_t | pid, |
int | sig | ||
) |
Sends the specified signal to the specified process.
0 | on success and -1 on failure. |
int ACE_Process_Manager::wait | ( | const ACE_Time_Value & | timeout = ACE_Time_Value::max_time | ) |
Block until there are no more child processes running that were spawned by this ACE_Process_Manager. Unlike the wait() method below, this method does not require a signal handler or use of ACE_OS::sigwait() because it simply blocks synchronously waiting for all the children managed by this ACE_Process_Manager to exit. Note that this does not return any status information about the success or failure of exiting child processes, although any registered exit handlers are called.
timeout | Relative time to wait for processes to terminate. |
0 | on success; -1 on failure. |
pid_t ACE_Process_Manager::wait | ( | pid_t | pid, |
const ACE_Time_Value & | timeout, | ||
ACE_exitcode * | status = 0 |
||
) |
Wait up to timeout for a single specified process to terminate. If pid is 0, this method waits for any of the managed processes (but see the note concerning "sloppy process cleanup on unix"). If pid != 0, waits for that process only.
pid | Process ID |
timeout | Relative time to wait for process to terminate |
status | Exit status of terminated process |
The | pid of the process which exited, 0 if a timeout occurred, or ACE_INVALID_PID on error. |
pid_t ACE_Process_Manager::wait | ( | pid_t | pid, |
ACE_exitcode * | status = 0 |
||
) |
Wait indefinitely for a single, specified process to terminate. If pid is 0, waits for any of the managed processes (but see the note concerning "sloppy process cleanup on unix"). If pid != 0, this method waits for that process only.
The | pid of the process which exited, or ACE_INVALID_PID on error. |
|
friend |
ACE_Process_Manager::ACE_ALLOC_HOOK_DECLARE |
Declare the dynamic allocation hooks.
|
private |
Current number of processes we are managing.
|
private |
This event handler is used to notify when a process we control exits.
|
staticprivate |
Controls whether the <Process_Manager> is deleted when we shut down (we can only delete it safely if we created it!)
|
staticprivate |
Singleton pointer.
|
private |
This lock protects access/ops on process_table_
.
|
private |
Maximum number of processes we can manage (should be dynamically allocated).
|
private |
Vector that describes process state within the Process_Manager.