ncbi_pipe.hpp

ncbi源码

/*
 * ===========================================================================
 * PRODUCTION $Log: ncbi_pipe.hpp,v $
 * PRODUCTION Revision 1000.2  2004/02/12 21:51:42  gouriano
 * PRODUCTION PRODUCTION: UPGRADED [CORE_001] Dev-tree R1.20
 * PRODUCTION
 * ===========================================================================
 */

#ifndef CONNECT___NCBI_PIPE__HPP
#define CONNECT___NCBI_PIPE__HPP

/*  $Id: ncbi_pipe.hpp,v 1000.2 2004/02/12 21:51:42 gouriano Exp $
 * ===========================================================================
 *
 *                            PUBLIC DOMAIN NOTICE
 *               National Center for Biotechnology Information
 *
 *  This software/database is a "United States Government Work" under the
 *  terms of the United States Copyright Act.  It was written as part of
 *  the author's official duties as a United States Government employee and
 *  thus cannot be copyrighted.  This software/database is freely available
 *  to the public for use. The National Library of Medicine and the U.S.
 *  Government have not placed any restriction on its use or reproduction.
 *
 *  Although all reasonable efforts have been taken to ensure the accuracy
 *  and reliability of the software and data, the NLM and the U.S.
 *  Government do not and cannot warrant the performance or results that
 *  may be obtained by using this software or data. The NLM and the U.S.
 *  Government disclaim all warranties, express or implied, including
 *  warranties of performance, merchantability or fitness for any particular
 *  purpose.
 *
 *  Please cite the author in any work or product based on this material.
 *
 * ===========================================================================
 *
 * Author:  Anton Lavrentiev, Vladimir Ivanov
 *
 *
 */

/// @file ncbi_pipe.hpp
/// Portable class for work with process pipes.
///
/// Defines classes: 
///     CPipe -  class for work with pipes
///
/// Implemented for: UNIX, MS-Windows


#include <corelib/ncbistd.hpp>
#include <corelib/ncbi_process.hpp>
#include <connect/ncbi_core.h>
#include <vector>

#if !defined(NCBI_OS_MSWIN)  &&  !defined(NCBI_OS_UNIX)
#  error "Class CPipe is only supported on Windows and Unix"
#endif


/** @addtogroup Pipes
 *
 * @{
 */


BEGIN_NCBI_SCOPE


// Forward declaration.
class CPipeHandle;


/////////////////////////////////////////////////////////////////////////////
/// CPipeException --
///
/// Define exceptions generated by CPipe.
///
/// CPipeException inherits its basic functionality from CCoreException
/// and defines additional error codes for CPipe.

class NCBI_XCONNECT_EXPORT CPipeException : public CCoreException
{
public:
    /// Error types for pipe exceptions.
    enum EErrCode {
        eInit,      ///< Pipe initialization error
        eOpen,      ///< Unable to open pipe (from constructor)
        eSetBuf     ///< setbuf() not permitted
    };

    /// Translate from an error code value to its string representation.
    virtual const char* GetErrCodeString(void) const
    {
        switch (GetErrCode()) {
        case eInit:   return "eInit";
        case eOpen:   return "eOpen";
        case eSetBuf: return "eSetBuf";
        default:      return CException::GetErrCodeString();
        }
    }
    // Standard exception boiler plate code.
    NCBI_EXCEPTION_DEFAULT(CPipeException,CCoreException);
};



/////////////////////////////////////////////////////////////////////////////
///
/// CPipe --
///
/// Launch child process with pipes connected to its standard I/O.
///
/// Program can read from stdin/stderr and write to stdin of the
/// executed child process using pipe object functions Read/Write.
/// Program can read from stdin/stderr and write to stdin of the
/// executed child process using pipe object functions Read/Write.
///
/// @sa
///   CNamedPipe, CExec

class NCBI_XCONNECT_EXPORT CPipe
{
public:
    /// Flags for creating standard I/O handles of child process.
    ///
    /// Default is 0 
    ///    fStdIn_Open | fStdOut_Open | fStdErr_Close | fCloseOnClose.
    enum ECreateFlags {
        fStdIn_Open    =    0,  ///< Do     open child stdin (default).
        fStdIn_Close   = 0x01,  ///< Do not open child's stdin.
        fStdOut_Open   =    0,  ///< Do     open child stdout (default).
        fStdOut_Close  = 0x02,  ///< Do not open child's stdout.
        fStdErr_Open   = 0x04,  ///< Do     open child stderr.
        fStdErr_Close  =    0,  ///< Do not open child stderr (default).
        fKeepOnClose   = 0x08,  ///< Close(): just return eIO_Timeout on
                                ///< eIO_Close timeout w/o closing pipe
                                ///< handles and/or killing child process.
        fCloseOnClose  =    0,  ///< Close(): always close all pipe handles
                                ///< but do not send any signal to running
                                ///< process if eIO_Close timeout expired.
        fKillOnClose   = 0x10   ///< Close(): kill child process if it didn't
                                ///< terminate after eIO_Close timeout.
    };
    typedef unsigned int TCreateFlags;  ///< bit-wise OR of "ECreateFlags"

    /// Which of the child I/O handles to use.
    enum EChildIOHandle {
        eStdIn,
        eStdOut,
        eStdErr,
        eDefault
    };

    /// Constructor.
    CPipe();

    /// Constructor.
    ///
    /// Call the Open() method to open a pipe.
    /// Throw CPipeException on failure to create the pipe.
    ///
    /// @param cmd
    ///   Command name to execute.
    /// @param args
    ///   Vector of string arguments for the command.
    /// @param create_flags
    ///   Specifies the options to be applied when creating the pipe.
    /// @sa
    ///   Open()
    CPipe
        (const string&         cmd,
         const vector<string>& args,
         TCreateFlags          create_flags = 0
        );

    /// Destructor. 
    ///
    /// If the pipe was opened then close it by calling Close().
    ~CPipe(void);

    /// Open pipe.
    ///
    /// Create a pipe and execute a command with the vector of arguments
    /// "args". The other end of the pipe is associated with the spawned
    /// command's standard input/output/error according to "create_flags".
    ///
    /// @param cmd
    ///   Command name to execute.
    /// @param args
    ///   Vector of string arguments for command.
    /// @param create_flags
    ///   Specifies options to be applied when creating the pipe.
    /// @return 
    ///   Completion status.
    /// @sa
    ///   Read(), Write(), Close()
    EIO_Status Open
        (const string&         cmd,
         const vector<string>& args,
         TCreateFlags          create_flags = 0
        );

    /// Close pipe.
    ///
    /// Wait for the spawned child process to terminate and then close
    /// the associated pipe.
    ///
    /// @param exitcode
    ///   Pointer to store the exit code at, if the child process terminated
    ///   successfully, or -1 in case of an error. Can be passed as NULL.
    /// @return
    ///   Completion status.
    ///   The returned status eIO_Timeout means that child process is still 
    ///   running and the pipe was not yet closed. Any other return status
    ///   means that the pipe is not suitable for further I/O until reopened.
    ///
    ///   eIO_Closed  - pipe was already closed;
    ///   eIO_Timeout - the eIO_Close timeout expired, child process
    ///                 is still running and the pipe was not yet closed
    ///                 (return only if fKeepOnClose create flag was set);
    ///   eIO_Success - pipe was succesfully closed. The child process
    ///                 running status depend on the flags:
    ///       fKeepOnClose  - process is terminated with "exitcode";
    ///       fCloseOnClose - process is self-terminated if "exitcode" != -1,
    ///                       or is still running otherwise;
    ///       fKillOnClose  - process is self-terminated if "exitcode" != -1,
    ///                       or was forcibly terminated otherwise;
    ///   Otherwise   - an error was detected;
    /// @sa
    ///   Description for flags fKeepOnClose, fCloseOnClose, fKillOnClose.
    ///   Open()
    EIO_Status Close(int* exitcode = 0);

    /// Close specified pipe handle.
    ///
    /// @param handle
    ///   Pipe handle to close
    /// @return
    ///   Completion status.
    /// @sa
    ///   Close()
    EIO_Status CloseHandle(EChildIOHandle handle);

    /// Read data from pipe. 
    ///
    /// @param buf
    ///   Buffer into which data is read.
    /// @param count
    ///   Number of bytes to read.
    /// @param read
    ///   Number of bytes actually read, which may be less than "count". 
    /// @param from_handle
    ///   Handle to read data from.
    /// @return
    ///   Always return eIO_Success if some data were read (regardless of pipe
    ///   conditions that may include EOF/error).
    ///   Return other (error) status only if no data at all could be obtained.
    /// @sa
    ///   Write(), SetTimeout()
    EIO_Status Read
        (void*          buf, 
         size_t         count, 
         size_t*        read = 0,
         EChildIOHandle from_handle = eDefault
        );

    /// Set standard output handle to read data from.
    ///
    /// @from_handle
    ///   Handle which used to read data (eStdOut/eStdErr).
    /// @return
    ///   Return eIO_Success if new handler is eStdOut or eStdErr.
    ///   Return eIO_Unknown otherwise.
    /// @sa
    ///   Read()
    EIO_Status SetReadHandle(EChildIOHandle from_handle);

    /// Write data to pipe. 
    ///
    /// @param buf
    ///   Buffer from which data is written.
    /// @param count
    ///   Number of bytes to write.
    /// @param written
    ///   Number of bytes actually written, which may be less than "count".
    /// @return
    ///   Return eIO_Success if some data were written.
    ///   Return other (error) code only if no data at all could be written.
    /// @sa
    ///   Read(), SetTimeout()
    EIO_Status Write
        (const void* buf,
         size_t      count,
         size_t*     written = 0
        );

    /// Return a status of the last I/O operation.
    /// 
    /// @param direction
    ///   Direction to get status for.
    /// @return
    ///   I/O status for the specified direction.
    ///   eIO_Closed     - if the pipe is closed;
    ///   eIO_Unknown    - if an error was detected during the last I/O;
    ///   eIO_InvalidArg - if "direction" is not one of:  eIO_Read, eIO_Write;
    ///   eIO_Timeout    - if the timeout was on last I/O;
    ///   eIO_Success    - otherwise.
    /// @sa
    ///   Read(), Write()
    EIO_Status Status(EIO_Event direction) const;

    /// Specify timeout for the pipe I/O.
    ///
    /// @param event
    ///   I/O event for which the timeout is set.
    /// @param timeout
    ///   Timeout value to set.
    ///   If "timeout" is NULL then set the timeout to be infinite.
    ///   - By default, initially all timeouts are infinite;
    ///   - kDefaultTimeout has no effect.
    /// @return
    ///   Completion status.
    /// @sa
    ///   Read(), Write(), Close(), GetTimeout()
    EIO_Status SetTimeout(EIO_Event event, const STimeout* timeout);

    /// Get pipe I/O timeout.
    ///
    /// @param event
    ///   I/O event for which timeout is obtained.
    /// @return
    //    Timeout for specified event (or NULL, if the timeout is infinite).
    ///   The returned timeout is guaranteed to be pointing to a valid
    ///   (and correct) structure in memory at least until the pipe is
    ///   closed or SetTimeout() is called for this pipe.
    /// @sa
    ///   SetTimeout()
    const STimeout* GetTimeout(EIO_Event event) const;

    /// Get the process handle for the piped child.
    ///
    /// @return
    ///   Returned value greater than 0 is a child process handle.
    ///   Return 0 if child process is not running.
    /// @sa
    ///   Open(), Close(), CProcess
    TProcessHandle GetProcessHandle(void) const;

protected:
    CPipeHandle*   m_PipeHandle;        ///< Internal pipe handle that handles
    EChildIOHandle m_ReadHandle;        ///< Default read handle

    // Last IO status
    EIO_Status     m_ReadStatus;        ///< Last read status
    EIO_Status     m_WriteStatus;       ///< Last write status

    // Timeouts
    STimeout*      m_ReadTimeout;       ///< eIO_Read timeout
    STimeout*      m_WriteTimeout;      ///< eIO_Write timeout
    STimeout*      m_CloseTimeout;      ///< eIO_Close timeout
    STimeout       m_ReadTimeoutValue;  ///< Storage for m_ReadTimeout
    STimeout       m_WriteTimeoutValue; ///< Storage for m_WriteTimeout
    STimeout       m_CloseTimeoutValue; ///< Storage for m_CloseTimeout

private:
    /// Disable copy constructor and assignment.
    CPipe(const CPipe&);
    CPipe& operator= (const CPipe&);
};


END_NCBI_SCOPE


/* @} */


/*
 * ===========================================================================
 * $Log: ncbi_pipe.hpp,v $
 * Revision 1000.2  2004/02/12 21:51:42  gouriano
 * PRODUCTION: UPGRADED [CORE_001] Dev-tree R1.20
 *
 * Revision 1.20  2003/12/04 16:29:50  ivanov
 * Added new create flags: fKeepOnClose, fCloseOnClose, fKillOnClose.
 * Added GetProcessHandle(). Comments changes.
 *
 * Revision 1.19  2003/11/13 17:51:47  lavr
 * -<stdio.h>
 *
 * Revision 1.18  2003/11/12 16:34:48  ivanov
 * Removed references to CPipeIOStream from  comments
 *
 * Revision 1.17  2003/09/23 21:03:06  lavr
 * PipeStreambuf and special stream removed: now all in ncbi_conn_stream.hpp
 *
 * Revision 1.16  2003/09/16 14:55:49  ivanov
 * Removed extra comma in the enum definition
 *
 * Revision 1.15  2003/09/09 19:23:16  ivanov
 * Comment changes
 *
 * Revision 1.14  2003/09/02 20:46:59  lavr
 * -<connect/connect_export.h> -- included from <connect/ncbi_core.h>
 *
 * Revision 1.13  2003/09/02 20:24:32  ivanov
 * Moved ncbipipe to CONNECT library from CORELIB.
 * Rewritten CPipe class using I/O timeouts.
 *
 * Revision 1.12  2003/08/26 14:06:51  siyan
 * Minor doc fixes.
 *
 * Revision 1.11  2003/08/24 22:53:03  siyan
 * Added documentation.
 *
 * Revision 1.10  2003/04/23 20:50:27  ivanov
 * Added CPipe::CloseHandle()
 *
 * Revision 1.9  2003/04/01 14:20:13  siyan
 * Added doxygen support
 *
 * Revision 1.8  2003/03/03 14:46:02  dicuccio
 * Reimplemented CPipe using separate private platform-specific implementations
 *
 * Revision 1.7  2002/12/18 22:53:21  dicuccio
 * Added export specifier for building DLLs in windows.  Added global list of
 * all such specifiers in mswin_exports.hpp, included through ncbistl.hpp
 *
 * Revision 1.6  2002/07/15 18:17:52  gouriano
 * renamed CNcbiException and its descendents
 *
 * Revision 1.5  2002/07/11 14:17:55  gouriano
 * exceptions replaced by CNcbiException-type ones
 *
 * Revision 1.4  2002/06/12 19:38:45  ucko
 * Remove a superfluous comma from the definition of EMode.
 *
 * Revision 1.3  2002/06/11 19:25:06  ivanov
 * Added class CPipeIOStream
 *
 * Revision 1.2  2002/06/10 18:35:13  ivanov
 * Changed argument's type of a running child program from char*[]
 * to vector<string>
 *
 * Revision 1.1  2002/06/10 16:57:04  ivanov
 * Initial revision
 *
 * ===========================================================================
 */

#endif  /* CONNECT__NCBI_PIPE__HPP */