src/subprocess.h

// Copyright 2012 Google Inc. All Rights Reserved.
//
// 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 NINJA_SUBPROCESS_H_
#define NINJA_SUBPROCESS_H_

#include <memory>
#include <queue>
#include <string>
#include <vector>

#ifdef _WIN32
#include <windows.h>
#else
#include <signal.h>
#endif

#include "async_loop.h"
#include "exit_status.h"
#include "interrupt_handling.h"
#include "ipc_handle.h"

class EnvironmentBlock;

struct SubprocessSet;

/// Subprocess wraps a single async subprocess.  It is entirely
/// passive: it expects the caller to notify it when its fds are ready
/// for reading, as well as call Finish() to reap the child once done()
/// is true.
struct Subprocess {
  ~Subprocess();

  /// Returns ExitSuccess on successful process exit, ExitInterrupted if
  /// the process was interrupted, ExitFailure if it otherwise failed.
  /// Should only be called on an instance where Done() returns true.
  ExitStatus Finish();

  /// Return true if the a subprocess has completed. Only used for testing.
  bool Done() const;

  /// Retrieve buffered output (combined stdout/stderr) for a given
  /// subprocess. Will be empty for subprocesses belonging to the 'console'
  /// pool. Only call this when Done() returns true, or after a call to
  /// Finish().
  const std::string& GetOutput() const;

 private:
  Subprocess(SubprocessSet& subprocess_set, bool use_console);
  bool Start(const std::string& command);

  SubprocessSet& subprocess_set_;
  std::string buf_;

#ifdef _WIN32
  /// Set up pipe_ as the parent-side pipe of the subprocess; return the
  /// other end of the pipe, usable in the child process.
  HANDLE SetupPipe();

  IpcHandle child_;
  AsyncHandle pipe_;
  bool is_reading_ = false;
#else
  AsyncHandle async_fd_;
  pid_t pid_;
#endif
  bool use_console_;
  char read_buf_[4 << 10];

  void Stop();

  friend struct SubprocessSet;
};

/// SubprocessSet runs a ppoll/pselect() loop around a set of Subprocesses.
/// DoWork() waits for any state change in subprocesses; finished_
/// is a queue of subprocesses as they finish.
struct SubprocessSet {
  SubprocessSet();

  explicit SubprocessSet(const EnvironmentBlock& environment);

  ~SubprocessSet();

  /// Start a new subprocess, and return a pointer to the corresponding
  /// instance, which is still owned by the SubprocessSet.
  Subprocess* Add(const std::string& command, bool use_console = false);

  /// Wait for any subprocess to complete. Returns true if interrupted
  /// or false otherwise.
  bool DoWork();

  /// Return next finished process, or null if there is none.
  /// The returned instance must be destroyed before this SubprocessSet.
  std::unique_ptr<Subprocess> NextFinished();

  /// Remove all remaining processes forcibly.
  void Clear();

  std::vector<std::unique_ptr<Subprocess>> running_;
  std::queue<std::unique_ptr<Subprocess>> finished_;

 private:
  friend struct Subprocess;

  AsyncLoop& async_loop_;
  AsyncLoop::ScopedInterruptCatcher interrupt_catcher_;
  const EnvironmentBlock* environment_ = nullptr;

  // Called from an asynchronous callback when a subprocess completes.
  void OnProcessCompletion(Subprocess* subprocess);
};

#endif // NINJA_SUBPROCESS_H_