ceph/src/seastar/include/seastar/util/process.hh

   1 /*
   2  * This file is open source software, licensed to you under the terms
   3  * of the Apache License, Version 2.0 (the "License").  See the NOTICE file
   4  * distributed with this work for additional information regarding copyright
   5  * ownership.  You may not use this file except in compliance with the License.
   6  *
   7  * You may obtain a copy of the License at
   8  *
   9  *   http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing,
  12  * software distributed under the License is distributed on an
  13  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  14  * KIND, either express or implied.  See the License for the
  15  * specific language governing permissions and limitations
  16  * under the License.
  17  */
  18
  19 /*
  20  * Copyright (C) 2022 Kefu Chai ( tchaikov@gmail.com )
  21  */
  22
  23 #pragma once
  24
  25 #include <sys/types.h>
  26 #include <algorithm>
  27 #include <filesystem>
  28 #include <initializer_list>
  29 #include <iterator>
  30 #include <string_view>
  31 #include <utility>
  32 #include <variant>
  33 #include <vector>
  34 #include <fmt/format.h>
  35 #include <seastar/core/iostream.hh>
  36 #include <seastar/core/posix.hh>
  37 #include <seastar/core/sstring.hh>
  38
  39 namespace seastar::experimental {
  40
  41 /// The optional parameters for spawning a subprocess
  42 ///
  43 /// \note see \c execve(2) for more details on \c argv and \c env.
  44 struct spawn_parameters {
  45     /// The arguments passed to the program
  46     std::vector<sstring> argv;
  47     /// The environment variables for the program
  48     std::vector<sstring> env;
  49 };
  50
  51 /// Interact with a spawned subprocess
  52 ///
  53 /// \note the spawned subprocess should always be \c wait()'ed. Otherwise,
  54 /// the Seastar application spawning the subprocess will leave us with
  55 /// one ore more zombie subprocesses after it exists.
  56 class process {
  57     struct create_tag {};
  58     /// Spawn a subprocess using \c posix_spawn(3)
  59     ///
  60     /// \param pathname the full path to the executable
  61     /// \param params parameters for spawning the subprocess
  62     ///
  63     /// \returns a \c process instance representing the spawned subprocess
  64     static future<process> spawn(const std::filesystem::path& pathname,
  65                                  spawn_parameters params);
  66     /// Spawn a subprocess using \c posix_spawn(3)
  67     ///
  68     /// \param pathname the full path to the executable
  69     ///
  70     /// \returns a \c process instance representing the spawned subprocess
  71     static future<process> spawn(const std::filesystem::path& pathname);
  72 public:
  73     process(create_tag, pid_t pid, file_desc&& stdin, file_desc&& stdout, file_desc&& stderr);
  74     /// Return an writable stream which provides input from the child process
  75     output_stream<char> stdin();
  76     /// Return an writable stream which provides stdout output from the child process
  77     input_stream<char> stdout();
  78     /// Return an writable stream which provides stderr output from the child process
  79     input_stream<char> stderr();
  80     struct wait_exited {
  81         int exit_code;
  82     };
  83     struct wait_signaled {
  84         int terminating_signal;
  85     };
  86     using wait_status = std::variant<wait_exited, wait_signaled>;
  87     /// Wait until the child process exits or terminates
  88     ///
  89     /// \returns the exit status
  90     future<wait_status> wait();
  91     /// Stop the process using SIGTERM
  92     void terminate();
  93     /// Force the process to exit using SIGKILL
  94     void kill();
  95
  96 private:
  97     const pid_t _pid;
  98     file_desc _stdin;
  99     file_desc _stdout;
 100     file_desc _stderr;
 101
 102     friend future<process> spawn_process(const std::filesystem::path&,
 103                                          spawn_parameters);
 104     friend future<process> spawn_process(const std::filesystem::path&);
 105 };
 106 }