Ви не можете вибрати більше 25 тем Теми мають розпочинатися з літери або цифри, можуть містити дефіси (-) і не повинні перевищувати 35 символів.

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341
  1. // \file child.hpp
  2. //
  3. // Copyright (C) 2014 MicroNeil Research Corporation.
  4. //
  5. // This program is part of the MicroNeil Research Open Library Project. For
  6. // more information go to http://www.microneil.com/OpenLibrary/index.html
  7. //
  8. // This program is free software; you can redistribute it and/or modify it
  9. // under the terms of the GNU General Public License as published by the
  10. // Free Software Foundation; either version 2 of the License, or (at your
  11. // option) any later version.
  12. //
  13. // This program is distributed in the hope that it will be useful, but WITHOUT
  14. // ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  15. // FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  16. // more details.
  17. //
  18. // You should have received a copy of the GNU General Public License along with
  19. // this program; if not, write to the Free Software Foundation, Inc., 59 Temple
  20. // Place, Suite 330, Boston, MA 02111-1307 USA
  21. //==============================================================================
  22. /*
  23. \brief The child module provides classes to spawn and communicate
  24. with child processes.
  25. */
  26. #ifndef CHILD_HPP
  27. #define CHILD_HPP
  28. #ifdef _WIN32
  29. #include <windows.h>
  30. #endif
  31. #include <cstdint>
  32. #include <streambuf>
  33. #include <istream>
  34. #include <ostream>
  35. #include <string>
  36. #include <vector>
  37. namespace CodeDweller {
  38. /**
  39. \namespace CodeDweller
  40. The CodeDweller namespace contains components providing high-level
  41. functionality for applications.
  42. */
  43. /** Class that abstracts the creation of child processes.
  44. This class provides functionality to create a child process,
  45. communicate with the child process via streams and signals, and
  46. obtain the exit code of the child process.
  47. */
  48. class Child {
  49. private:
  50. /// Streambuf class for reading the standard output of the child
  51. /// process.
  52. class ReadStreambuf : public std::streambuf {
  53. friend class Child;
  54. public:
  55. /// Reader streambuf constructor.
  56. //
  57. // \param[in] bufferSize is the size in bytes of the input
  58. // buffer.
  59. //
  60. explicit ReadStreambuf(std::size_t bufferSize = 4096);
  61. #ifdef _WIN32
  62. /// Set the handle to read the standard output of the child
  63. /// process.
  64. //
  65. // \param[in] inHandle is the input handle for the standard
  66. // output of the child process.
  67. //
  68. void setInputHandle(HANDLE inHandle);
  69. #else
  70. /// Set the file descriptor to read the standard output of the
  71. /// child process.
  72. //
  73. // \param[in] inFd is the input file descriptor for the standard
  74. // output of the child process.
  75. //
  76. void setInputFileDescriptor(int inFd);
  77. #endif
  78. private:
  79. /** Return the number of bytes that can be read without
  80. blocking.
  81. This method checks if any input is available from the pipe,
  82. and returns the number of bytes in the input buffer plus 1.
  83. Reading that number of bytes will not block. Reading a
  84. larger number of bytes might block.
  85. \returns minimum number of bytes that can be read without
  86. blocking.
  87. */
  88. size_t numBytesAvailable() const;
  89. /// Override streambuf::underflow().
  90. int_type underflow();
  91. /// Copy constructor not implemented.
  92. ReadStreambuf(const ReadStreambuf &);
  93. /// Copy constructor not implemented.
  94. ReadStreambuf &operator=(const ReadStreambuf &);
  95. /// Input handle.
  96. #ifdef _WIN32
  97. HANDLE inputHandle;
  98. #else
  99. int inputFileDescriptor;
  100. #endif
  101. /// Read buffer.
  102. std::vector<char> buffer;
  103. };
  104. /// Streambuf class for writing to the standard input of the child
  105. /// process.
  106. //
  107. // Note: If an error occurs when writing the output from the
  108. // parent process, the output buffer is cleared.
  109. //
  110. class WriteStreambuf : public std::streambuf {
  111. public:
  112. /// Writer streambuf constructor.
  113. //
  114. // \param[in] bufferSize is the size in bytes of the input
  115. // buffer.
  116. //
  117. explicit WriteStreambuf(std::size_t bufferSize = 4096);
  118. #ifdef _WIN32
  119. /// Set the handle to write the standard input of the child
  120. /// process.
  121. //
  122. // \param[in] outHandle is the output handle for the standard
  123. // input of the child process.
  124. //
  125. void setOutputHandle(HANDLE outHandle);
  126. #else
  127. /// Set the file descriptor to write the standard input of the
  128. /// child process.
  129. //
  130. // \param[in] outFd is the output file descriptor for the
  131. // standard input of the child process.
  132. //
  133. void setOutputFileDescriptor(int outFd);
  134. #endif
  135. private:
  136. /// Flush the output buffer.
  137. void flushBuffer();
  138. /// Override streambuf::overflow().
  139. int_type overflow(int_type ch);
  140. /// Override streambuf::sync().
  141. int sync();
  142. /// Copy constructor not implemented.
  143. WriteStreambuf(const WriteStreambuf &);
  144. /// Copy constructor not implemented.
  145. WriteStreambuf &operator=(const WriteStreambuf &);
  146. /// Output handle.
  147. #ifdef _WIN32
  148. HANDLE outputHandle;
  149. #else
  150. int outputFileDescriptor;
  151. #endif
  152. /// Write buffer.
  153. std::vector<char> buffer;
  154. };
  155. /// Stream buffer for reading from the stdout of the child process;
  156. ReadStreambuf readStreambuf;
  157. /// Stream buffer for writing to the stdin of the child process;
  158. WriteStreambuf writeStreambuf;
  159. public:
  160. /** Constructor for spawning with command-line parameters.
  161. The constructor configures the object, but doesn't spawn the
  162. child process.
  163. \param[in] args contains the child executable file name and
  164. command-line parameters. args[0] contains the full path of the
  165. executable, and args[1] thru args[n] are the command-line
  166. parameters.
  167. \param[in] bufSize is the buffer size of the reader and writer
  168. streams used to communicate with the child process.
  169. */
  170. Child(std::vector<std::string> args, size_t bufSize = 4096);
  171. /** Constructor for spawning without command-line parameters.
  172. The constructor configures the object, but doesn't spawn the
  173. child process.
  174. \param[in] childpath contains the child executable file name.
  175. \param[in] bufSize is the buffer size of the reader and writer
  176. streams used to communicate with the child process.
  177. */
  178. Child(std::string childpath, size_t bufSize = 4096);
  179. /** Destructor terminates the child process. */
  180. ~Child();
  181. /// Input stream to read data from the child's standard output.
  182. std::istream reader;
  183. /** Get the number of bytes available for input.
  184. @returns number of bytes that can be read from reader without
  185. blocking.
  186. */
  187. size_t numBytesAvailable() const;
  188. /// Output stream to write data to the child's standard input.
  189. std::ostream writer;
  190. /** Spawn the child process.
  191. \throws runtime_error if an error occurs.
  192. */
  193. void run();
  194. /** Terminite the child process.
  195. \throws runtime_error if an error occurs.
  196. \throws logic_error if the child process is not running.
  197. */
  198. void terminate();
  199. /** Check whether the child process has exited.
  200. \returns True if the child process has exited, false
  201. otherwise.
  202. \throws runtime_error if an error occurs.
  203. \throws logic_error if the child process is not running.
  204. */
  205. bool isDone();
  206. /** Get the exit value of the child process.
  207. \returns The exit value of the child process if the child
  208. process has exited.
  209. \throws runtime_error if an error occurs.
  210. \throws logic_error if the child process has not exited.
  211. \throws logic_error if the child process is not running.
  212. */
  213. int32_t result();
  214. private:
  215. /// Exit code to use when terminating the child process.
  216. static const uint32_t terminateExitCode = 0;
  217. /// True if the child process was successfully started.
  218. bool childStarted;
  219. /// True if the child process has exited.
  220. bool childExited;
  221. /// Initialize data members.
  222. void init();
  223. /// Child executable path and command-line parameters.
  224. std::vector<std::string> cmdArgs;
  225. /// Child executable path and command-line parameters.
  226. std::string cmdline;
  227. #ifdef _WIN32
  228. /// Child's process handle.
  229. HANDLE childProcess;
  230. /// Child's thread handle.
  231. HANDLE childThread;
  232. #else
  233. /// Child process ID.
  234. pid_t childPid;
  235. #endif
  236. /// Exit value of the process.
  237. int32_t exitCode;
  238. /// True if the exit code has been obtained.
  239. bool exitCodeObtainedFlag;
  240. /// Return text for the most recent error.
  241. //
  242. // \returns Human-readable description of the most recent error.
  243. //
  244. static std::string getErrorText();
  245. };
  246. }
  247. #endif // CHILD_HPP