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 77namespace utils { 78namespace process { 79namespace executor { 80 81 82namespace detail { 83 84 85extern const char* stdout_name; 86extern const char* stderr_name; 87extern const char* work_subdir; 88 89 90/// Shared reference counter. 91typedef std::shared_ptr< std::size_t > refcnt_t; 92 93 94void 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. 114class 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 123public: 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. 143class 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 154public: 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. 176class 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 197public: 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 223executor_handle setup(void); 224 225 226} // namespace executor 227} // namespace process 228} // namespace utils 229 230 231#endif // !defined(UTILS_PROCESS_EXECUTOR_HPP) 232