process/v2/process_handle.hpp

0001 // Copyright (c) 2022 Klemens D. Morgenstern
0002 //
0003 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0004 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0005 #ifndef BOOST_PROCESS_V2_PROCESS_HANDLE_HPP
0006 #define BOOST_PROCESS_V2_PROCESS_HANDLE_HPP
0007
0008 #include <boost/process/v2/detail/config.hpp>
0009
0010 #if defined(BOOST_PROCESS_V2_WINDOWS)
0011 #include <boost/process/v2/detail/process_handle_windows.hpp>
0012 #else
0013
0014 #if defined(BOOST_PROCESS_V2_PIDFD_OPEN)
0015 #include <boost/process/v2/detail/process_handle_fd.hpp>
0016 #elif defined(BOOST_PROCESS_V2_PDFORK)
0017 #include <boost/process/v2/detail/process_handle_fd_or_signal.hpp>
0018 #else
0019 // with asio support we could use EVFILT_PROC:NOTE_EXIT as well.
0020 #include <boost/process/v2/detail/process_handle_signal.hpp>
0021 #endif
0022 #endif
0023
0024 BOOST_PROCESS_V2_BEGIN_NAMESPACE
0025
0026
0027 #if defined(GENERATING_DOCUMENTATION)
0028 /** A process handle is an unmanaged version of a process.
0029  * This means it does not terminate the process on destruction and
0030  * will not keep track of the exit-code.
0031  *
0032  * Note that the exit code might be discovered early, during a call to `running`.
0033  * Thus it can only be discovered that process has exited already.
0034  */
0035 template<typename Executor = net::any_io_executor>
0036 struct basic_process_handle
0037 {
0038     /// The native handle of the process.
0039     /** This might be undefined on posix systems that only support signals */
0040     using native_handle_type = implementation_defined;
0041
0042     /// The executor_type of the process_handle
0043     using executor_type =  Executor;
0044
0045     /// Getter for the executor
0046     executor_type get_executor();
0047
0048     /// Rebinds the process_handle to another executor.
0049     template<typename Executor1>
0050     struct rebind_executor
0051     {
0052         /// The socket type when rebound to the specified executor.
0053         typedef basic_process_handle<Executor1> other;
0054     };
0055
0056
0057     /// Construct a basic_process_handle from an execution_context.
0058     /**
0059     * @tparam ExecutionContext The context must fulfill the asio::execution_context requirements
0060     */
0061     template<typename ExecutionContext>
0062     basic_process_handle(ExecutionContext &context);
0063
0064     /// Construct an empty process_handle from an executor.
0065     basic_process_handle(executor_type executor);
0066
0067     /// Construct an empty process_handle from an executor and bind it to a pid.
0068     /** On NON-linux posix systems this call is not able to obtain a file-descriptor and will thus
0069      * rely on signals.
0070      */
0071     basic_process_handle(executor_type executor, pid_type pid);
0072
0073     /// Construct an empty process_handle from an executor and bind it to a pid and the native-handle
0074     /** On some non-linux posix systems this overload is not present.
0075      */
0076     basic_process_handle(executor_type executor, pid_type pid, native_handle_type process_handle);
0077
0078     /// Move construct and rebind the executor.
0079     template<typename Executor1>
0080     basic_process_handle(basic_process_handle<Executor1> &&handle);
0081
0082     /// Get the id of the process
0083     pid_type id() const
0084     { return pid_; }
0085
0086     /// Terminate the process if it's still running and ignore the result
0087     void terminate_if_running(error_code &);
0088
0089     /// Throwing @overload void terminate_if_running(error_code & ec;
0090     void terminate_if_running();
0091     /// wait for the process to exit and store the exit code in exit_status.
0092     void wait(native_exit_code_type &exit_status, error_code &ec);
0093     /// Throwing @overload wait(native_exit_code_type &exit_code, error_code & ec)
0094     void wait(native_exit_code_type &exit_status);
0095
0096     /// Sends the process a signal to ask for an interrupt, which the process may interpret as a shutdown.
0097     /** Maybe be ignored by the subprocess. */
0098     void interrupt(error_code &ec);
0099
0100     /// Throwing @overload void interrupt()
0101     void interrupt();
0102
0103     /// Sends the process a signal to ask for a graceful shutdown. Maybe be ignored by the subprocess.
0104     void request_exit(error_code &ec);
0105
0106     /// Throwing @overload void request_exit(error_code & ec)
0107     void request_exit()
0108
0109     /// Unconditionally terminates the process and stores the exit code in exit_status.
0110     void terminate(native_exit_code_type &exit_status, error_code &ec);\
0111     /// Throwing @overload void terminate(native_exit_code_type &exit_code, error_code & ec)
0112     void terminate(native_exit_code_type &exit_status);/
0113
0114     /// Checks if the current process is running.
0115     /**If it has already completed, it assigns the exit code to `exit_code`.
0116      */
0117     bool running(native_exit_code_type &exit_code, error_code &ec);
0118     /// Throwing @overload bool running(native_exit_code_type &exit_code, error_code & ec)
0119     bool running(native_exit_code_type &exit_code);
0120
0121     /// Check if the process handle is referring to an existing process.
0122     bool is_open() const;
0123
0124     /// Asynchronously wait for the process to exit and deliver the native exit-code in the completion handler.
0125     template<BOOST_PROCESS_V2_COMPLETION_TOKEN_FOR(void(error_code, native_exit_code_type))
0126              WaitHandler = net::default_completion_token_t<executor_type>>
0127     auto async_wait(WaitHandler &&handler = net::default_completion_token_t<executor_type>());
0128 };
0129
0130
0131 #else
0132 #if defined(BOOST_PROCESS_V2_WINDOWS)
0133 template<typename Executor = net::any_io_executor>
0134 using basic_process_handle = detail::basic_process_handle_win<Executor>;
0135 #else
0136
0137 #if defined(BOOST_PROCESS_V2_PIDFD_OPEN)
0138 template<typename Executor = net::any_io_executor>
0139 using basic_process_handle = detail::basic_process_handle_fd<Executor>;
0140 #elif defined(BOOST_PROCESS_V2_PDFORK) || defined(BOOST_PROCESS_V2_PIPE_LAUNCHER)
0141 template<typename Executor = net::any_io_executor>
0142 using basic_process_handle = detail::basic_process_handle_fd_or_signal<Executor>;
0143 #else
0144
0145 template<typename Executor = net::any_io_executor>
0146 using basic_process_handle = detail::basic_process_handle_signal<Executor>;
0147
0148 #endif
0149 #endif
0150
0151 /// Process handle with the default executor.
0152 using process_handle = basic_process_handle<>;
0153
0154 #endif
0155
0156 BOOST_PROCESS_V2_END_NAMESPACE
0157
0158 #endif //BOOST_PROCESS_V2_PROCESS_HANDLE_HPP