Loading...
Searching...
No Matches
ASSA::Fork Class Reference

Fork class is a simple wrapper around C library function fork(). More...

`#include <Fork.h>`

## Public Types

enum | state_t { KILL_ON_EXIT , WAIT_ON_EXIT , LEAVE_ALONE }
| Child completion states. More...
enum | wait4status_t { IGNORE_STATUS , COLLECT_STATUS }

## Public Member Functions

| Fork (state_t exit_action_=WAIT_ON_EXIT, wait4status_t catch_status_=COLLECT_STATUS)
| Fork the current process in two immediately.
| ~Fork ()
| Destructor.
bool | isParent () const
| Test whether we are in parent section of the code.
bool | isChild () const
| Test whether we are in child section of the code.
pid_t | getChildPID () const
| Retrieve child process id.
int | get_exit_status () const
| Retrieve exit status of a child process if the constructor's parameter catch_status_ was set to TRUE.

## Static Public Member Functions

static int | fork_exec (const string &cmd_, const string &args_, wait4status_t wait_for_completion_, bool ignore_output_=false)
| Execute an external command.

## Private Attributes

pid_t | m_pid
| Child pid.
SigHandler | m_local_sh
| Local signal handler.
ChildStatusHandler | m_chstath
| Handler to catch Child's status.
SigAction | m_old_disp
| Old signal disposition.

## Detailed Description

Fork class is a simple wrapper around C library function fork().

Main advantage of using Fork over fork() is that child termination process is handles internally by Fork class static destructor.

Definition at line 86 of file Fork.h.

## Member Enumeration Documentation

## state_t

enum ASSA::Fork::state_t

Child completion states.

Enumerator
KILL_ON_EXIT | Kill all childer on exit.
WAIT_ON_EXIT | Wait for all children to exit.
LEAVE_ALONE | Ignore all running children on exit.

Definition at line 91 of file Fork.h.

{
KILL_ON_EXIT,
WAIT_ON_EXIT,
LEAVE_ALONE
};
ASSA::Fork::KILL_ON_EXIT
@ KILL_ON_EXIT
Kill all childer on exit.
Definition Fork.h:92
ASSA::Fork::WAIT_ON_EXIT
@ WAIT_ON_EXIT
Wait for all children to exit.
Definition Fork.h:93
ASSA::Fork::LEAVE_ALONE
@ LEAVE_ALONE
Ignore all running children on exit.
Definition Fork.h:94

## wait4status_t

enum ASSA::Fork::wait4status_t

Enumerator
IGNORE_STATUS | Don't wait for child to complete.
COLLECT_STATUS | Wait for child to complete and collect its exit status.

Definition at line 99 of file Fork.h.

{
IGNORE_STATUS,
COLLECT_STATUS
};
ASSA::Fork::COLLECT_STATUS
@ COLLECT_STATUS
Wait for child to complete and collect its exit status.
Definition Fork.h:101
ASSA::Fork::IGNORE_STATUS
@ IGNORE_STATUS
Don't wait for child to complete.
Definition Fork.h:100

## Constructor & Destructor Documentation

## Fork()

Fork::Fork | ( | Fork::state_t | exit_action_ = `WAIT_ON_EXIT`,
|  | Fork::wait4status_t | catch_status_ = `COLLECT_STATUS`
| ) |  |

Fork the current process in two immediately.

Parameters

  exit_action_ | Specify (default=WAIT_ON_EXIT) whether to wait for the child to finish or kill it with SIGTERM on process exit.
  catch_status_ | If true (default=COLLECT_STATUS), pause for the child to exit and collect its exit status.

Definition at line 159 of file Fork.cpp.

{
trace_with_mask("Fork::Fork",FORK);
if (catch_status_ == COLLECT_STATUS) {
m_local_sh.install (SIGCHLD, &m_chstath, 0, 0, &m_old_disp);
}
if ((m_pid = fork()) < 0) {
EL((ASSAERR,"failed to fork() - out of swap space?\n"));
exit (1); // die right here
}
if (m_pid) { // The Parent
if (exit_action_ != LEAVE_ALONE) {
ForkList::get_instance()->m_list.push_back (new fnode_t (m_pid, exit_action_));
}
if (catch_status_ == COLLECT_STATUS) {
if (! m_chstath.caught ()) {
pause ();
}
m_local_sh.remove (SIGCHLD, &m_chstath, &m_old_disp, 0);
}
}
}
EL
#define EL(X)
A macro for writing error message to the Logger.
Definition Logger.h:285
trace_with_mask
#define trace_with_mask(s, m)
trace_with_mask() is used to trace function call chain in C++ program.
Definition Logger.h:437
ASSA::AutoPtrRef
A wrapper class to provide AutoPtr with reference semantics.
Definition AutoPtr.h:32
ASSA::ChildStatusHandler::caught
bool caught() const
Definition Fork.h:73
ASSA::Fork::m_pid
pid_t m_pid
Child pid.
Definition Fork.h:178
ASSA::Fork::m_old_disp
SigAction m_old_disp
Old signal disposition.
Definition Fork.h:187
ASSA::Fork::m_local_sh
SigHandler m_local_sh
Local signal handler.
Definition Fork.h:181
ASSA::Fork::m_chstath
ChildStatusHandler m_chstath
Handler to catch Child's status.
Definition Fork.h:184
ASSA::SigHandler::remove
virtual int remove(int signum_, EventHandler *eh_=0, SigAction *new_disp_=0, SigAction *old_disp_=0)
Remove EventHandler associated with signum_.
Definition SigHandler.cpp:107
ASSA::SigHandler::install
virtual int install(int signum_, EventHandler *new_hand_, SigAction *new_disp_=0, EventHandler **old_hand_=0, SigAction *old_disp_=0)
Add new signal handler and new disposition for the signal.
Definition SigHandler.cpp:70
ASSA::Singleton< ForkList >::get_instance
static ForkList * get_instance()
Return an instance of templated class T.
Definition Singleton.h:47
ASSA::fnode_t
forknode_t class.
Definition Fork.h:195
ASSA::FORK
@ FORK
Class Fork messages
Definition LogMask.h:47
ASSA::ASSAERR
@ ASSAERR
ASSA and system errors
Definition LogMask.h:34

References ASSA::ASSAERR, ASSA::ChildStatusHandler::caught(), COLLECT_STATUS, EL, ASSA::FORK, ASSA::Singleton< ForkList >::get_instance(), ASSA::SigHandler::install(), LEAVE_ALONE, m_chstath, m_local_sh, m_old_disp, m_pid, ASSA::SigHandler::remove(), and trace_with_mask.

## ~Fork()

ASSA::Fork::~Fork | ( |  | ) |

inline

Destructor.

Doesn't really do anything. All children will be terminated according to state set when process terminates.

Definition at line 124 of file Fork.h.

{ trace_with_mask("Fork::~Fork",FORK); }

References ASSA::FORK, and trace_with_mask.

## Member Function Documentation

## fork_exec()

int Fork::fork_exec | ( | const string & | cmd_,
|  | const string & | args_,
|  | Fork::wait4status_t | wait_for_completion_,
|  | bool | ignore_output_ = `false`
| ) |  |

static

Execute an external command.

Conveniently wraps fork()/execvp()/wait() sequence of calls.

Parameters

  cmd_ | Command to execute.
  args_ | Command arguments as one string.
  wait_for_completion_ | If set to true, blocks until child exits; false otherwise.
  ignore_output_ | Discard child's output to stdout/stderr.

Returns
  If wait_for_completion_ is false, returns child PID; If wait_for_completion_ is true, returns command exit status: 0 returned means that command succeeded; 1 that it failed; -1 that wait(2) failed (where it shouldn't).

Close all file descriptors and reduped stdout/stderr to /dev/null

Definition at line 62 of file Fork.cpp.

{
trace_with_mask("Fork[static]::fork_exec",FORK);
DL((FORK,"exec \"%s %s\")\n", cmd_.c_str (), args_.c_str ()));
if (cmd_.size () == 0) {
return -1;
}
#if defined(WIN32)
return -1; // NOT IMPLEMENTED YET
#else
Fork f (Fork::LEAVE_ALONE, wait_for_completion_);
if (f.isChild ()) {
string arg_list (cmd_);
arg_list += " " + args_;
int argc = 0;
char** argv = 0;
CmdLineOpts::str_to_argv (arg_list, argc, argv);
if (ignore_output_) {
for (int i = 0; i < 1024; i++) {
(void) close(i);
}
pid_t nullfd = open("/dev/null", O_WRONLY | O_CREAT, 0666);
if (nullfd == -1) {
syslog (LOG_ERR,"failed to open \"/dev/null\"");
_exit (-1);
}
(void) dup2 (nullfd, 1);
(void) dup2 (nullfd, 2);
(void) close (nullfd);
}
execvp (cmd_.c_str (), argv);
EL((ASSAERR,"fork_exec (\"%s\") failed\n", cmd_.c_str ()));
_exit (-1);
}
if (! wait_for_completion_) {
return f.getChildPID ();
}
return f.get_exit_status ();
#endif // defined(WIN32)
}
DL
#define DL(X)
A macro for writing debug message to the Logger.
Definition Logger.h:273
ASSA::CmdLineOpts::str_to_argv
static void str_to_argv(const string &src_, int &argc_, char **&argv_)
Static function.
Definition CmdLineOpts.cpp:661
ASSA::Fork
Fork class is a simple wrapper around C library function fork().
Definition Fork.h:86

References ASSA::ASSAERR, DL, EL, ASSA::FORK, LEAVE_ALONE, ASSA::CmdLineOpts::str_to_argv(), and trace_with_mask.

## get_exit_status()

int ASSA::Fork::get_exit_status | ( |  | ) | const

inline

Retrieve exit status of a child process if the constructor's parameter catch_status_ was set to TRUE.

Definition at line 151 of file Fork.h.

{ return m_chstath.exit_status (); }
ASSA::ChildStatusHandler::exit_status
int exit_status() const
Definition Fork.h:69

References ASSA::ChildStatusHandler::exit_status(), and m_chstath.

## getChildPID()

pid_t ASSA::Fork::getChildPID | ( |  | ) | const

inline

Retrieve child process id.

Returns
  child pid

Definition at line 142 of file Fork.h.

{
trace_with_mask("Fork::getChildPID",FORK);
return m_pid;
}

References ASSA::FORK, m_pid, and trace_with_mask.

## isChild()

bool ASSA::Fork::isChild | ( |  | ) | const

inline

Test whether we are in child section of the code.

Returns
  true if it is parent code, false otherwise

Definition at line 136 of file Fork.h.

{ return !m_pid ? true : false; }

References m_pid.

## isParent()

bool ASSA::Fork::isParent | ( |  | ) | const

inline

Test whether we are in parent section of the code.

Returns
  true if it is parent code, false otherwise

Definition at line 130 of file Fork.h.

{ return m_pid ? true : false; }

References m_pid.

## Member Data Documentation

## m_chstath

ChildStatusHandler ASSA::Fork::m_chstath

private

Handler to catch Child's status.

Definition at line 184 of file Fork.h.

Referenced by Fork(), and get_exit_status().

## m_local_sh

SigHandler ASSA::Fork::m_local_sh

private

Local signal handler.

Definition at line 181 of file Fork.h.

Referenced by Fork().

## m_old_disp

SigAction ASSA::Fork::m_old_disp

private

Old signal disposition.

Definition at line 187 of file Fork.h.

Referenced by Fork().

## m_pid

pid_t ASSA::Fork::m_pid

private

Child pid.

Definition at line 178 of file Fork.h.

Referenced by Fork(), getChildPID(), isChild(), and isParent().

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

- Fork.h
- Fork.cpp