boost/process/child.hpp

0001 // Copyright (c) 2006, 2007 Julio M. Merino Vidal
0002 // Copyright (c) 2008 Ilya Sokolov, Boris Schaeling
0003 // Copyright (c) 2009 Boris Schaeling
0004 // Copyright (c) 2010 Felipe Tanus, Boris Schaeling
0005 // Copyright (c) 2011, 2012 Jeff Flinn, Boris Schaeling
0006 // Copyright (c) 2016 Klemens D. Morgenstern
0007 //
0008 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0009 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0010
0011 /**
0012  * \file boost/process/child.hpp
0013  *
0014  * Defines a child process class.
0015  */
0016
0017 #ifndef BOOST_PROCESS_CHILD_HPP
0018 #define BOOST_PROCESS_CHILD_HPP
0019
0020 #include <boost/process/detail/config.hpp>
0021 #include <boost/process/detail/child_decl.hpp>
0022 #include <boost/process/detail/execute_impl.hpp>
0023
0024 #if defined(BOOST_POSIX_API)
0025 #include <boost/process/posix.hpp>
0026 #endif
0027
0028 namespace boost {
0029
0030 ///The main namespace of boost.process.
0031 namespace process {
0032
0033 template<typename ...Args>
0034 child::child(Args&&...args)
0035     : child(::boost::process::detail::execute_impl(std::forward<Args>(args)...)) {}
0036
0037
0038 ///Typedef for the type of an pid_t
0039 typedef ::boost::process::detail::api::pid_t pid_t;
0040
0041 #if defined(BOOST_PROCESS_DOXYGEN)
0042 /** The main class to hold a child process. It is simliar to [std::thread](http://en.cppreference.com/w/cpp/thread/thread),
0043  * in that it has a join and detach function.
0044  *
0045  * @attention The destructor will call terminate on the process if not joined or detached without any warning.
0046  *
0047  */
0048
0049 class child
0050 {
0051     /** Type definition for the native process handle. */
0052     typedef platform_specific native_handle_t;
0053
0054     /** Construct the child from a pid.
0055      *
0056      * @attention There is no guarantee that this will work. The process need the right access rights, which are very platform specific.
0057      */
0058     explicit child(pid_t & pid) : _child_handle(pid) {};
0059
0060     /** Move-Constructor.*/
0061     child(child && lhs);
0062
0063     /** Construct a child from a property list and launch it
0064      * The standard version is to create a subprocess, which will spawn the process.
0065      */
0066     template<typename ...Args>
0067     explicit child(Args&&...args);
0068
0069     /** Construct an empty child. */
0070     child() = default;
0071
0072     /** Move assign. */
0073     child& operator=(child && lhs);
0074
0075     /** Detach the child, i.e. let it run after this handle dies. */
0076     void detach();
0077     /** Join the child. This just calls wait, but that way the naming is similar to std::thread */
0078     void join();
0079     /** Check if the child is joinable. */
0080     bool joinable();
0081
0082     /** Destructor.
0083      * @attention Will call terminate (without warning) when the child was neither joined nor detached.
0084      */
0085     ~child();
0086
0087     /** Get the native handle for the child process. */
0088     native_handle_t native_handle() const;
0089
0090     /** Get the exit_code. The return value is without any meaning if the child wasn't waited for or if it was terminated. */
0091     int exit_code() const;
0092     /** Get the Process Identifier. */
0093     pid_t id()      const;
0094
0095     /** Get the native, uninterpreted exit code. The return value is without any meaning if the child wasn't waited
0096      *  for or if it was terminated. */
0097     int native_exit_code() const;
0098
0099     /** Check if the child process is running. */
0100     bool running();
0101     /** \overload void running() */
0102     bool running(std::error_code & ec) noexcept;
0103
0104     /** Wait for the child process to exit. */
0105     void wait();
0106     /** \overload void wait() */
0107     void wait(std::error_code & ec) noexcept;
0108
0109     /** Wait for the child process to exit for a period of time.
0110      * \return True if child exited while waiting.
0111      */
0112     template< class Rep, class Period >
0113     bool wait_for  (const std::chrono::duration<Rep, Period>& rel_time);
0114     /** \overload bool wait_for(const std::chrono::duration<Rep, Period>& rel_time) */
0115     bool wait_for  (const std::chrono::duration<Rep, Period>& rel_time, std::error_code & ec) noexcept;
0116
0117     /** Wait for the child process to exit until a point in time.
0118       * \return True if child exited while waiting.*/
0119     template< class Clock, class Duration >
0120     bool wait_until(const std::chrono::time_point<Clock, Duration>& timeout_time );
0121     /** \overload bool wait_until(const std::chrono::time_point<Clock, Duration>& timeout_time )*/
0122     bool wait_until(const std::chrono::time_point<Clock, Duration>& timeout_time, std::error_code & ec) noexcept;
0123
0124     /** Check if this handle holds a child process.
0125      * @note That does not mean, that the process is still running. It only means, that the handle does or did exist.
0126      */
0127     bool valid() const;
0128     /** Same as valid, for convenience. */
0129     explicit operator bool() const;
0130
0131     /** Check if the the chlid process is in any process group. */
0132     bool in_group() const;
0133
0134     /** \overload bool in_group() const */
0135     bool in_group(std::error_code & ec) const noexcept;
0136
0137     /** Terminate the child process.
0138      *
0139      *  This function will cause the child process to unconditionally and immediately exit.
0140      *  It is implement with [SIGKILL](http://pubs.opengroup.org/onlinepubs/009695399/functions/kill.html) on posix
0141      *  and [TerminateProcess](https://technet.microsoft.com/en-us/library/ms686714.aspx) on windows.
0142      *
0143      */
0144     void terminate();
0145
0146     /** \overload void terminate() */
0147     void terminate(std::error_code & ec) noexcept;
0148 };
0149
0150 #endif
0151
0152 }}
0153 #endif
0154