1 // Copyright 2015 The Kyua Authors. 2 // All rights reserved. 3 // 4 // Redistribution and use in source and binary forms, with or without 5 // modification, are permitted provided that the following conditions are 6 // met: 7 // 8 // * Redistributions of source code must retain the above copyright 9 // notice, this list of conditions and the following disclaimer. 10 // * Redistributions in binary form must reproduce the above copyright 11 // notice, this list of conditions and the following disclaimer in the 12 // documentation and/or other materials provided with the distribution. 13 // * Neither the name of Google Inc. nor the names of its contributors 14 // may be used to endorse or promote products derived from this software 15 // without specific prior written permission. 16 // 17 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 20 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 21 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 22 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 23 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 27 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28 29 /// \file utils/process/executor.hpp 30 /// Multiprogrammed process executor with isolation guarantees. 31 /// 32 /// This module provides a mechanism to invoke more than one process 33 /// concurrently while at the same time ensuring that each process is run 34 /// in a clean container and in a "safe" work directory that gets cleaned 35 /// up automatically on termination. 36 /// 37 /// The intended workflow for using this module is the following: 38 /// 39 /// 1) Initialize the executor using setup(). Keep the returned object 40 /// around through the lifetime of the next operations. Only one 41 /// instance of the executor can be alive at once. 42 /// 2) Spawn one or more processes with spawn(). On the caller side, keep 43 /// track of any per-process data you may need using the returned 44 /// exec_handle, which is unique among the set of active processes. 45 /// 3) Call wait() or wait_any() to wait for completion of a process started 46 /// in the previous step. Repeat as desired. 47 /// 4) Use the returned exit_handle object by wait() or wait_any() to query 48 /// the status of the terminated process and/or to access any of its 49 /// data files. 50 /// 5) Invoke cleanup() on the exit_handle to wipe any stale data. 51 /// 6) Invoke cleanup() on the object returned by setup(). 52 /// 53 /// It is the responsibility of the caller to ensure that calls to 54 /// spawn() and spawn_followup() are balanced with wait() and wait_any() calls. 55 /// 56 /// Processes executed in this manner have access to two different "unique" 57 /// directories: the first is the "work directory", which is an empty directory 58 /// that acts as the subprocess' work directory; the second is the "control 59 /// directory", which is the location where the in-process code may place files 60 /// that are not clobbered by activities in the work directory. 61 62 #if !defined(UTILS_PROCESS_EXECUTOR_HPP) 63 #define UTILS_PROCESS_EXECUTOR_HPP 64 65 #include "utils/process/executor_fwd.hpp" 66 67 #include <cstddef> 68 #include <memory> 69 70 #include "utils/datetime_fwd.hpp" 71 #include "utils/fs/path_fwd.hpp" 72 #include "utils/optional.hpp" 73 #include "utils/passwd_fwd.hpp" 74 #include "utils/process/child_fwd.hpp" 75 #include "utils/process/status_fwd.hpp" 76 77 namespace utils { 78 namespace process { 79 namespace executor { 80 81 82 namespace detail { 83 84 85 extern const char* stdout_name; 86 extern const char* stderr_name; 87 extern const char* work_subdir; 88 89 90 /// Shared reference counter. 91 typedef std::shared_ptr< std::size_t > refcnt_t; 92 93 94 void setup_child(const utils::optional< utils::passwd::user >, 95 const utils::fs::path&, const utils::fs::path&); 96 97 98 } // namespace detail 99 100 101 /// Maintenance data held while a subprocess is being executed. 102 /// 103 /// This data structure exists from the moment a subprocess is executed via 104 /// executor::spawn() to when it is cleaned up with exit_handle::cleanup(). 105 /// 106 /// The caller NEED NOT maintain this object alive for the execution of the 107 /// subprocess. However, the PID contained in here can be used to match 108 /// exec_handle objects with corresponding exit_handle objects via their 109 /// original_pid() method. 110 /// 111 /// Objects of this type can be copied around but their implementation is 112 /// shared. The implication of this is that only the last copy of a given exit 113 /// handle will execute the automatic cleanup() on destruction. 114 class exec_handle { 115 struct impl; 116 117 /// Pointer to internal implementation. 118 std::shared_ptr< impl > _pimpl; 119 120 friend class executor_handle; 121 exec_handle(std::shared_ptr< impl >); 122 123 public: 124 ~exec_handle(void); 125 126 int pid(void) const; 127 utils::fs::path control_directory(void) const; 128 utils::fs::path work_directory(void) const; 129 const utils::fs::path& stdout_file(void) const; 130 const utils::fs::path& stderr_file(void) const; 131 }; 132 133 134 /// Container for the data of a process termination. 135 /// 136 /// This handle provides access to the details of the process that terminated 137 /// and serves as the owner of the remaining on-disk files. The caller is 138 /// expected to call cleanup() before destruction to remove the on-disk state. 139 /// 140 /// Objects of this type can be copied around but their implementation is 141 /// shared. The implication of this is that only the last copy of a given exit 142 /// handle will execute the automatic cleanup() on destruction. 143 class exit_handle { 144 struct impl; 145 146 /// Pointer to internal implementation. 147 std::shared_ptr< impl > _pimpl; 148 149 friend class executor_handle; 150 exit_handle(std::shared_ptr< impl >); 151 152 detail::refcnt_t state_owners(void) const; 153 154 public: 155 ~exit_handle(void); 156 157 void cleanup(void); 158 159 int original_pid(void) const; 160 const utils::optional< utils::process::status >& status(void) const; 161 const utils::optional< utils::passwd::user >& unprivileged_user(void) const; 162 const utils::datetime::timestamp& start_time() const; 163 const utils::datetime::timestamp& end_time() const; 164 utils::fs::path control_directory(void) const; 165 utils::fs::path work_directory(void) const; 166 const utils::fs::path& stdout_file(void) const; 167 const utils::fs::path& stderr_file(void) const; 168 }; 169 170 171 /// Handler for the livelihood of the executor. 172 /// 173 /// Objects of this type can be copied around (because we do not have move 174 /// semantics...) but their implementation is shared. Only one instance of the 175 /// executor can exist at any point in time. 176 class executor_handle { 177 struct impl; 178 /// Pointer to internal implementation. 179 std::shared_ptr< impl > _pimpl; 180 181 friend executor_handle setup(void); 182 executor_handle(void) throw(); 183 184 utils::fs::path spawn_pre(void); 185 exec_handle spawn_post(const utils::fs::path&, 186 const utils::fs::path&, 187 const utils::fs::path&, 188 const utils::datetime::delta&, 189 const utils::optional< utils::passwd::user >, 190 std::auto_ptr< utils::process::child >); 191 192 void spawn_followup_pre(void); 193 exec_handle spawn_followup_post(const exit_handle&, 194 const utils::datetime::delta&, 195 std::auto_ptr< utils::process::child >); 196 197 public: 198 ~executor_handle(void); 199 200 const utils::fs::path& root_work_directory(void) const; 201 202 void cleanup(void); 203 204 template< class Hook > 205 exec_handle spawn(Hook, 206 const datetime::delta&, 207 const utils::optional< utils::passwd::user >, 208 const utils::optional< utils::fs::path > = utils::none, 209 const utils::optional< utils::fs::path > = utils::none); 210 211 template< class Hook > 212 exec_handle spawn_followup(Hook, 213 const exit_handle&, 214 const datetime::delta&); 215 216 exit_handle wait(const exec_handle); 217 exit_handle wait_any(void); 218 219 void check_interrupt(void) const; 220 }; 221 222 223 executor_handle setup(void); 224 225 226 } // namespace executor 227 } // namespace process 228 } // namespace utils 229 230 231 #endif // !defined(UTILS_PROCESS_EXECUTOR_HPP) 232