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