subprocess.hpp

Go to the documentation of this file.

// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License

#ifndef __PROCESS_SUBPROCESS_HPP__
#define __PROCESS_SUBPROCESS_HPP__

#include <map>
#include <memory>
#include <string>
#include <vector>

#include <process/future.hpp>

#include <stout/flags.hpp>
#include <stout/lambda.hpp>
#include <stout/none.hpp>
#include <stout/option.hpp>
#include <stout/try.hpp>

#include <stout/os/exec.hpp>
#include <stout/os/shell.hpp>
#include <stout/os/int_fd.hpp>


namespace process {

class Subprocess
{
public:
  // Forward declarations.
  struct ParentHook;
  class ChildHook;

  class IO
  {
  public:
    struct InputFileDescriptors
    {
      int_fd read = -1;
      Option<int_fd> write = None();
    };

    struct OutputFileDescriptors
    {
      Option<int_fd> read = None();
      int_fd write = -1;
    };

    enum FDType {
      DUPLICATED,

      OWNED
    };


  private:
    friend class Subprocess;

    friend Try<Subprocess> subprocess(
        const std::string& path,
        std::vector<std::string> argv,
        const Subprocess::IO& in,
        const Subprocess::IO& out,
        const Subprocess::IO& err,
        const flags::FlagsBase* flags,
        const Option<std::map<std::string, std::string>>& environment,
        const Option<lambda::function<
            pid_t(const lambda::function<int()>&)>>& clone,
        const std::vector<Subprocess::ParentHook>& parent_hooks,
        const std::vector<Subprocess::ChildHook>& child_hooks,
        const std::vector<int_fd>& whitelist_fds);

    IO(const lambda::function<Try<InputFileDescriptors>()>& _input,
       const lambda::function<Try<OutputFileDescriptors>()>& _output)
      : input(_input),
        output(_output) {}

    lambda::function<Try<InputFileDescriptors>()> input;

    lambda::function<Try<OutputFileDescriptors>()> output;
  };

  struct ParentHook
  {
    ParentHook(const lambda::function<Try<Nothing>(pid_t)>& _parent_setup);

    const lambda::function<Try<Nothing>(pid_t)> parent_setup;

    friend class Subprocess;

#ifdef __WINDOWS__

    static ParentHook CREATE_JOB();
#endif // __WINDOWS__
  };

  class ChildHook
  {
  public:
    static ChildHook CHDIR(const std::string& working_directory);

    static ChildHook SETSID();

#ifndef __WINDOWS__

    static ChildHook DUP2(int oldFd, int newFd);
#endif // __WINDOWS__

    static ChildHook SUPERVISOR();

    Try<Nothing> operator()() const { return child_setup(); }

  private:
    ChildHook(const lambda::function<Try<Nothing>()>& _child_setup);

    const lambda::function<Try<Nothing>()> child_setup;
  };

  // Some syntactic sugar to create an IO::PIPE redirector.
  static IO PIPE();
  static IO PATH(const std::string& path);
  static IO FD(int_fd fd, IO::FDType type = IO::DUPLICATED);

  pid_t pid() const { return data->pid; }

  Option<int_fd> in() const
  {
    return data->in;
  }

  Option<int_fd> out() const
  {
    return data->out;
  }

  Option<int_fd> err() const
  {
    return data->err;
  }

  Future<Option<int>> status() const { return data->status; }

private:
  friend Try<Subprocess> subprocess(
      const std::string& path,
      std::vector<std::string> argv,
      const Subprocess::IO& in,
      const Subprocess::IO& out,
      const Subprocess::IO& err,
      const flags::FlagsBase* flags,
      const Option<std::map<std::string, std::string>>& environment,
      const Option<lambda::function<
          pid_t(const lambda::function<int()>&)>>& clone,
      const std::vector<Subprocess::ParentHook>& parent_hooks,
      const std::vector<Subprocess::ChildHook>& child_hooks,
      const std::vector<int_fd>& whitelist_fds);

  struct Data
  {
    ~Data()
    {
      if (in.isSome()) { os::close(in.get()); }
      if (out.isSome()) { os::close(out.get()); }
      if (err.isSome()) { os::close(err.get()); }
    }

    pid_t pid;

#ifdef __WINDOWS__
    Option<os::windows::internal::ProcessData> process_data;
#endif // __WINDOWS__

    // The parent side of the pipe for stdin/stdout/stderr. If the
    // IO mode is not a pipe, `None` will be stored.
    // NOTE: stdin, stdout, stderr are macros on some systems, hence
    // these names instead.
    Option<int_fd> in;
    Option<int_fd> out;
    Option<int_fd> err;

    Future<Option<int>> status;
  };

  Subprocess() : data(new Data()) {}

  std::shared_ptr<Data> data;
};

using InputFileDescriptors = Subprocess::IO::InputFileDescriptors;
using OutputFileDescriptors = Subprocess::IO::OutputFileDescriptors;

// TODO(jmlvanre): Consider removing default argument for
// `parent_hooks` to force the caller to think about setting them.
Try<Subprocess> subprocess(
    const std::string& path,
    std::vector<std::string> argv,
    const Subprocess::IO& in = Subprocess::FD(STDIN_FILENO),
    const Subprocess::IO& out = Subprocess::FD(STDOUT_FILENO),
    const Subprocess::IO& err = Subprocess::FD(STDERR_FILENO),
    const flags::FlagsBase* flags = nullptr,
    const Option<std::map<std::string, std::string>>& environment = None(),
    const Option<lambda::function<
        pid_t(const lambda::function<int()>&)>>& clone = None(),
    const std::vector<Subprocess::ParentHook>& parent_hooks = {},
    const std::vector<Subprocess::ChildHook>& child_hooks = {},
    const std::vector<int_fd>& whitelist_fds = {});


// TODO(jmlvanre): Consider removing default argument for
// `parent_hooks` to force the caller to think about setting them.
inline Try<Subprocess> subprocess(
    const std::string& command,
    const Subprocess::IO& in = Subprocess::FD(STDIN_FILENO),
    const Subprocess::IO& out = Subprocess::FD(STDOUT_FILENO),
    const Subprocess::IO& err = Subprocess::FD(STDERR_FILENO),
    const Option<std::map<std::string, std::string>>& environment = None(),
    const Option<lambda::function<
        pid_t(const lambda::function<int()>&)>>& clone = None(),
    const std::vector<Subprocess::ParentHook>& parent_hooks = {},
    const std::vector<Subprocess::ChildHook>& child_hooks = {},
    const std::vector<int_fd>& whitelist_fds = {})
{
  std::vector<std::string> argv = {os::Shell::arg0, os::Shell::arg1, command};

  return subprocess(
      os::Shell::name,
      argv,
      in,
      out,
      err,
      nullptr,
      environment,
      clone,
      parent_hooks,
      child_hooks,
      whitelist_fds);
}

} // namespace process {

#endif // __PROCESS_SUBPROCESS_HPP__