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

#include <windows.h> 

#include <cstdint>
#include <istream>
#include <ostream>
#include <string>
#include <vector>

namespace CodeDweller {

  /**
     \namespace CodeDweller

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

  */

  /** Class that abstracts the creation of child processes.

      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 Child {

  public:

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

	The constructor configures the object, but doesn't 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.

    */
    Child(std::vector<std::string> args);

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

	The constructor configures the object, but doesn't spawn the
	child process.

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

    */
    Child(std::string childpath);

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

    /// Return a stream that is seen by the child as standard output.
    std::istream *reader();

    /// Return a stream that is seen by the child as standard input.
    std::ostream *writer();

    /** Spawn the child process.

	If an error occurs, an exception is thrown.

    */
    void run();

    /** Terminite the child process.

	If an error occurs, an exception is thrown.

    */
    void terminate();

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

	\returns The exit value of the child process if the child
	process has exited.  If the child process has not exited, an
	exception is thrown.

    */
    int32_t result();

  private:

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

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

    /// Child executable path and command-line parameters.
    std::string cmdline;

    /// Parent's read handle for child process standard output.
    HANDLE childStdOutAtParent;

    /// Parent's write handle for child process standard input.
    HANDLE childStdInAtParent;

    /// Child's process handle.
    HANDLE childProcess;

    /// Child's thread handle.
    HANDLE childThread;

    /// 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.
    //
    std::string getErrorText();
  };

}

#endif // CHILD_HPP