contrib/kyua/utils/process/child.hpp

   1 // Copyright 2010 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/child.hpp
  30 /// Spawning and manipulation of children processes.
  31 ///
  32 /// The child module provides a set of functions to spawn subprocesses with
  33 /// different settings, and the corresponding set of classes to interact with
  34 /// said subprocesses.  The interfaces to fork subprocesses are very simplified
  35 /// and only provide the minimum functionality required by the rest of the
  36 /// project.
  37 ///
  38 /// Be aware that the semantics of the fork and wait methods exposed by this
  39 /// module are slightly different from that of the native calls.  Any process
  40 /// spawned by fork here will be isolated in its own session; once any of
  41 /// such children processes is awaited for, its whole process group will be
  42 /// terminated.  This is the semantics we want in the above layers to ensure
  43 /// that test programs (and, for that matter, external utilities) do not leak
  44 /// subprocesses on the system.
  45
  46 #if !defined(UTILS_PROCESS_CHILD_HPP)
  47 #define UTILS_PROCESS_CHILD_HPP
  48
  49 #include "utils/process/child_fwd.hpp"
  50
  51 #include <istream>
  52 #include <memory>
  53 #include <stdexcept>
  54
  55 #include "utils/defs.hpp"
  56 #include "utils/fs/path_fwd.hpp"
  57 #include "utils/noncopyable.hpp"
  58 #include "utils/process/operations_fwd.hpp"
  59 #include "utils/process/status_fwd.hpp"
  60
  61 namespace utils {
  62 namespace process {
  63
  64
  65 namespace detail {
  66
  67 void report_error_and_abort(void) UTILS_NORETURN;
  68 void report_error_and_abort(const std::runtime_error&) UTILS_NORETURN;
  69
  70
  71 }  // namespace detail
  72
  73
  74 /// Child process spawner and controller.
  75 class child : noncopyable {
  76     struct impl;
  77
  78     /// Pointer to the shared internal implementation.
  79     std::auto_ptr< impl > _pimpl;
  80
  81     static std::auto_ptr< child > fork_capture_aux(void);
  82
  83     static std::auto_ptr< child > fork_files_aux(const fs::path&,
  84                                                  const fs::path&);
  85
  86     explicit child(impl *);
  87
  88 public:
  89     ~child(void);
  90
  91     template< typename Hook >
  92     static std::auto_ptr< child > fork_capture(Hook);
  93     std::istream& output(void);
  94
  95     template< typename Hook >
  96     static std::auto_ptr< child > fork_files(Hook, const fs::path&,
  97                                              const fs::path&);
  98
  99     static std::auto_ptr< child > spawn_capture(
 100         const fs::path&, const args_vector&);
 101     static std::auto_ptr< child > spawn_files(
 102         const fs::path&, const args_vector&, const fs::path&, const fs::path&);
 103
 104     int pid(void) const;
 105
 106     status wait(void);
 107 };
 108
 109
 110 }  // namespace process
 111 }  // namespace utils
 112
 113 #endif  // !defined(UTILS_PROCESS_CHILD_HPP)