CodeDweller/child.hpp

// \file child.hpp
//
// Copyright (C) 2014 MicroNeil Research Corporation.
//
// This program is part of the MicroNeil Research Open Library Project. For
// more information go to http://www.microneil.com/OpenLibrary/index.html
//
// This program is free software; you can redistribute it and/or modify it
// under the terms of the GNU General Public License as published by the
// Free Software Foundation; either version 2 of the License, or (at your
// option) any later version.
//
// This program is distributed in the hope that it will be useful, but WITHOUT
// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
// FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
// more details.
//
// You should have received a copy of the GNU General Public License along with
// this program; if not, write to the Free Software Foundation, Inc., 59 Temple
// Place, Suite 330, Boston, MA 02111-1307 USA
//==============================================================================

/*
  \brief The child module provides classes to spawn and communicate
  with child processes.
*/

#ifndef CHILD_HPP
#define CHILD_HPP

#ifdef _WIN32
#include <windows.h> 
#endif

#include <cstdint>
#include <streambuf>
#include <iostream>
#include <string>
#include <vector>
#include <thread>
#include <mutex>

namespace CodeDweller {

  /**
     \namespace CodeDweller

     The CodeDweller namespace contains components providing high-level
     functionality for applications.

  */

  /** Class that abstracts the iostreams communication with a child
      process.

      This class provides functionality to create a child process,
      communicate with the child process via streams and signals, and
      obtain the exit code of the child process.

  */

  class ChildStream : public std::iostream {

  private:

    /// Streambuf class for reading from the standard output and
    /// writing to the standard input of the child process.
    class ChildStreambuf : public std::streambuf {

      friend class ChildStream;

    public:

      /// Constructor.
      //
      // \param[in] bufSize is the size in bytes of the input
      // buffer and output buffer.
      //
      explicit ChildStreambuf(std::size_t bufSize = 4096);

#ifdef _WIN32

      /// Set the handle to read the standard output of the child
      /// process.
      //
      // \param[in] inHandle is the input handle for the standard
      // output of the child process.
      //
      void setInputHandle(HANDLE inHandle);

      /// Set the handle to write the standard input of the child
      /// process.
      //
      // \param[in] outHandle is the output handle for the standard
      // input of the child process.
      //
      void setOutputHandle(HANDLE outHandle);

#else

      /// Set the file descriptor to read the standard output of the
      /// child process.
      //
      // \param[in] inFd is the input file descriptor for the standard
      // output of the child process.
      //
      void setInputFileDescriptor(int inFd);

      /// Set the file descriptor to write the standard input of the
      /// child process.
      //
      // \param[in] outFd is the output file descriptor for the
      // standard input of the child process.
      //
      void setOutputFileDescriptor(int outFd);

#endif

    private:

      /** Return the number of bytes that can be read without
	  blocking.

	  This method checks if any input is available from the pipe,
	  and returns the number of bytes in the input buffer plus 1.
	  Reading that number of bytes will not block.  Reading a
	  larger number of bytes might block.

	  \returns minimum number of bytes that can be read without
	  blocking.

       */
      size_t numBytesAvailable() const;

      /// Override streambuf::underflow().
      int_type underflow();

      /// Flush the output buffer.
      void flushBuffer();

      /// Override streambuf::overflow().
      int_type overflow(int_type ch);

      /// Override streambuf::sync().
      int sync();

      /// Input and output handles.
#ifdef _WIN32
      HANDLE inputHandle;
      HANDLE outputHandle;
#else
      int inputFileDescriptor;
      int outputFileDescriptor;
#endif

      /// Size of buffers.
      std::size_t bufferSize;

      /// Read buffer.
      std::vector<char> readBuffer;

      /// Write buffer.
      std::vector<char> writeBuffer;

      /// Copy constructor not implemented.
      ChildStreambuf(const ChildStreambuf &) = delete;

      /// Assignment operator not implemented.
      ChildStreambuf &operator=(const ChildStreambuf &) = delete;

    };

    /// Stream buffer for reading from the stdout and writing to the
    /// stdin of the child process.
    ChildStreambuf childStreambuf;

  public:

    /** Constructor for spawning with command-line parameters.

	The constructor configures the object, and spawns the child
	process.

	\param[in] args contains the child executable file name and
	command-line parameters. args[0] contains the full path of the
	executable, and args[1] thru args[n] are the command-line
	parameters.

	\param[in] bufSize is the input and output buffer size of the
	stream used to communicate with the child process.

	\throws runtime_error if an error occurs.

    */
    ChildStream(std::vector<std::string> const &args, size_t bufSize = 4096);

    /** Constructor for spawning without command-line parameters.

	The constructor configures the object, and spawns the child
	process.

	\param[in] childpath contains the child executable file name.

	\param[in] bufSize is the input and output buffer size of the
	stream used to communicate with the child process.

	\throws runtime_error if an error occurs.

    */
    ChildStream(std::string const &childpath, size_t bufSize = 4096);

    /** Constructor.

	The constructor configures the I/O buffers, but doesn't spawn
	any child process.

	\param[in] bufSize is the input and output buffer size of the
	stream used to communicate with the child process.

    */
    ChildStream(size_t bufSize = 4096);

    /** Destructor terminates the child process. */
    ~ChildStream();

    /** Spawn the child process.

	\param[in] args contains the child executable file name and
	command-line parameters. args[0] contains the full path of the
	executable, and args[1] thru args[n] are the command-line
	parameters.

	\throws runtime_error if an error occurs.

	\throws runtime_error if an error occurs.

    */
    void open(std::vector<std::string> const &args);

    /** Spawn the child process.

	\param[in] childpath contains the child executable file name.

	\throws runtime_error if an error occurs.

    */
    void open(std::string const &childpath);

    /** Get the number of bytes available for input.

	@returns number of bytes that can be read without blocking.

    */
    size_t numBytesAvailable() const;

    /** Check whether the child process is running.

	\returns True if the child process is running, false
	otherwise.

    */
    bool isRunning() const;

    /** Terminate the child process.

	\throws runtime_error if an error occurs.

	\throws logic_error if the child process is not running.

    */
    void close();

    /** Check whether the child process has exited.

	\returns True if the child process has exited, false
	otherwise.

	\throws runtime_error if an error occurs.

	\throws logic_error if the child process is not running.

    */
    bool isDone();

    /** Get the exit value of the child process.

	\returns The exit value of the child process if the child
	process has exited.

	\throws runtime_error if an error occurs.

	\throws logic_error if the child process has not exited.

	\throws logic_error if the child process is not running.

    */
    int32_t result();

  private:

    /** Spawn the child process.

	\throws runtime_error if an error occurs.

    */
    void run();

    /// Exit code to use when terminating the child process.
    static const uint32_t terminateExitCode = 0;

    /// True if the child process was successfully started.
    bool childStarted;

    /// True if the child process has exited.
    bool childExited;

    /// Initialize data members.
    void init();

    /// Child executable path and command-line parameters.
    std::vector<std::string> cmdArgs;

#ifdef _WIN32
    /// Child's process handle.
    HANDLE childProcess;

    /// Child's thread handle.
    HANDLE childThread;
#else
    /// Child process ID.
    pid_t childPid;
#endif

    /// Exit value of the process.
    int32_t exitCode;

    /// True if the exit code has been obtained.
    bool exitCodeObtainedFlag;

    /// Return text for the most recent error.
    //
    // \returns Human-readable description of the most recent error.
    //
    static std::string getErrorText();

  };

  /** Class that abstracts the non-blocking communication with a child
      process.

      This class provides functionality to create a child process,
      communicate with the child process via non-blocking methods, and
      obtain the exit code of the child process.

  */

  class Child {

  private:

    /** Circular buffer of characters. */
    class CircularBuffer {

    public:

      /** Constructor specifies the capacity.

          @param[in] maxSize is the capacity of the buffer.

      */
      CircularBuffer(size_t maxSize);

      /** Check whether the container is empty.

          @returns true if the container is empty, false otherwise.

      */
      bool empty() const;

      /** Get the size.

          @returns the number of bytes in the buffer.

      */
      size_t nUsed() const;

      /** Get the available space.

          @returns the number of bytes that can be written to the
          buffer without overwriting any existing data.

      */
      size_t nFree() const;

      /** Clear the buffer. */
      void clear();

      /** Put bytes to the buffer.

          @param[in] ptr is the address of the first byte to put.

          @param[in] nBytes is the number of bytes to put.

      */
      void put(char const *ptr, size_t nBytes);

      /** Get bytes from the buffer.

          This method gets the specified number of bytes from the
          buffer, and erases those bytes from the buffer.

          @param[out] buf receives the data.  The contents of buf are
          replaced with the data in the circular buffer.

          @param[in] nBytes is the number of bytes to get.  Specifying
          a value of zero for nBytes gets and erases all the data.

      */
      void getAndErase(std::string &buf, size_t nBytes = 0);

    private:

      /** Increment the index.

          @param[in] index is the index to increment.

      */
      void nextIndex(size_t &index) const {
        index++;
        if (index >= capacity)
          index = 0;
      }

      /// Buffer to hold data.
      std::vector<char> buffer;

      /// Capacity of the buffer.
      size_t capacity;

      /// Index of first element.
      size_t iBegin;

      /// Index of one past the last element.
      size_t iEnd;

    };

  public:

    /** Constructor for spawning with command-line parameters.

	The constructor configures the object, and spawns the child
	process.

	\param[in] args contains the child executable file name and
	command-line parameters. args[0] contains the full path of the
	executable, and args[1] thru args[n] are the command-line
	parameters.

	\param[in] bufSize is the input and output buffer size of the
	stream used to communicate with the child process.

        \param[in] nominalAboveMinPollTime_ms is used to determine the
        minimum time in milliseconds that the writer thread sleeps
        when there's no data in the output buffer, and that the reader
        thread sleeps when there's no room in the input buffer.  The
        minimum time is nominalAboveMinPollTime_ms +
        CodeDweller::MinimumSleeperTime.

        \param[in] deltaPollTime_ms is how much longer, in
        milliseconds, the maximum time to sleep is than the minimum time.

	\throws runtime_error if an error occurs.

    */
    Child(std::vector<std::string> const &args,
          size_t bufSize = 128 * 1024,
          std::uint16_t nominalAboveMinPollTime_ms = 0,
          std::uint16_t deltaPollTime_ms = 500);

    /** Constructor for spawning without command-line parameters.

	The constructor configures the object, and spawns the child
	process.

	\param[in] childpath contains the child executable file name.

	\param[in] bufSize is the input and output buffer size of the
	stream used to communicate with the child process.

        \param[in] nominalAboveMinPollTime_ms is used to determine the
        minimum time in milliseconds that the writer thread sleeps
        when there's no data in the output buffer, and that the reader
        thread sleeps when there's no room in the input buffer.  The
        minimum time is nominalAboveMinPollTime_ms +
        CodeDweller::MinimumSleeperTime.

        \param[in] deltaPollTime_ms is how much longer, in
        milliseconds, the maximum time to sleep is than the minimum time.

	\throws runtime_error if an error occurs.

    */
    Child(std::string const &childpath,
          size_t bufSize = 128 * 1024,
          std::uint16_t nominalAboveMinPollTime_ms = 0,
          std::uint16_t deltaPollTime_ms = 500);

    /** Constructor.

	The constructor configures the I/O buffers, but doesn't spawn
	any child process.

	\param[in] bufSize is the input and output buffer size of the
	stream used to communicate with the child process.

        \param[in] nominalAboveMinPollTime_ms is used to determine the
        minimum time in milliseconds that the writer thread sleeps
        when there's no data in the output buffer, and that the reader
        thread sleeps when there's no room in the input buffer.  The
        minimum time is nominalAboveMinPollTime_ms +
        CodeDweller::MinimumSleeperTime.

        \param[in] deltaPollTime_ms is how much longer, in
        milliseconds, the maximum time to sleep is than the minimum time.

    */
    Child(size_t bufSize = 4096,
          std::uint16_t nominalAboveMinPollTime_ms = 0,
          std::uint16_t deltaPollTime_ms = 500);

    /** Destructor terminates the child process. */
    ~Child();

    /** Spawn the child process.

	\param[in] args contains the child executable file name and
	command-line parameters. args[0] contains the full path of the
	executable, and args[1] thru args[n] are the command-line
	parameters.

	\throws runtime_error if an error occurs.

	\throws runtime_error if an error occurs.

    */
    void open(std::vector<std::string> const &args);

    /** Spawn the child process.

	\param[in] childpath contains the child executable file name.

	\throws runtime_error if an error occurs.

    */
    void open(std::string const &childpath);

    /** All-or-nothing non-blocking queue write request to the child.

        This methods attempts to queue a write request consisting of
        the entire contents of the string.

        @param[in] data is the data to queue.

        @returns true if the write request was queued, false
        otherwise.

    */
    bool write(std::string const &data);

    /** Non-blocking queue write request to the child.

        This methods attempts to queue a write request consisting of
        as much as possible of the contents of the string.

        @param[in, out] data on input is the data to queue.  On
        output, data contains the data that was not queued.

        @returns the number of bytes queued.

    */
    size_t writeAndShrink(std::string &data);

    /** Check if all queued data was transmitted.

        @returns true if all the queued data was transmitted to the
        child, false otherwise.

    */
    bool isFinishedWriting() const;

    /** Non-blocking request to get data read from the child.

        This method attempts to get up to a specified number of bytes
        of data from the input buffer containing data received from
        the child.  The data that is provided is erased from the input
        buffer.

        @param[out] data contains the copied data.

        @param[in] nBytes is the number of bytes to attempt to copy.
        If nBytes is zero, the contents of the entire input buffer is
        moved to data.

        @returns the number of bytes copied.

    */
    size_t read(std::string &data, size_t nBytes = 0);

    /** Check whether the child process is running.

	\returns True if the child process is running, false
	otherwise.

    */
    bool isRunning() const;

    /** Check error status.

        This method checks whether an error occurred when
        communicating with the child process.

        \param[out] errorDescription contains any description of the
        error.

        \returns true if an error occurred, false otherwise.

    */
    bool errorOccurred(std::string &errorDescription) const;

    /** Close the connection.

        This method terminate the child process if it is running, and
        resets the object.  After this method is invoked, open() can
        be invoked to spawn and communicate with another child
        process.

	\throws runtime_error if an error occurs.

	\throws logic_error if the child process is not running.

    */
    void close();

    /** Check whether the child process has exited.

	\returns True if the child process has exited, false
	otherwise.

	\throws runtime_error if an error occurs.

	\throws logic_error if the child process is not running.

    */
    bool isDone();

    /** Get the exit value of the child process.

	\returns The exit value of the child process if the child
	process has exited.

	\throws runtime_error if an error occurs.

	\throws logic_error if the child process has not exited.

	\throws logic_error if the child process is not running.

    */
    int32_t result();

  private:

    /// Initialize data members.
    void init();

    /** Spawn the child process.

	\throws runtime_error if an error occurs.

    */
    void run();

    /// Reader thread object.
    std::thread readerThread;

    /// Thread start function to read data from the child.
    void readFromChild();

    /// Writer thread object.
    std::thread writerThread;

    /// Thread start function to send data to the child.
    void writeToChild();

    /// True if readerThread and writerThread are to stop.
    bool stopFlag;

    /// True if both the reader and writer the writer threads are
    /// running, false otherwise.
    bool threadsAreRunning;

    /// Description of any error.
    std::string errorText;

    /// Input and output handles.
#ifdef _WIN32
    HANDLE inputHandle;
    HANDLE outputHandle;
#else
    int inputFileDescriptor;
    int outputFileDescriptor;
#endif

    /// Capacity of buffers.
    std::size_t bufferCapacity;

    /// Read buffer.
    CircularBuffer readBuffer;

    /// Mutex to serialize access to readBuffer.
    std::mutex readBufferMutex;

    /// Write buffer.
    std::vector<char> writeBuffer;

    /// Number of bytes in writeBuffer.
    size_t nWriteBytes;

    /// Mutex to serialize access to writeBuffer.
    std::mutex writeBufferMutex;

    /// Number of bytes in writer thread transmit buffer.
    size_t nTransmitBytes;

    /// Nominal poll time.
    //
    // If there isn't room in readBuffer, readerThread aperiodically
    // checks whether room is available.  The check times are
    // determined by a CodeDweller::PollTimer object, which requires a
    // nominal poll time and a maximum poll time.
    int nominalPollTime_ms;

    /// Maximum poll time.
    int maximumPollTime_ms;

    /// Exit code to use when terminating the child process.
    static const uint32_t terminateExitCode = 0;

    /// True if the child process was successfully started.
    bool childStarted;

    /// True if the child process has exited.
    bool childExited;

    /// Child executable path and command-line parameters.
    std::vector<std::string> cmdArgs;

#ifdef _WIN32
    /// Child's process handle.
    HANDLE childProcess;

    /// Child's thread handle.
    HANDLE childThread;
#else
    /// Child process ID.
    pid_t childPid;
#endif

    /// Exit value of the process.
    int32_t exitCode;

    /// True if the exit code has been obtained.
    bool exitCodeObtainedFlag;

    /// Return text for the most recent error.
    //
    // \returns Human-readable description of the most recent error.
    //
    static std::string getErrorText();

  };

}

#endif // CHILD_HPP