ACE_Process Class Reference

A portable encapsulation for creating and managing new processes. More...

#include <Process.h>

Inheritance diagram for ACE_Process:

Collaboration diagram for ACE_Process:

Public Member Functions
	ACE_Process (void)
	Default construction. Use ACE_Process::spawn() to start a process. More...
virtual	~ACE_Process (void)
	Destructor. More...
virtual int	prepare (ACE_Process_Options &options)
virtual pid_t	spawn (ACE_Process_Options &options)
virtual void	parent (pid_t child)
virtual void	child (pid_t parent)
virtual void	unmanage (void)
pid_t	wait (ACE_exitcode *status=0, int wait_options=0)
pid_t	wait (const ACE_Time_Value &tv, ACE_exitcode *status=0)
int	kill (int signum=SIGINT)
int	terminate (void)
pid_t	getpid (void) const
	Return the process id of the new child process. More...
ACE_HANDLE	gethandle (void) const
	Return the handle of the process, if it has one. More...
int	running (void) const
	Return 1 if running; 0 otherwise. More...
ACE_exitcode	exit_code (void) const
int	return_value (void) const
void	close_dup_handles (void)
void	close_passed_handles (void)
PROCESS_INFORMATION	process_info (void)

Protected Member Functions
void	exit_code (ACE_exitcode code)

Protected Attributes
PROCESS_INFORMATION	process_info_
ACE_exitcode	exit_code_
ACE_Handle_Set	handles_passed_
	Set of handles that were passed to the child process. More...
ACE_Handle_Set	dup_handles_
	Handle duplicates made for the child process. More...

Private Member Functions
	ACE_Process (const ACE_Process &)
void	operator= (const ACE_Process &)
wchar_t *	convert_env_buffer (const char *env) const

Friends
class	ACE_Process_Manager

Detailed Description

A portable encapsulation for creating and managing new processes.

ACE_Process provides a convenient way to:

• Spawn child processes, with convenient hooks for pre- and post-spawn actions
• Check if a spawned process is still running
• Kill a spawned child process
• Wait for a spawned child process to exit.

See also

ACE_Process_Options because it is used to pass options when spawning child processes.

ACE_Process_Manager for additional ways to manage spawned processes.

Constructor & Destructor Documentation

ACE_Process::ACE_Process

(

void

)

Default construction. Use ACE_Process::spawn() to start a process.

ACE_Process::~ACE_Process ( void  )

virtual

Destructor.

ACE_Process::ACE_Process ( const ACE_Process &  )

private

Member Function Documentation

void ACE_Process::child ( pid_t  parent )

virtual

Called back from spawn() in the child's context just after forking. The default does nothing.

Note

This function is not called on Windows because the process-creation scheme does not allow it.

void ACE_Process::close_dup_handles

(

void

)

Close all the handles in the set obtained from the ACE_Process_Options::dup_handles object used to spawn the process.

void ACE_Process::close_passed_handles

(

void

)

Close all the passed handles in the set obtained from the ACE_Process_Options object used to spawn the process.

wchar_t * ACE_Process::convert_env_buffer ( const char *  env ) const

private

ACE_exitcode ACE_Process::exit_code ( void  ) const

inline

Return the process's exit code. This method returns the raw exit status returned from system APIs (such as wait() or waitpid() ). This value is system dependent.

void ACE_Process::exit_code ( ACE_exitcode  code )

inlineprotected

Set this process's exit code. ACE_Process_Manager uses this method to set the exit code after successfully waiting for this process to exit.

ACE_HANDLE ACE_Process::gethandle ( void  ) const

inline

Return the handle of the process, if it has one.

pid_t ACE_Process::getpid ( void  ) const

inline

Return the process id of the new child process.

int ACE_Process::kill ( int  signum = SIGINT )

inline

Send the process a signal. This only has an effect on operating systems that support signals, such as UNIX/POSIX.

void ACE_Process::operator= ( const ACE_Process &  )

private

void ACE_Process::parent ( pid_t  child )

virtual

Called back from spawn() in the parent's context just after forking, if the fork succeeds. The default simply returns.

int ACE_Process::prepare ( ACE_Process_Options &  options )

virtual

Called back from spawn() just before spawning the child. If this returns non-zero, the spawn is aborted (and returns ACE_INVALID_PID). The default returns zero.

PROCESS_INFORMATION ACE_Process::process_info ( void  )

inline

int ACE_Process::return_value ( void  ) const

inline

Return the process's return value. This method returns the actual return value that a child process returns or exits with.

int ACE_Process::running

(

void

)

const

Return 1 if running; 0 otherwise.

pid_t ACE_Process::spawn ( ACE_Process_Options &  options )

virtual

Launch a new process as described by options.

Return values

-1	on failure; check errno for error code.
1	on success if the option avoid_zombies is set.
other	the process id of the newly spawned child.

Note

The return value 1 may be changed in future versions of ACE to be the process id of the child will be returned regardless of the avoid_zombies option.

On UNIX platforms, spawn() uses the execvp() system call if ACE_Process_Options::inherit_environment() returns true (which is the default) and execve() if not. Since execve() does not search PATH, the ACE_Process_Options::command_line() should include a full path to the program file.

int ACE_Process::terminate ( void  )

inline

Terminate the process abruptly using ACE::terminate_process(). This call doesn't give the process a chance to cleanup, so use it with caution.

void ACE_Process::unmanage ( void  )

virtual

Called by a ACE_Process_Manager that is removing this object from its table of managed processes. Default is to do nothing.

Reimplemented in ACE_Managed_Process.

pid_t ACE_Process::wait ( ACE_exitcode *  status = 0, int  wait_options = 0  )

inline

Wait for a previously spawned process to exit.

• status Points to a location to receive the exit status of the spawned process. Ignored if the value is 0.
• wait_options If WNOHANG then return 0 and don't block if the child process hasn't exited yet.

Return values

-1	the wait operation failed; consult errno for details.
other	the child process id is returned on success.

pid_t ACE_Process::wait	(	const ACE_Time_Value &	tv,
		ACE_exitcode *	status = 0
	)

Timed wait for a previously spawned process to exit.

• tv A relative amount of time to wait for the process to exit.
• status Points to a location to receive the exit status of the spawned process. Ignored if the value is 0.

Return values

0	the specified time period elapsed before the process exited.
-1	the wait operation failed; consult errno for details.
other	the child process id is returned on success.

Note

On UNIX platforms this function uses ualarm(), i.e., it overwrites any existing alarm. In addition, it steals all SIGCHLD signals during the timeout period, which will break another ACE_Process_Manager in the same process that's expecting SIGCHLD to kick off process reaping.

Friends And Related Function Documentation

friend class ACE_Process_Manager

friend

Member Data Documentation

ACE_Handle_Set ACE_Process::dup_handles_

protected

Handle duplicates made for the child process.

ACE_exitcode ACE_Process::exit_code_

protected

ACE_Handle_Set ACE_Process::handles_passed_

protected

Set of handles that were passed to the child process.

PROCESS_INFORMATION ACE_Process::process_info_

protected

---

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

• Process.h
• Process.cpp
• Process.inl