ACE  6.3.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Public Member Functions | Protected Member Functions | Protected Attributes | Private Member Functions | Friends | List of all members
ACE_Process Class Reference

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

#include <Process.h>

Inheritance diagram for ACE_Process:
Inheritance graph
[legend]
Collaboration diagram for ACE_Process:
Collaboration graph
[legend]

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:

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
-1on failure; check errno for error code.
1on success if the option avoid_zombies is set.
otherthe 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
-1the wait operation failed; consult errno for details.
otherthe 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
0the specified time period elapsed before the process exited.
-1the wait operation failed; consult errno for details.
otherthe 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: