Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages | Search for 

Wefts::OSProcessBase Class Reference
[OS Cooperative File Function Extended Enviroment]

#include <wefts_coffee_base.h>

Inheritance diagram for Wefts::OSProcessBase:

Inheritance graph
[legend]
Collaboration diagram for Wefts::OSProcessBase:

Collaboration graph
[legend]
List of all members.

Detailed Description

Representation of subprocesses on the platform.

This class encapsulates threadsafe subprocess handling on the current platform. It provides support to spawn a child of the process, access its stdin, stdout and stderr file handle, test it's status and eventually wait for its termination.

The encapsulation is made so that the child process can be referenced to the thread that spawned it; if the father thread is cancelled, so the child process is cancelled too.

For this reason, the subprocess should be handled only by the calling thread, but it's possible for threads to exchange ownership among them with the takeOwnership() method. This removes the cancellation cleanup routine from the previous thread and adds it to the one that called takeOwnership.

Note:
This class is designed to work in tight cooperation with the Thread class; using it outside a Thread::run() started with Thread::start(), or any method called from that, has undefined results. Of course, also derived class and non-method functions called by Thread::run() can use OSProcessBase class.


Public Member Functions

virtual bool running ()=0
 Return true if the child process is currently running.

virtual bool wait (const double seconds=-1.0)=0
 Wait for the process to finish.

virtual bool start (const std::string process, bool useShell=false, bool usePath=true)=0
 Starts the subprocess.

virtual bool stop ()=0
 Stop the subprocess.

virtual bool getProcessValue (int &retvalue) const =0
 Get the return value of the process.

int osError () const
 Return system dependend error occured on last operation.

virtual file_size_t getProcessId () const =0
 Return OS dependent process id.

virtual int write (const void *data, const int size, const double seconds=-1.0)=0
 Write to child standard input.

virtual int read (void *data, const int size, const double seconds=-1.0)=0
 Read from child standard output.

virtual int readStdErr (void *data, const int size, const double seconds=-1.0)=0
 Read from child standard error.

virtual void mergeStdErr ()=0
 Merge data incoming from Standard Output and Standard error child process streams.

virtual void detach ()=0
 Detaches the process.

virtual void sinkInput ()=0
 Tells that this process object won't read standard input.

virtual void sinkOutput ()=0
 Tells that this process object won't read standard input.

virtual void sinkError ()=0
 Tells that this process object won't read standard input.

virtual bool closeRead ()=0
virtual bool closeWrite ()=0
virtual bool closeStdErr ()=0
virtual void handleCleanup (int code, void *caller=0)=0

Protected Member Functions

 OSProcessBase ()
 Initializes the process object.


Protected Attributes

int m_osError
 Search for the child process to be spawned in the path.

bool m_started
bool m_ended
bool m_mergeStdErr
int m_retval
bool m_detached

Private Member Functions

void internal_init ()

Constructor & Destructor Documentation

Wefts::OSProcessBase::OSProcessBase (   )  [inline, protected]
 

Initializes the process object.

Member Function Documentation

virtual bool Wefts::OSProcessBase::closeRead (   )  [pure virtual]
 

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

virtual bool Wefts::OSProcessBase::closeStdErr (   )  [pure virtual]
 

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

virtual bool Wefts::OSProcessBase::closeWrite (   )  [pure virtual]
 

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

virtual void Wefts::OSProcessBase::detach (   )  [pure virtual]
 

Detaches the process.

Instead of listening for the sub process to terminate, the thread may detach it. If it does so, the child process is not tied anymore to the calling thread; on child termination, its system resources are cleaned (a low-level thread is started and puts itself in wait for the child). If the calling process terminates, the child process continues it execution, but if the parent is killed, the child may or may not remain active, depending on the OS implementation.

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

virtual file_size_t Wefts::OSProcessBase::getProcessId (   )  const [pure virtual]
 

Return OS dependent process id.

This function can be called to retreive the system id and do system specific operations on that; i.e. UNIX systems supports signals, while Windows systems supports process accounting informations (different ones based on Windows version). If some of this advanced features are needed by the application, it can use this method to retreive the low level process ID and work directly on that.

Of course, doing this unsafely (i.e. calling directly waitpid) will strip the application from the ability to use Wefts Independence layers (that means, do this at your own risk).

This function will return an impossible id if the process is not opened or is already closed (-1).

Note:
As this function is meant to be system-dependant you can safely cast the returned value to some systemwise ID type, i.e. ULONG or pid_t.
Returns:
system process ID or -1.

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

virtual bool Wefts::OSProcessBase::getProcessValue (  int &  retvalue  )  const [pure virtual]
 

Get the return value of the process.

Parameters:
retvalue an integer where to store the return value of the process.
Returns:
true if a process value is available ( process terminated ), false otherwise.ù

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

virtual void Wefts::OSProcessBase::handleCleanup (  int  code,
void *  caller = 0
)  [pure virtual]
 

Implements Wefts::CleanupHandler.

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

void Wefts::OSProcessBase::internal_init (   )  [inline, private]
 

virtual void Wefts::OSProcessBase::mergeStdErr (   )  [pure virtual]
 

Merge data incoming from Standard Output and Standard error child process streams.

Sometimes it is desiderable to have both the error stream and the standard output stream readable in only one call. After calling this method, read() will return both data coming from stdout and stderr of the child process, while readStdErr() will always return -1 (without setting osError).

The method can be called both before and after the child process is started.

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

int Wefts::OSProcessBase::osError (   )  const [inline]
 

Return system dependend error occured on last operation.

virtual int Wefts::OSProcessBase::read (  void *  data,
const int  size,
const double  seconds = -1.0
)  [pure virtual]
 

Read from child standard output.

This is a cancellation point; if the thread is cancelled in this call, the child is killed too.

Note:
the output stream and the error stream may be merged with mergeStdErr() method. This may be useful for those applications that are not willing to wait differently from the two streams.
A timeout in seconds may also be given. On error, osError() will return the OS dependent error value.
Parameters:
data the data do send
size the amount of data to send
seconds timeout before function return; 0 doesn't wait, < 0 returns immediately.
Returns:
amount if bytes written, -1 on error.

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

virtual int Wefts::OSProcessBase::readStdErr (  void *  data,
const int  size,
const double  seconds = -1.0
)  [pure virtual]
 

Read from child standard error.

This is a cancellation point; if the thread is cancelled in this call, the child is killed too.

Remember that if the child writes on standard error, the father MUST periodically read it, or the child writes will block it waiting for father to read.

Note:
the output stream and the error stream may be merged with mergeStdErr() method. This may be useful for those applications that are not willing to wait differently from the two streams.
A timeout in seconds may also be given. On error, osError() will return the OS dependent error value.
Parameters:
data the data do send
size the amount of data to send
seconds timeout before function return; 0 doesn't wait, < 0 returns immediately.
Returns:
amount if bytes written, -1 on error.

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

virtual bool Wefts::OSProcessBase::running (   )  [pure virtual]
 

Return true if the child process is currently running.

False is returned both if the process is not yet started or is already terminated.

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

virtual void Wefts::OSProcessBase::sinkError (   )  [pure virtual]
 

Tells that this process object won't read standard input.

For this reason, child standard error must be ignored.

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

virtual void Wefts::OSProcessBase::sinkInput (   )  [pure virtual]
 

Tells that this process object won't read standard input.

For this reason, child standard input must be ignored.

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

virtual void Wefts::OSProcessBase::sinkOutput (   )  [pure virtual]
 

Tells that this process object won't read standard input.

For this reason, child standard output must be ignored.

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

virtual bool Wefts::OSProcessBase::start (  const std::string  process,
bool  useShell = false,
bool  usePath = true
)  [pure virtual]
 

Starts the subprocess.

If an error occurs, the method returns false and osError() method can be used to determine what happend.

The calling thread may also chose to

Parameters:
process The process name, including command line parameters.
useShell set to true to start the process using the shell interface.
usePath if true (default) searches the process in the PATH environment.
Returns:
true if the process is started, false on error

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

virtual bool Wefts::OSProcessBase::stop (   )  [pure virtual]
 

Stop the subprocess.

If running, the subprocess is terminated; if not running this function returns false. This function is not a cancellation point.

Returns:
true if the process is stopped, false on error (most likely the process cannot be started).

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

virtual bool Wefts::OSProcessBase::wait (  const double  seconds = -1.0  )  [pure virtual]
 

Wait for the process to finish.

This is a cancellation point; if the thread is cancelled while waiting in this function, the subprocess is destroyed. Disable cancellation before entering if you don't want this behavior. In example, a thread run() code slice where the cancellation of subprocess on thread cancllation is not wanted may look like this: 

         while( proc.running() )
         {
            Sleep( 1.0 );
            disableCancel();
            proc.wait(0);
            enableCancel();
         }
In this way, the thread may still be cancelled but the child process will survive.

When the function returns true, the application can check for getProcessValue;

Parameters:
seconds maximum wait time; if 0 doesn't wait, if < 0 it waits forever.
Returns:
false on error or if timedout, true on success.

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

virtual int Wefts::OSProcessBase::write (  const void *  data,
const int  size,
const double  seconds = -1.0
)  [pure virtual]
 

Write to child standard input.

This is a cancellation point; if the thread is cancelled in this call, the child is killed too. A timeout in seconds may also be given. On error, osError() will return the OS dependent error value.

Returns:
amount if bytes written, -1 on error.
Parameters:
data the data do send
size the amount of data to send
seconds timeout before function return; 0 doesn't wait, < 0 returns immediately.

Implemented in Wefts::OSProcessPthread, and Wefts::OSProcessWin.

Member Data Documentation

bool Wefts::OSProcessBase::m_detached [protected]
 

bool Wefts::OSProcessBase::m_ended [protected]
 

bool Wefts::OSProcessBase::m_mergeStdErr [protected]
 

int Wefts::OSProcessBase::m_osError [protected]
 

Search for the child process to be spawned in the path.

int Wefts::OSProcessBase::m_retval [protected]
 

bool Wefts::OSProcessBase::m_started [protected]
 

The documentation for this class was generated from the following file:
Generated on Tue Oct 5 14:57:02 2004 for Wefts by doxygen 1.3.7