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

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             
    };

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          
    };

Constructor & Destructor Documentation

Fork::Fork	(	Fork::state_t	state_ = `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 160 of file Fork.cpp.

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.

{
    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 (state_ != LEAVE_ALONE) {
            ForkList::get_instance()->
                m_list.push_back (new fnode_t (m_pid, state_));
        }
        if (catch_status_ == COLLECT_STATUS) {
            if (! m_chstath.caught ()) {
                pause ();
            }
            m_local_sh.remove (SIGCHLD, &m_chstath, &m_old_disp, 0);
        }
    }
}

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.

References ASSA::FORK, and trace_with_mask.

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

Member Function Documentation

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 63 of file Fork.cpp.

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

{
    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)
}

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.

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

Referenced by fork_exec().

{ return m_chstath.exit_status (); }

pid_t ASSA::Fork::getChildPID ( ) const [inline]

Retrieve child process id.

Returns:: child pid

Definition at line 142 of file Fork.h.

References ASSA::FORK, m_pid, and trace_with_mask.

Referenced by fork_exec(), and ASSA::Pipe::open().

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

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.

References m_pid.

Referenced by ASSA::GenServer::become_daemon(), fork_exec(), and ASSA::Pipe::open().

{ return !m_pid ? true : false; }

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.

References m_pid.

{ return m_pid ? true : false; }

Member Data Documentation

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().

SigHandler ASSA::Fork::m_local_sh [private]

Local signal handler.

Definition at line 181 of file Fork.h.

Referenced by Fork().

SigAction ASSA::Fork::m_old_disp [private]

Old signal disposition.

Definition at line 187 of file Fork.h.

Referenced by Fork().

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:

/builddir/build/BUILD/libassa-3.5.0/assa/Fork.h
/builddir/build/BUILD/libassa-3.5.0/assa/Fork.cpp

ASSA::Fork Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation