Arc::Run Class Reference

This class runs an external executable. More...

#include <arc/Run.h>

Public Member Functions
	Run (const std::string &cmdline)
	Constructor prepares object to run cmdline. More...
	Run (const std::list< std::string > &argv)
	Constructor prepares object to run executable and arguments specified in argv. More...
	~Run (void)
	Destructor kills running executable and releases associated resources. More...
	operator bool (void)
	Returns true if object is valid. More...
bool	operator! (void)
	Returns true if object is invalid. More...
bool	Start (void)
	Starts running executable. This method may be called only once. More...
bool	Wait (int timeout)
	Wait till execution finished or till timeout seconds expires. More...
bool	Wait (void)
	Wait till execution finished. More...
int	Result (void)
	Returns exit code of execution. More...
bool	Running (void)
	Return true if execution is going on. More...
Time	RunTime (void)
	Return when executable was started. More...
Time	ExitTime (void)
	Return when executable finished executing. More...
int	ReadStdout (int timeout, char *buf, int size)
	Read from stdout handle of running executable. More...
int	ReadStderr (int timeout, char *buf, int size)
	Read from stderr handle of running executable. More...
int	WriteStdin (int timeout, const char *buf, int size)
	Write to stdin handle of running executable. More...
void	AssignStdout (std::string &str)
	Associate stdout handle of executable with string. More...
void	AssignStderr (std::string &str)
	Associate stderr handle of executable with string. More...
void	AssignStdin (std::string &str)
	Associate stdin handle of executable with string. More...
void	KeepStdout (bool keep=true)
	Keep stdout same as parent's if keep = true. More...
void	KeepStderr (bool keep=true)
	Keep stderr same as parent's if keep = true. More...
void	KeepStdin (bool keep=true)
	Keep stdin same as parent's if keep = true. More...
void	CloseStdout (void)
	Closes pipe associated with stdout handle. More...
void	CloseStderr (void)
	Closes pipe associated with stderr handle. More...
void	CloseStdin (void)
	Closes pipe associated with stdin handle. More...
void	AssignInitializer (void(*initializer_func)(void *), void *initializer_arg)
	Assign a function to be called just after process is forked but before execution starts. More...
void	AssignKicker (void(*kicker_func)(void *), void *kicker_arg)
	Assign a function to be called just after execution ends. More...
void	AssignWorkingDirectory (std::string &wd)
	Assign working directory of the running process. More...
void	AssignUserId (int uid)
	Assign uid for the process to run under. More...
void	AssignGroupId (int gid)
	Assign gid for the process to run under. More...
void	Kill (int timeout)
	Kill running executable. More...
void	Abandon (void)
	Detach this object from running process. More...

Static Public Member Functions
static void	AfterFork (void)
	Call this method after fork() in child process. More...

Protected Member Functions
bool	stdout_handler (Glib::IOCondition cond)
bool	stderr_handler (Glib::IOCondition cond)
bool	stdin_handler (Glib::IOCondition cond)
void	child_handler (Glib::Pid pid, int result)

Protected Attributes
std::string	working_directory
int	stdout_
int	stderr_
int	stdin_
std::string *	stdout_str_
std::string *	stderr_str_
std::string *	stdin_str_
bool	stdout_keep_
bool	stderr_keep_
bool	stdin_keep_
sigc::connection	stdout_conn_
sigc::connection	stderr_conn_
sigc::connection	stdin_conn_
sigc::connection	child_conn_
Pid *	pid_
Glib::ArrayHandle< std::string >	argv_
void(*	initializer_func_ )(void *)
void *	initializer_arg_
void(*	kicker_func_ )(void *)
void *	kicker_arg_
bool	started_
bool	running_
bool	abandoned_
int	result_
Glib::Mutex	lock_
Glib::Cond	cond_
int	user_id_
int	group_id_
Time	run_time_
Time	exit_time_

Friends
class	RunPump

Detailed Description

This class runs an external executable.

It is possible to read from or write to its standard handles or to redirect them to std::string elements.

Constructor & Destructor Documentation

Arc::Run::Run

(

const std::string &

cmdline

)

Constructor prepares object to run cmdline.

Arc::Run::Run

(

const std::list< std::string > &

argv

)

Constructor prepares object to run executable and arguments specified in argv.

Arc::Run::~Run

(

void

)

Destructor kills running executable and releases associated resources.

Member Function Documentation

void Arc::Run::Abandon

(

void

)

Detach this object from running process.

After calling this method instance is not associated with external process anymore. As result destructor will not kill process.

static void Arc::Run::AfterFork ( void  )

static

Call this method after fork() in child process.

It will reinitialize internal structures for new environment. Do not call it in any other case than defined.

void Arc::Run::AssignGroupId ( int  gid )

inline

Assign gid for the process to run under.

void Arc::Run::AssignInitializer	(	void(*)(void *)	initializer_func,
		void *	initializer_arg
	)

Assign a function to be called just after process is forked but before execution starts.

void Arc::Run::AssignKicker	(	void(*)(void *)	kicker_func,
		void *	kicker_arg
	)

Assign a function to be called just after execution ends.

void Arc::Run::AssignStderr

(

std::string &

str

)

Associate stderr handle of executable with string.

This method must be called before Start(). str object must be valid as long as this object exists.

void Arc::Run::AssignStdin

(

std::string &

str

)

Associate stdin handle of executable with string.

This method must be called before Start(). str object must be valid as long as this object exists.

void Arc::Run::AssignStdout

(

std::string &

str

)

Associate stdout handle of executable with string.

This method must be called before Start(). str object must be valid as long as this object exists.

void Arc::Run::AssignUserId ( int  uid )

inline

Assign uid for the process to run under.

void Arc::Run::AssignWorkingDirectory ( std::string &  wd )

inline

Assign working directory of the running process.

void Arc::Run::CloseStderr

(

void

)

Closes pipe associated with stderr handle.

void Arc::Run::CloseStdin

(

void

)

Closes pipe associated with stdin handle.

void Arc::Run::CloseStdout

(

void

)

Closes pipe associated with stdout handle.

Time Arc::Run::ExitTime ( void  )

inline

Return when executable finished executing.

void Arc::Run::KeepStderr

(

bool

keep = true

)

Keep stderr same as parent's if keep = true.

void Arc::Run::KeepStdin

(

bool

keep = true

)

Keep stdin same as parent's if keep = true.

void Arc::Run::KeepStdout

(

bool

keep = true

)

Keep stdout same as parent's if keep = true.

void Arc::Run::Kill

(

int

timeout

)

Kill running executable.

First soft kill signal (SIGTERM) is sent to executable. If after timeout seconds executable is still running it's killed completely. Currently this method does not work for Windows OS

Arc::Run::operator bool ( void  )

inline

Returns true if object is valid.

bool Arc::Run::operator! ( void  )

inline

Returns true if object is invalid.

int Arc::Run::ReadStderr	(	int	timeout,
		char *	buf,
		int	size
	)

Read from stderr handle of running executable.

This method may be used while stderr is directed to string, but the result is unpredictable.

Parameters

timeout	upper limit for which method will block in milliseconds. Negative means infinite.
buf	buffer to write the stderr to
size	size of buf

Returns

number of read bytes.

int Arc::Run::ReadStdout	(	int	timeout,
		char *	buf,
		int	size
	)

Read from stdout handle of running executable.

This method may be used while stdout is directed to string, but the result is unpredictable.

Parameters

timeout	upper limit for which method will block in milliseconds. Negative means infinite.
buf	buffer to write the stdout to
size	size of buf

Returns

number of read bytes.

int Arc::Run::Result ( void  )

inline

Returns exit code of execution.

If child process was killed then exit code is -1. If code is compiled with support for detecting lost child process this code is -1 also if track of child was lost.

bool Arc::Run::Running

(

void

)

Return true if execution is going on.

Time Arc::Run::RunTime ( void  )

inline

Return when executable was started.

bool Arc::Run::Start

(

void

)

Starts running executable. This method may be called only once.

Returns

true if executable started without problems

bool Arc::Run::Wait

(

int

timeout

)

Wait till execution finished or till timeout seconds expires.

Returns

true if execution is complete.

bool Arc::Run::Wait

(

void

)

Wait till execution finished.

Returns

true if execution is complete, false if execution was not started.

int Arc::Run::WriteStdin	(	int	timeout,
		const char *	buf,
		int	size
	)

Write to stdin handle of running executable.

This method may be used while stdin is directed to string, but the result is unpredictable.

Parameters

timeout	upper limit for which method will block in milliseconds. Negative means infinite.
buf	buffer to read the stdin from
size	size of buf

Returns

number of written bytes.

---

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

• Run.h