stx::ExecPipeImpl Class Reference

Main library implementation (internal object). More...

List of all members.

Classes

struct  Stage
 Structure representing each stage in the pipe. More...

Public Member Functions

void set_debug_level (enum ExecPipe::DebugLevel dl)
 Change the current debug level. The default is DL_ERROR.
void set_debug_output (void(*output)(const char *line))
 Change output function for debug messages.
 ExecPipeImpl ()
 Create a new pipe implementation with zero reference counter.
unsigned int & refs ()
 Return writable reference to counter.
void input_source_write (const void *data, unsigned int datalen)
 Function called by PipeSource::write() to push data into the ring buffer.
void stage_function_write (unsigned int st, const void *data, unsigned int datalen)
 Function called by PipeSource::write() to push data into the ring buffer.
void run ()
 Run the configured pipe sequence and wait for all children processes to complete.
Input Selectors

void set_input_fd (int fd)
 Assign an already opened file descriptor as input stream for the first exec stage.
void set_input_file (const char *path)
 Assign a file as input stream source.
void set_input_string (const std::string *input)
 Assign a std::string as input stream source.
void set_input_source (PipeSource *source)
 Assign a PipeSource as input stream source.
Output Selectors

void set_output_fd (int fd)
 Assign an already opened file descriptor as output stream for the last exec stage.
void set_output_file (const char *path, int mode=0666)
 Assign a file as output stream destination.
void set_output_string (std::string *output)
 Assign a std::string as output stream destination.
void set_output_sink (PipeSink *sink)
 Assign a PipeSink as output stream destination.
Add Pipe Stages

unsigned int size () const
 Return the number of pipe stages added.
void add_exec (const char *prog)
 Add an exec() stage to the pipe with given arguments.
void add_exec (const char *prog, const char *arg1)
 Add an exec() stage to the pipe with given arguments.
void add_exec (const char *prog, const char *arg1, const char *arg2)
 Add an exec() stage to the pipe with given arguments.
void add_exec (const char *prog, const char *arg1, const char *arg2, const char *arg3)
 Add an exec() stage to the pipe with given arguments.
void add_exec (const std::vector< std::string > *args)
 Add an exec() stage to the pipe with given arguments.
void add_execp (const char *prog)
 Add an execp() stage to the pipe with given arguments.
void add_execp (const char *prog, const char *arg1)
 Add an execp() stage to the pipe with given arguments.
void add_execp (const char *prog, const char *arg1, const char *arg2)
 Add an execp() stage to the pipe with given arguments.
void add_execp (const char *prog, const char *arg1, const char *arg2, const char *arg3)
 Add an execp() stage to the pipe with given arguments.
void add_execp (const std::vector< std::string > *args)
 Add an execp() stage to the pipe with given arguments.
void add_exece (const char *path, const std::vector< std::string > *argsp, const std::vector< std::string > *envp)
 Add an exece() stage to the pipe with the given arguments and environments.
void add_function (PipeFunction *func)
 Add a function stage to the pipe.
Inspect Return Codes

int get_return_status (unsigned int stageid) const
 Get the return status of exec() stage's program run after pipe execution as indicated by wait().
int get_return_code (unsigned int stageid) const
 Get the return code of exec() stage's program run after pipe execution, or -1 if the program terminated abnormally.
int get_return_signal (unsigned int stageid) const
 Get the signal of the abnormally terminated exec() stage's program run after pipe execution, or -1 if the program terminated normally.
bool all_return_codes_zero () const
 Return true if the return code of all exec() stages were zero.

Protected Member Functions

void exec_stage (const Stage &stage)
 Transform arguments and launch an exec stage using the correct exec() variant.
void print_exec (const std::vector< std::string > &args)
 Print all arguments of exec() call.
void sclose (int fd)
 Safe close() call and output error if fd was already closed.

Private Types

enum  StreamType {
  ST_NONE = 0, ST_FD, ST_FILE, ST_STRING,
  ST_OBJECT
}
 

Enumeration describing the currently set input or output stream type.

More...
typedef std::vector< Stagestagelist_type
 typedef of list of pipe stages.

Private Attributes

unsigned int m_refs
 reference counter
enum ExecPipe::DebugLevel m_debug_level
 currently set debug level
void(* m_debug_output )(const char *line)
 current debug line output function
StreamType m_input
 describes the currently set input stream type
int m_input_fd
 for ST_FD the input fd given by the user.
const char * m_input_file
 for ST_FILE the path of the input file.
const std::string * m_input_string
 for ST_STRING a pointer to the user-supplied std::string input stream object.
std::string::size_type m_input_string_pos
 for ST_STRING the current position in the input stream object.
PipeSourcem_input_source
 for ST_OBJECT the input stream source object
RingBuffer m_input_rbuffer
 for ST_OBJECT the input stream ring buffer
StreamType m_output
 describes the currently set input stream type
int m_output_fd
 for ST_FD the output fd given by the user.
const char * m_output_file
 for ST_FILE the path of the output file.
int m_output_file_mode
 for ST_FILE the permission used in the open() call.
std::string * m_output_string
 for ST_STRING a pointer to the user-supplied std::string output stream object.
PipeSinkm_output_sink
 for ST_OBJECT the output stream source object
stagelist_type m_stages
 list of pipe stages.
char m_buffer [4096]
 general buffer used for read() and write() calls.

Detailed Description

Main library implementation (internal object).

Implementation class for stx::ExecPipe. See the documentation of the front-end class for detailed information.

Definition at line 258 of file stx-execpipe.cc.


Member Typedef Documentation

typedef std::vector<Stage> stx::ExecPipeImpl::stagelist_type [private]

typedef of list of pipe stages.

Definition at line 402 of file stx-execpipe.cc.


Member Enumeration Documentation

Enumeration describing the currently set input or output stream type.

Enumerator:
ST_NONE 

no special redirection requested

ST_FD 

redirection to existing fd

ST_FILE 

redirection to file path

ST_STRING 

input/output directed by/to string

ST_OBJECT 

input/output attached to program object

Definition at line 293 of file stx-execpipe.cc.


Constructor & Destructor Documentation

stx::ExecPipeImpl::ExecPipeImpl (  )  [inline]

Create a new pipe implementation with zero reference counter.

Definition at line 413 of file stx-execpipe.cc.


Member Function Documentation

void stx::ExecPipeImpl::add_exec ( const std::vector< std::string > *  args  )  [inline]

Add an exec() stage to the pipe with given arguments.

The vector of arguments is not copied, so it must still exist when run() is called. Note that the program called is args[0].

Definition at line 632 of file stx-execpipe.cc.

void stx::ExecPipeImpl::add_exec ( const char *  prog,
const char *  arg1,
const char *  arg2,
const char *  arg3 
) [inline]

Add an exec() stage to the pipe with given arguments.

Note that argv[0] is set to prog.

Definition at line 616 of file stx-execpipe.cc.

void stx::ExecPipeImpl::add_exec ( const char *  prog,
const char *  arg1,
const char *  arg2 
) [inline]

Add an exec() stage to the pipe with given arguments.

Note that argv[0] is set to prog.

Definition at line 602 of file stx-execpipe.cc.

void stx::ExecPipeImpl::add_exec ( const char *  prog,
const char *  arg1 
) [inline]

Add an exec() stage to the pipe with given arguments.

Note that argv[0] is set to prog.

Definition at line 589 of file stx-execpipe.cc.

void stx::ExecPipeImpl::add_exec ( const char *  prog  )  [inline]

Add an exec() stage to the pipe with given arguments.

Note that argv[0] is set to prog.

Definition at line 577 of file stx-execpipe.cc.

void stx::ExecPipeImpl::add_exece ( const char *  path,
const std::vector< std::string > *  argsp,
const std::vector< std::string > *  envp 
) [inline]

Add an exece() stage to the pipe with the given arguments and environments.

This is the most flexible exec() call. The vector of arguments and environment variables is not copied, so it must still exist when run() is called. The env vector pointer may be NULL, the args vector must not be NULL. The args[0] is _not_ override with path, so you can fake program name calls.

Definition at line 731 of file stx-execpipe.cc.

void stx::ExecPipeImpl::add_execp ( const std::vector< std::string > *  args  )  [inline]

Add an execp() stage to the pipe with given arguments.

The PATH variable is search for programs not containing a slash / character. The vector of arguments is not copied, so it must still exist when run() is called. Note that the program called is args[0].

Definition at line 711 of file stx-execpipe.cc.

void stx::ExecPipeImpl::add_execp ( const char *  prog,
const char *  arg1,
const char *  arg2,
const char *  arg3 
) [inline]

Add an execp() stage to the pipe with given arguments.

The PATH variable is search for programs not containing a slash / character. Note that argv[0] is set to prog.

Definition at line 693 of file stx-execpipe.cc.

void stx::ExecPipeImpl::add_execp ( const char *  prog,
const char *  arg1,
const char *  arg2 
) [inline]

Add an execp() stage to the pipe with given arguments.

The PATH variable is search for programs not containing a slash / character. Note that argv[0] is set to prog.

Definition at line 677 of file stx-execpipe.cc.

void stx::ExecPipeImpl::add_execp ( const char *  prog,
const char *  arg1 
) [inline]

Add an execp() stage to the pipe with given arguments.

The PATH variable is search for programs not containing a slash / character. Note that argv[0] is set to prog.

Definition at line 662 of file stx-execpipe.cc.

void stx::ExecPipeImpl::add_execp ( const char *  prog  )  [inline]

Add an execp() stage to the pipe with given arguments.

The PATH variable is search for programs not containing a slash / character. Note that argv[0] is set to prog.

Definition at line 648 of file stx-execpipe.cc.

void stx::ExecPipeImpl::add_function ( PipeFunction func  )  [inline]

Add a function stage to the pipe.

This function object will be called in the parent process with data passing through the stage. See PipeFunction for more information.

Definition at line 751 of file stx-execpipe.cc.

bool stx::ExecPipeImpl::all_return_codes_zero (  )  const [inline]

Return true if the return code of all exec() stages were zero.

Definition at line 837 of file stx-execpipe.cc.

void stx::ExecPipeImpl::exec_stage ( const Stage stage  )  [protected]

Transform arguments and launch an exec stage using the correct exec() variant.

Definition at line 880 of file stx-execpipe.cc.

int stx::ExecPipeImpl::get_return_code ( unsigned int  stageid  )  const [inline]

Get the return code of exec() stage's program run after pipe execution, or -1 if the program terminated abnormally.

Definition at line 808 of file stx-execpipe.cc.

int stx::ExecPipeImpl::get_return_signal ( unsigned int  stageid  )  const [inline]

Get the signal of the abnormally terminated exec() stage's program run after pipe execution, or -1 if the program terminated normally.

Definition at line 823 of file stx-execpipe.cc.

int stx::ExecPipeImpl::get_return_status ( unsigned int  stageid  )  const [inline]

Get the return status of exec() stage's program run after pipe execution as indicated by wait().

Definition at line 796 of file stx-execpipe.cc.

void stx::ExecPipeImpl::input_source_write ( const void *  data,
unsigned int  datalen 
) [inline]

Function called by PipeSource::write() to push data into the ring buffer.

Definition at line 496 of file stx-execpipe.cc.

void stx::ExecPipeImpl::print_exec ( const std::vector< std::string > &  args  )  [protected]

Print all arguments of exec() call.

Definition at line 869 of file stx-execpipe.cc.

unsigned int& stx::ExecPipeImpl::refs (  )  [inline]

Return writable reference to counter.

Definition at line 425 of file stx-execpipe.cc.

void stx::ExecPipeImpl::run (  ) 

Run the configured pipe sequence and wait for all children processes to complete.

Returns a reference to *this for chaining.

This function call should be wrapped into a try-catch block as it will throw() if a system call fails.

Definition at line 931 of file stx-execpipe.cc.

void stx::ExecPipeImpl::sclose ( int  fd  )  [protected]

Safe close() call and output error if fd was already closed.

Definition at line 920 of file stx-execpipe.cc.

void stx::ExecPipeImpl::set_debug_level ( enum ExecPipe::DebugLevel  dl  )  [inline]

Change the current debug level. The default is DL_ERROR.

Definition at line 278 of file stx-execpipe.cc.

void stx::ExecPipeImpl::set_debug_output ( void(*)(const char *line)  output  )  [inline]

Change output function for debug messages.

If set to NULL (the default) the debug lines are printed to stdout.

Definition at line 285 of file stx-execpipe.cc.

void stx::ExecPipeImpl::set_input_fd ( int  fd  )  [inline]

Assign an already opened file descriptor as input stream for the first exec stage.

Definition at line 438 of file stx-execpipe.cc.

void stx::ExecPipeImpl::set_input_file ( const char *  path  )  [inline]

Assign a file as input stream source.

This file will be opened read-only and read by the first exec stage.

Definition at line 451 of file stx-execpipe.cc.

void stx::ExecPipeImpl::set_input_source ( PipeSource source  )  [inline]

Assign a PipeSource as input stream source.

The object will be queried via the read() function for data which is then written to the first exec stage.

Definition at line 480 of file stx-execpipe.cc.

void stx::ExecPipeImpl::set_input_string ( const std::string *  input  )  [inline]

Assign a std::string as input stream source.

The contents of the string will be written to the first exec stage. The string object is not copied and must still exist when run() is called.

Definition at line 465 of file stx-execpipe.cc.

void stx::ExecPipeImpl::set_output_fd ( int  fd  )  [inline]

Assign an already opened file descriptor as output stream for the last exec stage.

Definition at line 509 of file stx-execpipe.cc.

void stx::ExecPipeImpl::set_output_file ( const char *  path,
int  mode = 0666 
) [inline]

Assign a file as output stream destination.

This file will be created or truncated write-only and written by the last exec stage.

Definition at line 522 of file stx-execpipe.cc.

void stx::ExecPipeImpl::set_output_sink ( PipeSink sink  )  [inline]

Assign a PipeSink as output stream destination.

The object will receive data via the process() function and is informed via eof()

Definition at line 550 of file stx-execpipe.cc.

void stx::ExecPipeImpl::set_output_string ( std::string *  output  )  [inline]

Assign a std::string as output stream destination.

The output of the last exec stage will be stored as the contents of the string. The string object is not copied and must still exist when run() is called.

Definition at line 537 of file stx-execpipe.cc.

unsigned int stx::ExecPipeImpl::size (  )  const [inline]

Return the number of pipe stages added.

Definition at line 568 of file stx-execpipe.cc.

void stx::ExecPipeImpl::stage_function_write ( unsigned int  st,
const void *  data,
unsigned int  datalen 
) [inline]

Function called by PipeSource::write() to push data into the ring buffer.

Definition at line 770 of file stx-execpipe.cc.


Member Data Documentation

char stx::ExecPipeImpl::m_buffer[4096] [private]

general buffer used for read() and write() calls.

Definition at line 408 of file stx-execpipe.cc.

currently set debug level

Definition at line 270 of file stx-execpipe.cc.

void(* stx::ExecPipeImpl::m_debug_output)(const char *line) [private]

current debug line output function

Definition at line 273 of file stx-execpipe.cc.

describes the currently set input stream type

Definition at line 303 of file stx-execpipe.cc.

for ST_FD the input fd given by the user.

for ST_STRING and ST_FUNCTION the pipe write fd of the parent process.

Definition at line 309 of file stx-execpipe.cc.

const char* stx::ExecPipeImpl::m_input_file [private]

for ST_FILE the path of the input file.

Definition at line 312 of file stx-execpipe.cc.

RingBuffer stx::ExecPipeImpl::m_input_rbuffer [private]

for ST_OBJECT the input stream ring buffer

Definition at line 325 of file stx-execpipe.cc.

for ST_OBJECT the input stream source object

Definition at line 322 of file stx-execpipe.cc.

const std::string* stx::ExecPipeImpl::m_input_string [private]

for ST_STRING a pointer to the user-supplied std::string input stream object.

Definition at line 316 of file stx-execpipe.cc.

std::string::size_type stx::ExecPipeImpl::m_input_string_pos [private]

for ST_STRING the current position in the input stream object.

Definition at line 319 of file stx-execpipe.cc.

describes the currently set input stream type

Definition at line 330 of file stx-execpipe.cc.

for ST_FD the output fd given by the user.

for ST_STRING and ST_FUNCTION the pipe read fd of the parent process.

Definition at line 334 of file stx-execpipe.cc.

const char* stx::ExecPipeImpl::m_output_file [private]

for ST_FILE the path of the output file.

Definition at line 337 of file stx-execpipe.cc.

for ST_FILE the permission used in the open() call.

Definition at line 340 of file stx-execpipe.cc.

for ST_OBJECT the output stream source object

Definition at line 347 of file stx-execpipe.cc.

std::string* stx::ExecPipeImpl::m_output_string [private]

for ST_STRING a pointer to the user-supplied std::string output stream object.

Definition at line 344 of file stx-execpipe.cc.

unsigned int stx::ExecPipeImpl::m_refs [private]

reference counter

Definition at line 263 of file stx-execpipe.cc.

list of pipe stages.

Definition at line 405 of file stx-execpipe.cc.


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends
Generated on Fri Jul 30 17:07:13 2010 for STX Execution Pipe by  doxygen 1.6.3