diff options
Diffstat (limited to 'ACE/ace/Process_Manager.h')
| -rw-r--r-- | ACE/ace/Process_Manager.h | 449 |
1 files changed, 449 insertions, 0 deletions
diff --git a/ACE/ace/Process_Manager.h b/ACE/ace/Process_Manager.h new file mode 100644 index 00000000000..050c2f47e2e --- /dev/null +++ b/ACE/ace/Process_Manager.h @@ -0,0 +1,449 @@ +// -*- C++ -*- + +//============================================================================= +/** + * @file Process_Manager.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + +#ifndef ACE_PROCESS_MANAGER_H +#define ACE_PROCESS_MANAGER_H + +#include /**/ "ace/pre.h" + +#include "ace/ACE_export.h" + +#if !defined (ACE_LACKS_PRAGMA_ONCE) +# pragma once +#endif /* ACE_LACKS_PRAGMA_ONCE */ + +#include "ace/Process.h" +#include "ace/Event_Handler.h" +#include "ace/Time_Value.h" + +#if defined (ACE_HAS_THREADS) +# include "ace/Recursive_Thread_Mutex.h" +#endif /* ACE_HAS_THREADS */ + +ACE_BEGIN_VERSIONED_NAMESPACE_DECL + +class ACE_Reactor; + +/** + * @class ACE_Process_Descriptor + * + * @brief Information describing each process that's controlled by an + * \<ACE_Process_Manager\>. + */ +class ACE_Export ACE_Process_Descriptor +{ +private: + friend class ACE_Process_Manager; + + /// Default ctor/dtor. + ACE_Process_Descriptor (void); + ~ACE_Process_Descriptor (void); + + /// Describes the process itself. + ACE_Process *process_; + + /// function to call when process exits + ACE_Event_Handler *exit_notify_; + + /// Dump the state of an object. + void dump (void) const; +}; + +/** + * @class ACE_Process_Manager + * + * @brief 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 <ACE_Process>es. If you just want <Process>es to + * go away when they're finished, simply register the + * <Process_Manager> with an \<ACE_Reactor\>: + * ACE_Process_Manager mgr( 100, some_reactor ) + * -or- + * ACE_Process_Manager mgr; + * ... + * mgr.open( 100, some_reactor ); + * Then, the <Process_Manager> will clean up after any + * <Process>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 <Process> cleanup + * code, then *don't* register the <Process_Manager> with a + * Reactor, and be sure to call one of the + * <Process_Manager::wait> functions whenever there might be + * managed <Process>es that have exited. + * Note that in either case, <Process_Manager> allows you to + * register "<Event_Handlers>" to be called when a specific + * <Process> exits, or when any <Process> without a specific + * <Event_Handler> exits. When a <Process> exits, the + * appropriate <Event_Handler>'s <handle_input> 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 <Process_Manager> is registered with + * a <Reactor>. + * 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 <Process_Manager> whose <wait> you invoked. It's best to + * only use a single <Process_Manager>, and to create all + * subprocesses by calling that <Process_Manager>'s <spawn> + * method. + * Incidentally, when you register your <Process_Manager> with a + * <Reactor> its notification pipe is used to help "reap" the + * available exit statuses. Therefore, you must not use a + * <Reactor> whose notify pipe has been disabled. Here's the + * sequence of steps used to reap the exit statuses in this case: + * + The <Process_Manager> registers a signal handler for + * SIGCHLD. + * + The SIGCHLD handler, when invoked, uses the <Reactor>'s + * <notify> method to inform the <Reactor> to wake up. + * + Next, the <Reactor> calls the <Process_Manager>'s + * <handle_input>, this happens synchronously, not in + * sighandler-space. + * + The <handle_input> method collects all available exit + * statuses. + */ +class ACE_Export ACE_Process_Manager : protected ACE_Event_Handler +{ +public: + friend class ACE_Process_Control; + + enum + { + DEFAULT_SIZE = 100 + }; + + // = Initialization and termination methods. + /** + * Initialize an <ACE_Process_Manager> with a table containing up to + * <size> processes. This table resizes itself automatically as + * needed. If a non-NULL <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. + */ + 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 non-NULL <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 open (size_t size = DEFAULT_SIZE, + ACE_Reactor *r = 0); + + /// Release all resources. Do not wait for processes to exit. + int close (void); + + /// Destructor releases all resources and does not wait for processes + /// to exit. + virtual ~ACE_Process_Manager (void); + + // = Singleton accessors. + /// Get pointer to a process-wide <ACE_Process_Manager>. + static ACE_Process_Manager *instance (void); + + /// Set pointer to a process-wide <ACE_Process_Manager> and return + /// existing pointer. + static ACE_Process_Manager *instance (ACE_Process_Manager *); + + /// Delete the dynamically allocated singleton. + static void close_singleton (void); + + /// Cleanup method, used by the <ACE_Object_Manager> to destroy the + /// singleton. + static void cleanup (void *instance, void *arg); + + // = Process creation methods. + + /** + * Create a new process by passing <options> to <proc.spawn>. + * 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. + */ + pid_t spawn (ACE_Process *proc, + ACE_Process_Options &options, + ACE_Event_Handler *event_handler = 0); + + /** + * Create a new process by passing <options> to <ACE_Process::spawn>. + * 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. + */ + pid_t spawn (ACE_Process_Options &options, + ACE_Event_Handler *event_handler = 0); + + /** + * Create <n> new processes by passing <options> to + * <ACE_Process::spawn>, which is called <n> times. If <child_pids> + * is non-0 it is expected to be an array of <n> <pid_t>'s, which + * are filled in with the process ids of each newly created process. + * Register <event_handler> to be called back when each process exits. + * Returns 0 on success and -1 on failure. + */ + int spawn_n (size_t n, + ACE_Process_Options &options, + pid_t *child_pids = 0, + ACE_Event_Handler *event_Handler = 0); + + // = Process synchronization operations. + + /** + * Block until there are no more child processes running that were + * @c spawn()ed by this @c ACE_Process_Manager. Unlike the @c wait + * call below, this method does not require a signal handler or + * @c ACE_OS::sigwait because it simply blocks synchronously waiting + * for all the children managed by this @c 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. Returns 0 on success + * (and @c remove()s the corresponding @c ACE_Process_Descriptor + * entries from the @c Process_Manager; otherwise, returns -1 on + * failure. + * + * @param timeout Relative time to wait for process to terminate + */ + int wait (const ACE_Time_Value &timeout = ACE_Time_Value::max_time); + + /** + * Wait up to @a timeout for a single process to terminate. If + * pid==0, waits for any of the managed <Process>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 <Process> + * only. Returns the pid of the Process whose exit was handled, 0 + * if a timeout occurred, or ACE_INVALID_PID on error. + * + * @param pid Process ID + * @param timeout Relative time to wait for process to terminate + * @param status Exit status of terminated process + */ + pid_t wait (pid_t pid, + const ACE_Time_Value &timeout, + ACE_exitcode *status = 0); + + /** + * Wait indefinitely for a single process to terminate. If pid==0, + * waits for any of the managed <Process>es (but see the note in + * the class documentation for caveats about this -- "sloppy Process + * cleanup on unix") If pid != 0, waits for that <Process> only. + * Returns the pid of the process whose exit was handled, or + * ACE_INVALID_PID on error. + */ + pid_t wait (pid_t pid, + ACE_exitcode *status = 0); + + /** + * @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, <remove> is called automatically. This + * method does the same thing that the <wait> method directly above + * it does -- It's just here for backwards compatibility. + */ + int reap (pid_t pid = -1, + ACE_exitcode *stat_loc = 0, + int options = WNOHANG); + + // = Utility methods. + /** + * 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. + */ + int register_handler (ACE_Event_Handler *event_handler, + pid_t pid = ACE_INVALID_PID); + + /** + * Remove process <pid> from the table. This is called + * automatically by the <reap> method after it successfully reaped a + * <SIGCHLD> signal. It's also possible to call this method + * directly from a signal handler, but don't call both <reap> and + * <remove>! + */ + int remove (pid_t pid); + + /** + * Abruptly terminate a single process with id <pid> 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. + */ + int terminate (pid_t pid); + + /// On OSs that support signals, send the signal to the specified + /// process. Returns 0 on success and -1 on failure. + int terminate (pid_t pid, + int sig); + + /// Return the number of managed Processes. + size_t managed (void) const; + /** + * Sets the scheduling parameters for the <Process> managed by + * <ACE_Process_Manager> identified by pid by passing <params>, <pid> to + * <ACE_OS::sched_params>. Returns 0 on success, -1 on failure, and + * ACE_INVALID_PID when given pid is not managed by + * <ACE_Process_Manager>. + */ + int set_scheduler (const ACE_Sched_Params ¶ms, + pid_t pid); + + /** + * Sets the scheduling parameters for all the <Process>es managed by + * <ACE_Process_Manager> by passing <params> to + * <ACE_OS::sched_params>. Returns 0 on success, -1 on failure. + */ + int set_scheduler_all (const ACE_Sched_Params &); + + /// Dump the state of an object. + void dump (void) const; + + /// Declare the dynamic allocation hooks. + ACE_ALLOC_HOOK_DECLARE; + +protected: + // = These methods allow a <Process_Manager> to be an <Event_Handler>. + + // As an <Event_Handler>, the <Process_Manager> automagically + // detects child Processes exiting and calls notify_proc_handler() + // and remove(). This means that you don't have to (shouldn't!) + // call the wait(...) methods yourself. + + // On Unix, we can't detect individual process termination very + // well; the best method is to catch SIGCHLD and then call the + // polling wait() function to collect any available exit statuses. + // However, we don't want to do this from within a signal handler + // because of the restrictions associated. Therefore (following the + // lead in examples/mumble) we open a bogus handle (to ACE_DEV_NULL) + // and register that handle with our Reactor. Then, when our + // SIGCHLD handler gets invoked, we tell the Reactor that the bogus + // handle is readable. That will cause the handle_input() function + // to be called once we're out of the interrupt context, and + // handle_input() collects exit statuses. + + // On Win32, we simply register ourself with the Reactor to deal + // with the Process handle becoming signaled. No muss, no fuss, no + // signal handler, and no dummy handle. + +#if !defined(ACE_WIN32) + /// Collect one (or more, on unix) process exit status. + virtual int handle_input (ACE_HANDLE proc); +#endif // !defined(ACE_WIN32) + + /** + * 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 + */ + virtual int handle_signal (int signum, + siginfo_t * = 0, + ucontext_t * = 0); + +private: + /// Resize the pool of Process_Descriptors. + int resize (size_t); + + /// Locate the index of the table slot occupied by <process_id>. + /// Returns -1 if <process_id> is not in the <process_table_> + ssize_t find_proc (pid_t process_id); + +#if defined (ACE_WIN32) + /// Locate the index of the table slot occupied by <process_handle>. + /// Returns ~0 if <process_handle> is not in the <process_table_> + ssize_t find_proc (ACE_HANDLE process_handle); +#endif /* ACE_WIN32 */ + + /// 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. + int insert_proc (ACE_Process *process, + ACE_Event_Handler *event_handler = 0); + + /** + * 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. + */ + int append_proc (ACE_Process *process, + ACE_Event_Handler *event_handler = 0); + + /// Actually removes the process at index <n> from the table. This method + /// must be called with locks held. + int remove_proc (size_t n); + + /// If there's a specific handler for the Process at index <n> in the + /// table, or there's a default handler, call it. + int notify_proc_handler (size_t n, + ACE_exitcode status); + + /// Vector that describes process state within the Process_Manager. + ACE_Process_Descriptor *process_table_; + + /// Maximum number of processes we can manage (should be dynamically + /// allocated). + size_t max_process_table_size_; + + /// Current number of processes we are managing. + size_t current_count_; + + /// This event handler is used to notify when a process we control + /// exits. + ACE_Event_Handler *default_exit_handler_; + + /// Singleton pointer. + static ACE_Process_Manager *instance_; + + /// Controls whether the <Process_Manager> is deleted when we shut + /// down (we can only delete it safely if we created it!) + static int delete_instance_; + +#if defined (ACE_HAS_THREADS) + /// This lock protects access/ops on <process_table_>. + ACE_Recursive_Thread_Mutex lock_; +#endif /* ACE_HAS_THREADS */ +}; + +ACE_END_VERSIONED_NAMESPACE_DECL + +#if defined (__ACE_INLINE__) +#include "ace/Process_Manager.inl" +#endif /* __ACE_INLINE__ */ + +#include /**/ "ace/post.h" +#endif /* ACE_PROCESS_MANAGER_H */ |