ACE_Process_Manager Class Reference

Manages a group of processes. More...

#include <Process_Manager.h>

Inheritance diagram for ACE_Process_Manager:

[legend]Collaboration diagram for ACE_Process_Manager:

[legend]List of all members.

Public Types
enum	{ DEFAULT_SIZE = 100 }
Public Member Functions
	ACE_Process_Manager (size_t size=ACE_Process_Manager::DEFAULT_SIZE, ACE_Reactor *reactor=0)
int	open (size_t size=DEFAULT_SIZE, ACE_Reactor *r=0)
int	close (void)
	Release all resources. Do not wait for processes to exit.
virtual	~ACE_Process_Manager (void)
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)
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)
int	reap (pid_t pid=-1, ACE_exitcode *stat_loc=0, int options=WNOHANG)
int	register_handler (ACE_Event_Handler *event_handler, pid_t pid=ACE_INVALID_PID)
int	remove (pid_t pid)
int	terminate (pid_t pid)
int	terminate (pid_t pid, int sig)
size_t	managed (void) const
	Return the number of managed Processes.
int	set_scheduler (const ACE_Sched_Params &params, pid_t pid)
int	set_scheduler_all (const ACE_Sched_Params &)
void	dump (void) const
	Dump the state of an object.
Static Public Member Functions
ACE_Process_Manager *	instance (void)
	Get pointer to a process-wide .
ACE_Process_Manager *	instance (ACE_Process_Manager *)
void	close_singleton (void)
	Delete the dynamically allocated singleton.
void	cleanup (void *instance, void *arg)
Public Attributes
	ACE_ALLOC_HOOK_DECLARE
	Declare the dynamic allocation hooks.
Protected Member Functions
virtual int	handle_signal (int signum, siginfo_t *=0, ucontext_t *=0)
Private Member Functions
int	resize (size_t)
	Resize the pool of Process_Descriptors.
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
ACE_Process_Descriptor *	process_table_
	Vector that describes process state within the Process_Manager.
size_t	max_process_table_size_
size_t	current_count_
	Current number of processes we are managing.
ACE_Event_Handler *	default_exit_handler_
ACE_Recursive_Thread_Mutex	lock_
	This lock protects access/ops on .
Static Private Attributes
ACE_Process_Manager *	instance_ = 0
	Singleton pointer.
int	delete_instance_ = 0
Friends
class	ACE_Process_Control

---

Detailed Description

Manages a group of processes.

This class allows applications to control groups of processes, similar to how the <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 process. There are two (main) ways of using <ACE_Process_Manager>, depending on how involved you wish to be with the termination of managed es. If you just want es to go away when they're finished, simply register the with an <ACE_Reactor>: ACE_Process_Manager mgr( 100, some_reactor ) -or- ACE_Process_Manager mgr; ... mgr.open( 100, some_reactor ); Then, the will clean up after any es 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 (and for some inexplicable reason) you want to explicitly invoke the terminated cleanup code, then *don't* register the with a Reactor, and be sure to call one of the <Process_Manager::wait> functions whenever there might be managed es that have exited. Note that in either case, allows you to register "<Event_Handlers>" to be called when a specific exits, or when any without a specific exits. When a exits, the appropriate 's is called; the ACE_HANDLE passed is either the Process' HANDLE (on Win32), or its pid cast to an ACE_HANDLE (on unix). It is also possible to call the <Process_Manager::wait> functions even though the is registered with a . Note also that the wait functions are "sloppy" on Unix, because there's no good way to wait for a subset of the children of a process. The wait functions may end up collecting the exit status of a process that's not managed by the whose you invoked. It's best to only use a single , and to create all subprocesses by calling that 's method. Incidentally, when you register your with a its notification pipe is used to help "reap" the available exit statuses. Therefore, you must not use a whose notify pipe has been disabled. Here's the sequence of steps used to reap the exit statuses in this case: + The registers a signal handler for SIGCHLD. + The SIGCHLD handler, when invoked, uses the 's method to inform the to wake up. + Next, the calls the 's , this happens synchronously, not in sighandler-space. + The method collects all available exit statuses.

Definition at line 124 of file Process_Manager.h.

---

Member Enumeration Documentation

anonymous enum

Enumeration values: DEFAULT_SIZE  Definition at line 129 of file Process_Manager.h. { DEFAULT_SIZE = 100 };

---

Constructor & Destructor Documentation

ACE_Process_Manager::ACE_Process_Manager (  size_t  size = ACE_Process_Manager::DEFAULT_SIZE, ACE_Reactor *  reactor = 0 )

Initialize an with a table containing up to processes. This table resizes itself automatically as needed. If a non-NULL is provided, this uses it to notify an application when a process it controls exits. By default, however, we don't use an ACE_Reactor. Definition at line 246 of file Process_Manager.cpp. References ACE_ERROR, ACE_LIB_TEXT, ACE_TRACE, LM_ERROR, and open(). : ACE_Event_Handler (), process_table_ (0), max_process_table_size_ (0), current_count_ (0), default_exit_handler_ (0) #if defined (ACE_HAS_THREADS) , lock_ () #endif /* ACE_HAS_THREADS */ { ACE_TRACE ("ACE_Process_Manager::ACE_Process_Manager"); if (this->open (size, r) == -1) ACE_ERROR ((LM_ERROR, ACE_LIB_TEXT ("%p\n"), ACE_LIB_TEXT ("ACE_Process_Manager"))); }

ACE_Process_Manager::~ACE_Process_Manager (  void   )  [virtual]

Destructor releases all resources and does not wait for processes to exit. Definition at line 301 of file Process_Manager.cpp. References ACE_TRACE, and close(). { ACE_TRACE ("ACE_Process_Manager::~ACE_Process_Manager"); this->close (); }

---

Member Function Documentation

int ACE_Process_Manager::append_proc (  ACE_Process *  process, ACE_Event_Handler *  event_handler = 0 )  [private]

Append information about a process, i.e., its in the . Each entry is added at the end, growing the table if necessary. Register to be called back when the process exits. Definition at line 497 of file Process_Manager.cpp. References ACE_TRACE, current_count_, DEFAULT_SIZE, ACE_Process_Descriptor::exit_notify_, ACE_Process::gethandle(), max_process_table_size_, ACE_Process_Descriptor::process_, process_table_, ACE_Event_Handler::reactor(), ACE_Reactor::register_handler(), and resize(). Referenced by insert_proc(), and spawn(). { ACE_TRACE ("ACE_Process_Manager::append_proc"); // Try to resize the array to twice its existing size (or the DEFAULT_SIZE, // if there are no array entries) if we run out of space... if (this->current_count_ >= this->max_process_table_size_) { size_t new_size = this->max_process_table_size_ * 2; if (new_size == 0) new_size = ACE_Process_Manager::DEFAULT_SIZE; if (this->resize (new_size) == -1) return -1; } ACE_Process_Descriptor &proc_desc = this->process_table_[this->current_count_]; proc_desc.process_ = proc; proc_desc.exit_notify_ = event_handler; #if defined (ACE_WIN32) // If we have a Reactor, then we're supposed to reap Processes // automagically. Get a handle to this new Process and tell the // Reactor we're interested in <handling_input> on it. ACE_Reactor * const r = this->reactor (); if (r != 0) r->register_handler (this, proc->gethandle ()); #endif /* ACE_WIN32 */ ++this->current_count_; return 0; }

ACE_BEGIN_VERSIONED_NAMESPACE_DECL void ACE_Process_Manager::cleanup (  void *  instance, void *  arg )  [static]

Cleanup method, used by the to destroy the singleton. Definition at line 38 of file Process_Manager.cpp. References close_singleton(). Referenced by instance(). { ACE_Process_Manager::close_singleton (); }

int ACE_Process_Manager::close (  void   )

Release all resources. Do not wait for processes to exit. Definition at line 269 of file Process_Manager.cpp. References ACE_GUARD_RETURN, ACE_TRACE, current_count_, default_exit_handler_, ACE_Event_Handler::handle_close(), max_process_table_size_, process_table_, ACE_Event_Handler::reactor(), ACE_Reactor::remove_handler(), remove_proc(), and SIGCHLD. Referenced by ~ACE_Process_Manager(). { ACE_TRACE ("ACE_Process_Manager::close"); if (this->reactor () != 0) { #if !defined (ACE_WIN32) && !defined (ACE_LACKS_UNIX_SIGNALS) this->reactor ()->remove_handler (SIGCHLD, (ACE_Sig_Action *) 0); #endif /* !ACE_WIN32 */ this->reactor (0); } ACE_MT (ACE_GUARD_RETURN (ACE_Recursive_Thread_Mutex, ace_mon, this->lock_, -1)); if (this->process_table_ != 0) { while (this->current_count_ > 0) this->remove_proc (0); delete [] this->process_table_; this->process_table_ = 0; this->max_process_table_size_ = 0; this->current_count_ = 0; } if (this->default_exit_handler_ != 0) this->default_exit_handler_->handle_close (ACE_INVALID_HANDLE,0); this->default_exit_handler_ = 0; return 0; }

void ACE_Process_Manager::close_singleton (  void   )  [static]

Delete the dynamically allocated singleton. Definition at line 176 of file Process_Manager.cpp. References ACE_GUARD, ACE_TRACE, delete_instance_, and instance_. Referenced by cleanup(). { ACE_TRACE ("ACE_Process_Manager::close_singleton"); ACE_MT (ACE_GUARD (ACE_Recursive_Thread_Mutex, ace_mon, *ACE_Static_Object_Lock::instance ())); if (ACE_Process_Manager::delete_instance_) { delete ACE_Process_Manager::instance_; ACE_Process_Manager::instance_ = 0; ACE_Process_Manager::delete_instance_ = 0; } }

void ACE_Process_Manager::dump (  void   )  const

Dump the state of an object. Definition at line 84 of file Process_Manager.cpp. References ACE_BEGIN_DUMP, ACE_DEBUG, ACE_END_DUMP, ACE_LIB_TEXT, ACE_TRACE, current_count_, ACE_Process_Descriptor::dump(), LM_DEBUG, and process_table_. { #if defined (ACE_HAS_DUMP) ACE_TRACE ("ACE_Process_Manager::dump"); ACE_DEBUG ((LM_DEBUG, ACE_BEGIN_DUMP, this)); ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("\nmax_process_table_size_ = %d"), this->max_process_table_size_)); ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("\ncurrent_count_ = %d"), this->current_count_)); for (size_t i = 0; i < this->current_count_; i++) this->process_table_[i].dump (); ACE_DEBUG ((LM_DEBUG, ACE_END_DUMP)); #endif /* ACE_HAS_DUMP */ }

ssize_t ACE_Process_Manager::find_proc (  ACE_HANDLE  process_handle  )  [private]

Locate the index of the table slot occupied by . Returns ~0 if is not in the Definition at line 715 of file Process_Manager.cpp. References ACE_TRACE, current_count_, ACE_Process::gethandle(), ACE_Process_Descriptor::process_, and process_table_. { ACE_TRACE ("ACE_Process_Manager::find_proc"); for (size_t i = 0; i < this->current_count_; ++i) if (h == this->process_table_[i].process_->gethandle ()) return i; return -1; }

ssize_t ACE_Process_Manager::find_proc (  pid_t  process_id  )  [private]

Locate the index of the table slot occupied by . Returns -1 if is not in the Definition at line 699 of file Process_Manager.cpp. References ACE_TRACE, current_count_, ACE_Process::getpid(), pid_t, ACE_Process_Descriptor::process_, and process_table_. Referenced by handle_signal(), insert_proc(), register_handler(), remove(), set_scheduler(), terminate(), and wait(). { ACE_TRACE ("ACE_Process_Manager::find_proc"); for (size_t i = 0; i < this->current_count_; ++i) if (pid == this->process_table_[i].process_->getpid ()) return i; return -1; }

int ACE_Process_Manager::handle_signal (  int  signum, siginfo_t *  = 0, ucontext_t *  = 0 )  [protected, virtual]

On Unix, this routine is called asynchronously when a SIGCHLD is received. We just tweak the reactor so that it'll call back our 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. Definition at line 341 of file Process_Manager.cpp. References ACE_ERROR_RETURN, ACE_exitcode, ACE_GUARD_RETURN, ACE_INVALID_PID, ACE_LIB_TEXT, find_proc(), ACE_Process::getpid(), LM_ERROR, ACE_Reactor::notify(), notify_proc_handler(), pid_t, ACE_Process_Descriptor::process_, process_table_, ACE_Event_Handler::reactor(), remove_proc(), siginfo_t::si_handle_, ssize_t, and ucontext_t. { #if defined (ACE_WIN32) ACE_HANDLE proc = si->si_handle_; ACE_exitcode status = 0; BOOL result = ::GetExitCodeProcess (proc, &status); if (result) { if (status != STILL_ACTIVE) { { ACE_MT (ACE_GUARD_RETURN (ACE_Recursive_Thread_Mutex, ace_mon, lock_, -1)); ssize_t const i = this->find_proc (proc); if (i == -1) return -1; #if 0 pid_t pid = i != -1 ? process_table_[i].process_->getpid () : ACE_INVALID_PID; #endif this->notify_proc_handler (i, status); this->remove_proc (i); } return -1; // remove this HANDLE/Event_Handler combination } else ACE_ERROR_RETURN ((LM_ERROR, ACE_LIB_TEXT ("Process still active") ACE_LIB_TEXT (" -- shouldn't have been called yet!\n")), 0); // return 0 : stay registered } else { // <GetExitCodeProcess> failed. ACE_ERROR_RETURN ((LM_ERROR, ACE_LIB_TEXT ("GetExitCodeProcess failed")), -1); // return -1: unregister } #else /* !ACE_WIN32 */ ACE_UNUSED_ARG (si); return reactor ()->notify (this, ACE_Event_Handler::READ_MASK); #endif /* !ACE_WIN32 */ }

int ACE_Process_Manager::insert_proc (  ACE_Process *  process, ACE_Event_Handler *  event_handler = 0 )  [private]

Insert a process in the table (checks for duplicates). Omitting the process handle won't work on Win32... Register to be called back when the process exits. Definition at line 537 of file Process_Manager.cpp. References ACE_TRACE, append_proc(), find_proc(), and ACE_Process::getpid(). { ACE_TRACE ("ACE_Process_Manager::insert_proc"); // Check for duplicates and bail out if they're already // registered... if (this->find_proc (proc->getpid ()) != -1) return -1; return this->append_proc (proc, event_handler); }

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

Set pointer to a process-wide and return existing pointer. Definition at line 147 of file Process_Manager.cpp. References ACE_GUARD_RETURN, ACE_TRACE, ACE_Object_Manager::at_exit(), cleanup(), delete_instance_, and instance_. { ACE_TRACE ("ACE_Process_Manager::instance"); ACE_MT (ACE_GUARD_RETURN (ACE_Recursive_Thread_Mutex, ace_mon, *ACE_Static_Object_Lock::instance (), 0)); ACE_Process_Manager *t = ACE_Process_Manager::instance_; // We can't safely delete it since we don't know who created it! ACE_Process_Manager::delete_instance_ = 0; // Register with the Object_Manager so that the wrapper to // delete the proactor will be called when Object_Manager is // being terminated. #if defined ACE_HAS_SIG_C_FUNC ACE_Object_Manager::at_exit (ACE_Process_Manager::instance_, ACE_Process_Manager_cleanup, 0); #else ACE_Object_Manager::at_exit (ACE_Process_Manager::instance_, ACE_Process_Manager::cleanup, 0); #endif /* ACE_HAS_SIG_C_FUNC */ ACE_Process_Manager::instance_ = tm; return t; }

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

Get pointer to a process-wide . Definition at line 109 of file Process_Manager.cpp. References ACE_GUARD_RETURN, ACE_NEW_RETURN, ACE_TRACE, ACE_Object_Manager::at_exit(), cleanup(), delete_instance_, and instance_. { ACE_TRACE ("ACE_Process_Manager::instance"); if (ACE_Process_Manager::instance_ == 0) { // Perform Double-Checked Locking Optimization. ACE_MT (ACE_GUARD_RETURN (ACE_Recursive_Thread_Mutex, ace_mon, *ACE_Static_Object_Lock::instance (), 0)); if (ACE_Process_Manager::instance_ == 0) { ACE_NEW_RETURN (ACE_Process_Manager::instance_, ACE_Process_Manager, 0); ACE_Process_Manager::delete_instance_ = 1; // Register with the Object_Manager so that the wrapper to // delete the proactor will be called when Object_Manager is // being terminated. #if defined ACE_HAS_SIG_C_FUNC ACE_Object_Manager::at_exit (ACE_Process_Manager::instance_, ACE_Process_Manager_cleanup, 0); #else ACE_Object_Manager::at_exit (ACE_Process_Manager::instance_, ACE_Process_Manager::cleanup, 0); #endif /* ACE_HAS_SIG_C_FUNC */ } } return ACE_Process_Manager::instance_; }

ACE_BEGIN_VERSIONED_NAMESPACE_DECL ACE_INLINE size_t ACE_Process_Manager::managed (  void   )  const

Return the number of managed Processes. Definition at line 8 of file Process_Manager.inl. References current_count_. { return current_count_; }

int ACE_Process_Manager::notify_proc_handler (  size_t  n, ACE_exitcode  status )  [private]

If there's a specific handler for the Process at index in the table, or there's a default handler, call it. Definition at line 1001 of file Process_Manager.cpp. References ACE_DEBUG, ACE_exitcode, ACE_LIB_TEXT, current_count_, default_exit_handler_, ACE_Process::exit_code(), ACE_Process_Descriptor::exit_notify_, ACE_Event_Handler::handle_close(), ACE_Event_Handler::handle_exit(), LM_DEBUG, ACE_Process_Descriptor::process_, and process_table_. Referenced by handle_signal(), and wait(). { if (i < this->current_count_) { ACE_Process_Descriptor &proc_desc = this->process_table_[i]; proc_desc.process_->exit_code (exit_code); if (proc_desc.exit_notify_ != 0) proc_desc.exit_notify_->handle_exit (proc_desc.process_); else if (this->default_exit_handler_ != 0 && this->default_exit_handler_->handle_exit (proc_desc.process_) < 0) { this->default_exit_handler_->handle_close (ACE_INVALID_HANDLE, 0); this->default_exit_handler_ = 0; } return 1; } else { ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("(%P:%t|%T) ACE_Process_Manager::notify_proc_handler:") ACE_LIB_TEXT (" unknown/unmanaged process reaped\n"))); return 0; } }

int ACE_Process_Manager::open (  size_t  size = DEFAULT_SIZE, ACE_Reactor *  r = 0 )

Initialize an with a table containing up to processes. This table resizes itself automatically as needed. If a non-NULL is provided, this uses it to notify an application when a process it controls exits. By default, however, we don't use an ACE_Reactor. Definition at line 222 of file Process_Manager.cpp. References ACE_GUARD_RETURN, ACE_TRACE, max_process_table_size_, ACE_Event_Handler::reactor(), ACE_Reactor::register_handler(), resize(), and SIGCHLD. Referenced by ACE_Process_Manager(). { ACE_TRACE ("ACE_Process_Manager::open"); if (r) { this->reactor (r); #if !defined (ACE_WIN32) && !defined (ACE_LACKS_UNIX_SIGNALS) // Register signal handler object. if (r->register_handler (SIGCHLD, this) == -1) return -1; #endif /* !defined(ACE_WIN32) */ } ACE_MT (ACE_GUARD_RETURN (ACE_Recursive_Thread_Mutex, ace_mon, this->lock_, -1)); if (this->max_process_table_size_ < size) this->resize (size); return 0; }

int ACE_Process_Manager::reap (  pid_t  pid = -1, ACE_exitcode *  stat_loc = 0, int  options = WNOHANG )

Deprecated: Reap the result of a single process by calling <ACE_OS::waitpid>, therefore, this method is not portable to Win32. If the child is successfully reaped, is called automatically. This method does the same thing that the method directly above it does -- It's just here for backwards compatibility. Definition at line 983 of file Process_Manager.cpp. References ACE_BIT_ENABLED, ACE_exitcode, ACE_TRACE, pid_t, wait(), and WNOHANG. { ACE_TRACE ("ACE_Process_Manager::reap"); return this->wait (pid, (ACE_BIT_ENABLED (options, WNOHANG) ? ACE_Time_Value::zero : ACE_Time_Value::max_time), stat_loc); }

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. Note: In multi-threaded applications, there is a race condition if a process exits between the time it is spawned and when its handler is registered. To avoid this, register the handler at the time the process is spawned. Definition at line 390 of file Process_Manager.cpp. References ACE_GUARD_RETURN, ACE_INVALID_PID, default_exit_handler_, ACE_Process_Descriptor::exit_notify_, find_proc(), ACE_Event_Handler::handle_close(), pid_t, process_table_, and ssize_t. { ACE_MT (ACE_GUARD_RETURN (ACE_Recursive_Thread_Mutex, ace_mon, this->lock_, -1)); if (pid == ACE_INVALID_PID) { if (this->default_exit_handler_ != 0) this->default_exit_handler_->handle_close (ACE_INVALID_HANDLE, 0); this->default_exit_handler_ = eh; return 0; } ssize_t const i = this->find_proc (pid); if (i == -1) { errno = EINVAL; return -1; } ACE_Process_Descriptor &proc_desc = this->process_table_[i]; if (proc_desc.exit_notify_ != 0) proc_desc.exit_notify_->handle_close (ACE_INVALID_HANDLE, 0); proc_desc.exit_notify_ = eh; return 0; }

int ACE_Process_Manager::remove (  pid_t  pid  )

Remove process from the table. This is called automatically by the method after it successfully reaped a signal. It's also possible to call this method directly from a signal handler, but don't call both and ! Definition at line 553 of file Process_Manager.cpp. References ACE_GUARD_RETURN, ACE_TRACE, find_proc(), pid_t, remove_proc(), and ssize_t. Referenced by wait(). { ACE_TRACE ("ACE_Process_Manager::remove"); ACE_MT (ACE_GUARD_RETURN (ACE_Recursive_Thread_Mutex, ace_mon, this->lock_, -1)); ssize_t const i = this->find_proc (pid); if (i != -1) return this->remove_proc (i); // set "process not found" error return -1; }

int ACE_Process_Manager::remove_proc (  size_t  n  )  [private]

Actually removes the process at index from the table. This method must be called with locks held. Definition at line 571 of file Process_Manager.cpp. References ACE_TRACE, current_count_, ACE_Process_Descriptor::exit_notify_, ACE_Process::gethandle(), ACE_Event_Handler::handle_close(), ACE_Process_Descriptor::process_, process_table_, ACE_Event_Handler::reactor(), ACE_Reactor::remove_handler(), and ACE_Process::unmanage(). Referenced by close(), handle_signal(), remove(), terminate(), and wait(). { ACE_TRACE ("ACE_Process_Manager::remove_proc"); // If there's an exit_notify_ <Event_Handler> for this pid, call its // <handle_close> method. if (this->process_table_[i].exit_notify_ != 0) { this->process_table_[i].exit_notify_->handle_close (this->process_table_[i].process_->gethandle(), 0); this->process_table_[i].exit_notify_ = 0; } #if defined (ACE_WIN32) ACE_Reactor * const r = this->reactor (); if (r != 0) r->remove_handler (this->process_table_[i].process_->gethandle (), ACE_Event_Handler::DONT_CALL); #endif /* ACE_WIN32 */ this->process_table_[i].process_->unmanage (); this->process_table_[i].process_ = 0; this->current_count_--; if (this->current_count_ > 0) // Compact the table by moving the last item into the slot vacated // by the index being removed (this is a structure assignment). this->process_table_[i] = this->process_table_[this->current_count_]; return 0; }

int ACE_Process_Manager::resize (  size_t   )  [private]

Resize the pool of Process_Descriptors. Definition at line 192 of file Process_Manager.cpp. References ACE_NEW_RETURN, ACE_TRACE, current_count_, max_process_table_size_, and process_table_. Referenced by append_proc(), and open(). { ACE_TRACE ("ACE_Process_Manager::resize"); if (size <= this->max_process_table_size_) return 0; ACE_Process_Descriptor *temp = 0; ACE_NEW_RETURN (temp, ACE_Process_Descriptor[size], -1); for (size_t i = 0; i < this->current_count_; i++) // Structure assignment. temp[i] = this->process_table_[i]; this->max_process_table_size_ = size; delete [] this->process_table_; this->process_table_ = temp; return 0; }

int ACE_Process_Manager::set_scheduler (  const ACE_Sched_Params &  params, pid_t  pid )

Sets the scheduling parameters for the managed by identified by pid by passing , to <ACE_OS::sched_params>. Returns 0 on success, -1 on failure, and ACE_INVALID_PID when given pid is not managed by . Definition at line 657 of file Process_Manager.cpp. References ACE_GUARD_RETURN, ACE_INVALID_PID, ACE_TRACE, find_proc(), pid_t, ACE_OS::sched_params(), and ssize_t. { ACE_TRACE ("ACE_Process_Manager::set_scheduler"); ACE_MT (ACE_GUARD_RETURN (ACE_Recursive_Thread_Mutex, ace_mon, this->lock_, -1)); // Check to see if the process identified by the given pid is managed by // this instance of ACE_Process_Manager. ssize_t const i = this->find_proc (pid); if (i == -1) // set "no such process" error return ACE_INVALID_PID; return ACE_OS::sched_params (params, pid); }

int ACE_Process_Manager::set_scheduler_all (  const ACE_Sched_Params &   )

Sets the scheduling parameters for all the es managed by by passing to <ACE_OS::sched_params>. Returns 0 on success, -1 on failure. Definition at line 677 of file Process_Manager.cpp. References ACE_GUARD_RETURN, ACE_TRACE, current_count_, ACE_Process::getpid(), pid_t, ACE_Process_Descriptor::process_, process_table_, and ACE_OS::sched_params(). { ACE_TRACE ("ACE_Process_Manager::set_scheduler_all"); ACE_MT (ACE_GUARD_RETURN (ACE_Recursive_Thread_Mutex, ace_mon, this->lock_, -1)); for (size_t i = 0; i < this->current_count_; ++i) { pid_t const pid = this->process_table_[i].process_->getpid (); if (ACE_OS::sched_params (params, pid) != 0) return -1; } return 0; }

pid_t ACE_Process_Manager::spawn (  ACE_Process_Options &  options, ACE_Event_Handler *  event_handler = 0 )

Create a new process by passing to <ACE_Process::spawn>. Register 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. Definition at line 422 of file Process_Manager.cpp. References ACE_INVALID_PID, ACE_NEW_RETURN, pid_t, and spawn(). { ACE_Process *process = 0; ACE_NEW_RETURN (process, ACE_Managed_Process, ACE_INVALID_PID); pid_t const pid = spawn (process, options, event_handler); if (pid == ACE_INVALID_PID || pid == 0) delete process; return pid; }

pid_t ACE_Process_Manager::spawn (  ACE_Process *  proc, ACE_Process_Options &  options, ACE_Event_Handler *  event_handler = 0 )

Create a new process by passing to <proc.spawn>. Register 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. Definition at line 440 of file Process_Manager.cpp. References ACE_GUARD_RETURN, ACE_INVALID_PID, ACE_TRACE, append_proc(), pid_t, and ACE_Process::spawn(). Referenced by spawn(), and spawn_n(). { ACE_TRACE ("ACE_Process_Manager::spawn"); pid_t const pid = process->spawn (options); // Only include the pid in the parent's table. if (pid == ACE_INVALID_PID || pid == 0) return pid; ACE_MT (ACE_GUARD_RETURN (ACE_Recursive_Thread_Mutex, ace_mon, this->lock_, -1)); if (this->append_proc (process, event_handler) == -1) // bad news: spawned, but not registered in table. return ACE_INVALID_PID; return 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 new processes by passing to <ACE_Process::spawn>, which is called times. If is non-0 it is expected to be an array of 's, which are filled in with the process ids of each newly created process. Register to be called back when each process exits. Returns 0 on success and -1 on failure. Definition at line 465 of file Process_Manager.cpp. References ACE_INVALID_PID, ACE_TRACE, pid_t, and spawn(). { ACE_TRACE ("ACE_Process_Manager::spawn_n"); if (child_pids != 0) for (size_t i = 0; i < n; ++i) child_pids[i] = ACE_INVALID_PID; for (size_t i = 0; i < n; i++) { pid_t const pid = this->spawn (options, event_handler); if (pid == ACE_INVALID_PID || pid == 0) // We're in the child or something's gone wrong. return pid; else if (child_pids != 0) child_pids[i] = pid; } return 0; }

int ACE_Process_Manager::terminate (  pid_t  pid, int  sig )

On OSs that support signals, send the signal to the specified process. Returns 0 on success and -1 on failure. Definition at line 637 of file Process_Manager.cpp. References ACE_GUARD_RETURN, ACE_TRACE, find_proc(), ACE_OS::kill(), pid_t, and ssize_t. { ACE_TRACE ("ACE_Process_Manager::terminate"); ACE_MT (ACE_GUARD_RETURN (ACE_Recursive_Thread_Mutex, ace_mon, this->lock_, -1)); // Check for duplicates and bail out if they're already // registered... ssize_t const i = this->find_proc (pid); if (i == -1) // set "no such process" error return -1; return ACE_OS::kill (pid, sig); }

int ACE_Process_Manager::terminate (  pid_t  pid  )

Abruptly terminate a single process with id using the <ACE::terminate_process> method. Note that this call is potentially dangerous to use since the process being terminated may not have a chance to cleanup before it shuts down. Returns 0 on success and -1 on failure. Definition at line 609 of file Process_Manager.cpp. References ACE_GUARD_RETURN, ACE_TRACE, find_proc(), pid_t, remove_proc(), ssize_t, and ACE::terminate_process(). { ACE_TRACE ("ACE_Process_Manager::terminate"); ACE_MT (ACE_GUARD_RETURN (ACE_Recursive_Thread_Mutex, ace_mon, this->lock_, -1)); // Check for duplicates and bail out if they're already // registered... ssize_t const i = this->find_proc (pid); if (i == -1) // set "no such process" error return -1; int const result = ACE::terminate_process (pid); if (result != -1) { // Save/restore errno. ACE_Errno_Guard error (errno); this->remove_proc (i); return 0; } return -1; }

pid_t ACE_Process_Manager::wait (  pid_t  pid, ACE_exitcode *  status = 0 )

Wait indefinitely for a single process to terminate. If pid==0, waits for any of the managed es (but see the note in the class documentation for caveats about this -- "sloppy Process cleanup on unix") If pid != 0, waits for that only. Returns the pid of the process whose exit was handled, or ACE_INVALID_PID on error. Definition at line 770 of file Process_Manager.cpp. References ACE_exitcode, ACE_TRACE, pid_t, and wait(). { ACE_TRACE ("ACE_Process_Manager::wait"); return this->wait (pid, ACE_Time_Value::max_time, status); }

pid_t ACE_Process_Manager::wait (  pid_t  pid, const ACE_Time_Value &  timeout, ACE_exitcode *  status = 0 )

Wait up to for a single process to terminate. If pid==0, waits for any of the managed es (but see the note in the class documentation above for caveats about this -- "sloppy process cleanup on unix") If pid != 0, waits for that only. Returns the pid of the Process whose exit was handled, 0 if a timeout occurred, or ACE_INVALID_PID on error. Definition at line 785 of file Process_Manager.cpp. References ACE_ASSERT, ACE_DEBUG, ACE_ERROR_RETURN, ACE_exitcode, ACE_GUARD_RETURN, ACE_INVALID_PID, ACE_LIB_TEXT, ACE_NEW_RETURN, ACE_SignalHandler, ACE_TRACE, current_count_, find_proc(), ACE_Process::gethandle(), ACE_Process::getpid(), LM_DEBUG, LM_ERROR, ACE_Time_Value::msec(), notify_proc_handler(), pid_t, ACE_Process_Descriptor::process_, process_table_, ACE_Event_Handler::reactor(), ACE_Sig_Action::register_action(), remove(), remove_proc(), SIGCHLD, ACE_OS::sleep(), ssize_t, ACE_Countdown_Time::update(), ACE_Process::wait(), ACE_OS::waitpid(), and WNOHANG. { ACE_TRACE ("ACE_Process_Manager::wait"); ACE_exitcode local_stat = 0; if (status == 0) status = &local_stat; *status = 0; ssize_t idx = -1; ACE_Process *proc = 0; ACE_MT (ACE_GUARD_RETURN (ACE_Recursive_Thread_Mutex, ace_mon, this->lock_, -1)); if (pid != 0) { idx = this->find_proc (pid); if (idx == -1) return ACE_INVALID_PID; else proc = process_table_[idx].process_; } if (proc != 0) pid = proc->wait (timeout, status); else { // Wait for any Process spawned by this Process_Manager. #if defined (ACE_WIN32) HANDLE *handles = 0; ACE_NEW_RETURN (handles, HANDLE[this->current_count_], ACE_INVALID_PID); for (size_t i = 0; i < this->current_count_; ++i) handles[i] = process_table_[i].process_->gethandle (); DWORD handle_count = static_cast<DWORD> (this->current_count_); DWORD result = ::WaitForMultipleObjects (handle_count, handles, FALSE, timeout == ACE_Time_Value::max_time ? INFINITE : timeout.msec ()); if (result == WAIT_FAILED) pid = ACE_INVALID_PID; else if (result == WAIT_TIMEOUT) pid = 0; else { // Green Hills produces a warning that result >= WAIT_OBJECT_0 is // a pointless comparison because WAIT_OBJECT_0 is zero and DWORD is // unsigned long, so this test is skipped for Green Hills. // Same for mingw. # if defined (ghs) || defined (__MINGW32__) || (defined (_MSC_VER) && _MSC_VER >= 1300) ACE_ASSERT (result < WAIT_OBJECT_0 + this->current_count_); # else ACE_ASSERT (result >= WAIT_OBJECT_0 && result < WAIT_OBJECT_0 + this->current_count_); # endif idx = this->find_proc (handles[result - WAIT_OBJECT_0]); if (idx != -1) { pid = process_table_[idx].process_->getpid (); result = ::GetExitCodeProcess (handles[result - WAIT_OBJECT_0], status); if (result == 0) { // <GetExitCodeProcess> failed! this->remove_proc (idx); pid = ACE_INVALID_PID; } } else { // uh oh...handle removed from process_table_, even though // we're holding a lock! delete [] handles; ACE_ERROR_RETURN ((LM_ERROR, ACE_LIB_TEXT ("Process removed") ACE_LIB_TEXT (" -- somebody's ignoring the lock!\n")), -1); } } delete [] handles; #else /* !defined(ACE_WIN32) */ if (timeout == ACE_Time_Value::max_time) { pid = ACE_OS::waitpid (-1, status, 0); } else if (timeout == ACE_Time_Value::zero) { pid = ACE_OS::waitpid (-1, status, WNOHANG); } else { # if defined (ACE_LACKS_UNIX_SIGNALS) pid = 0; ACE_Time_Value sleeptm (1); // 1 msec if (sleeptm > timeout) // if sleeptime > waittime sleeptm = timeout; ACE_Time_Value tmo (timeout); // Need one we can change for (ACE_Countdown_Time time_left (&tmo); tmo > ACE_Time_Value::zero ; time_left.update ()) { pid = ACE_OS::waitpid (-1, status, WNOHANG); if (pid > 0 || pid == ACE_INVALID_PID) break; // Got a child or an error - all done // pid 0, nothing is ready yet, so wait. // Do a (very) short sleep (only this thread sleeps). ACE_OS::sleep (sleeptm); } # else // Force generation of SIGCHLD, even though we don't want to // catch it - just need it to interrupt the sleep below. // If this object has a reactor set, assume it was given at // open(), and there's already a SIGCHLD action set, so no // action is needed here. ACE_Sig_Action old_action; if (this->reactor () == 0) { ACE_Sig_Action do_sigchld ((ACE_SignalHandler)sigchld_nop); do_sigchld.register_action (SIGCHLD, &old_action); } ACE_Time_Value tmo (timeout); // Need one we can change for (ACE_Countdown_Time time_left (&tmo); ; time_left.update ()) { pid = ACE_OS::waitpid (-1, status, WNOHANG); # if defined (ACE_VXWORKS) && (ACE_VXWORKS >= 0x600) if (pid > 0 || (pid == ACE_INVALID_PID && errno != EINTR)) # else if (pid > 0 || pid == ACE_INVALID_PID) # endif break; // Got a child or an error - all done // pid 0, nothing is ready yet, so wait. // Do a sleep (only this thread sleeps) til something // happens. This relies on SIGCHLD interrupting the sleep. // If SIGCHLD isn't delivered, we'll need to do something // with sigaction to force it. if (-1 == ACE_OS::sleep (tmo) && errno == EINTR) continue; // Timed out pid = 0; break; } // Restore the previous SIGCHLD action if it was changed. if (this->reactor () == 0) { old_action.register_action (SIGCHLD); } # endif /* !ACE_LACKS_UNIX_SIGNALS */ } #endif /* !defined (ACE_WIN32) */ } if (pid != ACE_INVALID_PID && pid != 0) { if (proc == 0) { idx = this->find_proc (pid); if (idx == -1) { // oops, reaped an unmanaged process! ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("(%P|%t) oops, reaped unmanaged %d\n"), pid)); return pid; } else proc = process_table_[idx].process_; } else ACE_ASSERT (pid == proc->getpid ()); this->notify_proc_handler (idx, *status); this->remove (pid); } return pid; }

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 ed by this . Unlike the call below, this method does not require a signal handler or <ACE_OS::sigwait> because it simply blocks synchronously waiting for all the children managed by this 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. Returns 0 on success (and s the corresponding entries from the ; otherwise, returns -1 on failure. Definition at line 731 of file Process_Manager.cpp. References ACE_INVALID_PID, ACE_TRACE, current_count_, ACE_OS::gettimeofday(), and pid_t. Referenced by reap(), and wait(). { ACE_TRACE ("ACE_Process_Manager::wait"); ACE_Time_Value until = timeout; ACE_Time_Value remaining = timeout; if (until < ACE_Time_Value::max_time) until += ACE_OS::gettimeofday (); while (this->current_count_ > 0) { pid_t const pid = this->wait (0, remaining); if (pid == ACE_INVALID_PID) // wait() failed return -1; else if (pid == 0) // timeout break; remaining = until < ACE_Time_Value::max_time ? until - ACE_OS::gettimeofday () : ACE_Time_Value::max_time; if (remaining <= ACE_Time_Value::zero) break; // else Process terminated...wait for more... } return static_cast<int> (this->current_count_); }

---

Friends And Related Function Documentation

friend class ACE_Process_Control [friend]

Definition at line 127 of file Process_Manager.h.

---

Member Data Documentation

ACE_Process_Manager::ACE_ALLOC_HOOK_DECLARE

Declare the dynamic allocation hooks. Definition at line 326 of file Process_Manager.h.

size_t ACE_Process_Manager::current_count_ [private]

Current number of processes we are managing. Definition at line 416 of file Process_Manager.h. Referenced by append_proc(), close(), dump(), find_proc(), managed(), notify_proc_handler(), remove_proc(), resize(), set_scheduler_all(), and wait().

ACE_Event_Handler* ACE_Process_Manager::default_exit_handler_ [private]

This event handler is used to notify when a process we control exits. Definition at line 420 of file Process_Manager.h. Referenced by close(), notify_proc_handler(), and register_handler().

int ACE_Process_Manager::delete_instance_ = 0 [static, private]

Controls whether the is deleted when we shut down (we can only delete it safely if we created it!) Definition at line 62 of file Process_Manager.cpp. Referenced by close_singleton(), and instance().

ACE_Process_Manager * ACE_Process_Manager::instance_ = 0 [static, private]

Singleton pointer. Definition at line 58 of file Process_Manager.cpp. Referenced by close_singleton(), and instance().

ACE_Recursive_Thread_Mutex ACE_Process_Manager::lock_ [private]

This lock protects access/ops on . Definition at line 431 of file Process_Manager.h.

size_t ACE_Process_Manager::max_process_table_size_ [private]

Maximum number of processes we can manage (should be dynamically allocated). Definition at line 413 of file Process_Manager.h. Referenced by append_proc(), close(), open(), and resize().

ACE_Process_Descriptor* ACE_Process_Manager::process_table_ [private]

Vector that describes process state within the Process_Manager. Definition at line 409 of file Process_Manager.h. Referenced by append_proc(), close(), dump(), find_proc(), handle_signal(), notify_proc_handler(), register_handler(), remove_proc(), resize(), set_scheduler_all(), and wait().

---

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

• Process_Manager.h
• Process_Manager.cpp
• Process_Manager.inl

---