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 proces 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 = BOOST_PROCESS_V2_ASIO_NAMESPACE::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 BOOST_PROCESS_V2_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
0127              BOOST_PROCESS_V2_INITFN_AUTO_RESULT_TYPE(WaitHandler, void (error_code, native_exit_code_type))
0128     async_wait(WaitHandler &&handler BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type));
0129
0130 };
0131
0132
0133 #else
0134 #if defined(BOOST_PROCESS_V2_WINDOWS)
0135 template<typename Executor = BOOST_PROCESS_V2_ASIO_NAMESPACE::any_io_executor>
0136 using basic_process_handle = detail::basic_process_handle_win<Executor>;
0137 #else
0138
0139 #if defined(BOOST_PROCESS_V2_PIDFD_OPEN)
0140 template<typename Executor = BOOST_PROCESS_V2_ASIO_NAMESPACE::any_io_executor>
0141 using basic_process_handle = detail::basic_process_handle_fd<Executor>;
0142 #elif defined(BOOST_PROCESS_V2_PDFORK)
0143 template<typename Executor = BOOST_PROCESS_V2_ASIO_NAMESPACE::any_io_executor>
0144 using basic_process_handle = detail::basic_process_handle_fd_or_signal<Executor>;
0145 #else
0146
0147 template<typename Executor = BOOST_PROCESS_V2_ASIO_NAMESPACE::any_io_executor>
0148 using basic_process_handle = detail::basic_process_handle_signal<Executor>;
0149
0150 #endif
0151 #endif
0152
0153 /// Process handle with the default executor.
0154 using process_handle = basic_process_handle<>;
0155
0156 #endif
0157
0158 BOOST_PROCESS_V2_END_NAMESPACE
0159
0160 #if defined(BOOST_PROCESS_V2_HEADER_ONLY)
0161
0162 #include <boost/process/v2/impl/process_handle.ipp>
0163
0164 #endif
0165
0166
0167
0168
0169 #endif //BOOST_PROCESS_V2_PROCESS_HANDLE_HPP