X-Git-Url: http://plrg.eecs.uci.edu/git/?p=folly.git;a=blobdiff_plain;f=folly%2FSubprocess.h;h=f1dd2ecd9b4548189b0db41a907e7c59dba9544a;hp=65842c870bf6225a5a9933dec68702d25a620930;hb=55af3d190b31e6b09943bb6456dc1085688fc007;hpb=546bd3f5f2ed1fdf3a0f5c2b6737a20c4bc2f561 diff --git a/folly/Subprocess.h b/folly/Subprocess.h index 65842c87..f1dd2ecd 100644 --- a/folly/Subprocess.h +++ b/folly/Subprocess.h @@ -1,5 +1,5 @@ /* - * Copyright 2014 Facebook, Inc. + * Copyright 2017 Facebook, Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -26,33 +26,72 @@ * output, and standard error to/from child descriptors in the parent, * or to create communication pipes between the child and the parent. * - * The simplest example is a thread-safe version of the system() library + * The simplest example is a thread-safe [1] version of the system() library * function: * Subprocess(cmd).wait(); * which executes the command using the default shell and waits for it * to complete, returning the exit status. * - * A thread-safe version of popen() (type="r", to read from the child): - * Subprocess proc(cmd, Subprocess::pipeStdout()); - * // read from proc.stdout() + * A thread-safe [1] version of popen() (type="r", to read from the child): + * Subprocess proc(cmd, Subprocess::Options().pipeStdout()); + * // read from proc.stdoutFd() * proc.wait(); * - * A thread-safe version of popen() (type="w", to write to the child): - * Subprocess proc(cmd, Subprocess::pipeStdin()); - * // write to proc.stdin() + * A thread-safe [1] version of popen() (type="w", to write to the child): + * Subprocess proc(cmd, Subprocess::Options().pipeStdin()); + * // write to proc.stdinFd() * proc.wait(); * - * If you want to redirect both stdin and stdout to pipes, you can, but - * note that you're subject to a variety of deadlocks. You'll want to use - * nonblocking I/O; look at the implementation of communicate() for an example. + * If you want to redirect both stdin and stdout to pipes, you can, but note + * that you're subject to a variety of deadlocks. You'll want to use + * nonblocking I/O, like the callback version of communicate(). * - * communicate() is a way to communicate to a child via its standard input, - * standard output, and standard error. It buffers everything in memory, - * so it's not great for large amounts of data (or long-running processes), - * but it insulates you from the deadlocks mentioned above. + * The string or IOBuf-based variants of communicate() are the simplest way + * to communicate with a child via its standard input, standard output, and + * standard error. They buffer everything in memory, so they are not great + * for large amounts of data (or long-running processes), but they are much + * simpler than the callback version. + * + * == A note on thread-safety == + * + * [1] "thread-safe" refers ONLY to the fact that Subprocess is very careful + * to fork in a way that does not cause grief in multithreaded programs. + * + * Caveat: If your system does not have the atomic pipe2 system call, it is + * not safe to concurrently call Subprocess from different threads. + * Therefore, it is best to have a single thread be responsible for spawning + * subprocesses. + * + * A particular instances of Subprocess is emphatically **not** thread-safe. + * If you need to simultaneously communicate via the pipes, and interact + * with the Subprocess state, your best bet is to: + * - takeOwnershipOfPipes() to separate the pipe I/O from the subprocess. + * - Only interact with the Subprocess from one thread at a time. + * + * The current implementation of communicate() cannot be safely interrupted. + * To do so correctly, one would need to use EventFD, or open a dedicated + * pipe to be messaged from a different thread -- in particular, kill() will + * not do, since a descendant may keep the pipes open indefinitely. + * + * So, once you call communicate(), you must wait for it to return, and not + * touch the pipes from other threads. closeParentFd() is emphatically + * unsafe to call concurrently, and even sendSignal() is not a good idea. + * You can perhaps give the Subprocess's PID to a different thread before + * starting communicate(), and use that PID to send a signal without + * accessing the Subprocess object. In that case, you will need a mutex + * that ensures you don't wait() before you sent said signal. In a + * nutshell, don't do this. + * + * In fact, signals are inherently concurrency-unsafe on Unix: if you signal + * a PID, while another thread is in waitpid(), the signal may fire either + * before or after the process is reaped. This means that your signal can, + * in pathological circumstances, be delivered to the wrong process (ouch!). + * To avoid this, you should only use non-blocking waits (i.e. poll()), and + * make sure to serialize your signals (i.e. kill()) with the waits -- + * either wait & signal from the same thread, or use a mutex. */ -#ifndef FOLLY_SUBPROCESS_H_ -#define FOLLY_SUBPROCESS_H_ + +#pragma once #include #include @@ -67,15 +106,18 @@ #include #include -#include -#include +#include +#include #include -#include -#include +#include #include +#include #include #include +#include +#include +#include namespace folly { @@ -87,12 +129,26 @@ class ProcessReturnCode { friend class Subprocess; public: enum State { + // Subprocess starts in the constructor, so this state designates only + // default-initialized or moved-out ProcessReturnCodes. NOT_STARTED, RUNNING, EXITED, KILLED }; + // Default-initialized for convenience. Subprocess::returnCode() will + // never produce this value. + ProcessReturnCode() : ProcessReturnCode(RV_NOT_STARTED) {} + + // Trivially copyable + ProcessReturnCode(const ProcessReturnCode& p) = default; + ProcessReturnCode& operator=(const ProcessReturnCode& p) = default; + // Non-default move: In order for Subprocess to be movable, the "moved + // out" state must not be "running", or ~Subprocess() will abort. + ProcessReturnCode(ProcessReturnCode&& p) noexcept; + ProcessReturnCode& operator=(ProcessReturnCode&& p) noexcept; + /** * Process state. One of: * NOT_STARTED: process hasn't been started successfully @@ -161,8 +217,8 @@ class SubprocessError : public std::exception {}; class CalledProcessError : public SubprocessError { public: explicit CalledProcessError(ProcessReturnCode rc); - ~CalledProcessError() throw() { } - const char* what() const throw() FOLLY_OVERRIDE { return what_.c_str(); } + ~CalledProcessError() throw() override = default; + const char* what() const throw() override { return what_.c_str(); } ProcessReturnCode returnCode() const { return returnCode_; } private: ProcessReturnCode returnCode_; @@ -175,8 +231,8 @@ class CalledProcessError : public SubprocessError { class SubprocessSpawnError : public SubprocessError { public: SubprocessSpawnError(const char* executable, int errCode, int errnoValue); - ~SubprocessSpawnError() throw() {} - const char* what() const throw() FOLLY_OVERRIDE { return what_.c_str(); } + ~SubprocessSpawnError() throw() override = default; + const char* what() const throw() override { return what_.c_str(); } int errnoValue() const { return errnoValue_; } private: @@ -187,13 +243,30 @@ class SubprocessSpawnError : public SubprocessError { /** * Subprocess. */ -class Subprocess : private boost::noncopyable { +class Subprocess { public: static const int CLOSE = -1; static const int PIPE = -2; static const int PIPE_IN = -3; static const int PIPE_OUT = -4; + /** + * See Subprocess::Options::dangerousPostForkPreExecCallback() for usage. + * Every derived class should include the following warning: + * + * DANGER: This class runs after fork in a child processes. Be fast, the + * parent thread is waiting, but remember that other parent threads are + * running and may mutate your state. Avoid mutating any data belonging to + * the parent. Avoid interacting with non-POD data that originated in the + * parent. Avoid any libraries that may internally reference non-POD data. + * Especially beware parent mutexes -- for example, glog's LOG() uses one. + */ + struct DangerousPostForkPreExecCallback { + virtual ~DangerousPostForkPreExecCallback() {} + // This must return 0 on success, or an `errno` error code. + virtual int operator()() = 0; + }; + /** * Class representing various options: file descriptor behavior, and * whether to use $PATH for searching for the executable, @@ -202,13 +275,10 @@ class Subprocess : private boost::noncopyable { * the close-on-exec flag is set (fcntl FD_CLOEXEC) and inherited * otherwise. */ - class Options : private boost::orable { + class Options { friend class Subprocess; public: - Options() - : closeOtherFds_(false), - usePath_(false) { - } + Options() {} // E.g. https://gcc.gnu.org/bugzilla/show_bug.cgi?id=58328 /** * Change action for file descriptor fd. @@ -229,19 +299,19 @@ class Subprocess : private boost::noncopyable { /** * Shortcut to change the action for standard input. */ - Options& stdin(int action) { return fd(STDIN_FILENO, action); } + Options& stdinFd(int action) { return fd(STDIN_FILENO, action); } /** * Shortcut to change the action for standard output. */ - Options& stdout(int action) { return fd(STDOUT_FILENO, action); } + Options& stdoutFd(int action) { return fd(STDOUT_FILENO, action); } /** * Shortcut to change the action for standard error. * Note that stderr(1) will redirect the standard error to the same * file descriptor as standard output; the equivalent of bash's "2>&1" */ - Options& stderr(int action) { return fd(STDERR_FILENO, action); } + Options& stderrFd(int action) { return fd(STDERR_FILENO, action); } Options& pipeStdin() { return fd(STDIN_FILENO, PIPE_IN); } Options& pipeStdout() { return fd(STDOUT_FILENO, PIPE_OUT); } @@ -282,24 +352,107 @@ class Subprocess : private boost::noncopyable { #endif /** - * Helpful way to combine Options. + * Child will be made a process group leader when it starts. Upside: one + * can reliably all its kill non-daemonizing descendants. Downside: the + * child will not receive Ctrl-C etc during interactive use. + */ + Options& processGroupLeader() { + processGroupLeader_ = true; + return *this; + } + + /** + * *** READ THIS WHOLE DOCBLOCK BEFORE USING *** + * + * Run this callback in the child after the fork, just before the + * exec(), and after the child's state has been completely set up: + * - signal handlers have been reset to default handling and unblocked + * - the working directory was set + * - closed any file descriptors specified via Options() + * - set child process flags (see code) + * + * This is EXTREMELY DANGEROUS. For example, this innocuous-looking code + * can cause a fraction of your Subprocess launches to hang forever: + * + * LOG(INFO) << "Hello from the child"; + * + * The reason is that glog has an internal mutex. If your fork() happens + * when the parent has the mutex locked, the child will wait forever. + * + * == GUIDELINES == + * + * - Be quick -- the parent thread is blocked until you exit. + * - Remember that other parent threads are running, and may mutate your + * state. + * - Avoid mutating any data belonging to the parent. + * - Avoid interacting with non-POD data that came from the parent. + * - Avoid any libraries that may internally reference non-POD state. + * - Especially beware parent mutexes, e.g. LOG() uses a global mutex. + * - Avoid invoking the parent's destructors (you can accidentally + * delete files, terminate network connections, etc). + * - Read http://ewontfix.com/7/ + */ + Options& dangerousPostForkPreExecCallback( + DangerousPostForkPreExecCallback* cob) { + dangerousPostForkPreExecCallback_ = cob; + return *this; + } + +#if __linux__ + /** + * This is an experimental feature, it is best you don't use it at this + * point of time. + * Although folly would support cloning with custom flags in some form, this + * API might change in the near future. So use the following assuming it is + * experimental. (Apr 11, 2017) + * + * This unlocks Subprocess to support clone flags, many of them need + * CAP_SYS_ADMIN permissions. It might also require you to go through the + * implementation to understand what happens before, between and after the + * fork-and-exec. + * + * `man 2 clone` would be a starting point for knowing about the available + * flags. */ - Options& operator|=(const Options& other); + using clone_flags_t = uint64_t; + Options& useCloneWithFlags(clone_flags_t cloneFlags) noexcept { + cloneFlags_ = cloneFlags; + return *this; + } +#endif private: typedef boost::container::flat_map FdMap; FdMap fdActions_; - bool closeOtherFds_; - bool usePath_; + bool closeOtherFds_{false}; + bool usePath_{false}; std::string childDir_; // "" keeps the parent's working directory #if __linux__ int parentDeathSignal_{0}; +#endif + bool processGroupLeader_{false}; + DangerousPostForkPreExecCallback* + dangerousPostForkPreExecCallback_{nullptr}; +#if __linux__ + // none means `vfork()` instead of a custom `clone()` + // Optional<> is used because value of '0' means do clone without any flags. + Optional cloneFlags_; #endif }; - static Options pipeStdin() { return Options().stdin(PIPE); } - static Options pipeStdout() { return Options().stdout(PIPE); } - static Options pipeStderr() { return Options().stderr(PIPE); } + // Non-copiable, but movable + Subprocess(const Subprocess&) = delete; + Subprocess& operator=(const Subprocess&) = delete; + Subprocess(Subprocess&&) = default; + Subprocess& operator=(Subprocess&&) = default; + + /** + * Create an uninitialized subprocess. + * + * In this state it can only be destroyed, or assigned to using the move + * assignment operator. + */ + Subprocess(); /** * Create a subprocess from the given arguments. argv[0] must be listed. @@ -323,11 +476,75 @@ class Subprocess : private boost::noncopyable { * The shell to use is taken from the environment variable $SHELL, * or /bin/sh if $SHELL is unset. */ + FOLLY_DEPRECATED("Prefer not running in a shell or use `shellify`.") explicit Subprocess( const std::string& cmd, const Options& options = Options(), const std::vector* env = nullptr); + //// + //// The methods below only manipulate the process state, and do not + //// affect its communication pipes. + //// + + /** + * Return the child's pid, or -1 if the child wasn't successfully spawned + * or has already been wait()ed upon. + */ + pid_t pid() const; + + /** + * Return the child's status (as per wait()) if the process has already + * been waited on, -1 if the process is still running, or -2 if the + * process hasn't been successfully started. NOTE that this does not call + * waitpid() or Subprocess::poll(), but simply returns the status stored + * in the Subprocess object. + */ + ProcessReturnCode returnCode() const { return returnCode_; } + + /** + * Poll the child's status and return it. Return the exit status if the + * subprocess had quit, or RUNNING otherwise. Throws an std::logic_error + * if called on a Subprocess whose status is no longer RUNNING. No other + * exceptions are possible. Aborts on egregious violations of contract, + * e.g. if you wait for the underlying process without going through this + * Subprocess instance. + */ + ProcessReturnCode poll(struct rusage* ru = nullptr); + + /** + * Poll the child's status. If the process is still running, return false. + * Otherwise, return true if the process exited with status 0 (success), + * or throw CalledProcessError if the process exited with a non-zero status. + */ + bool pollChecked(); + + /** + * Wait for the process to terminate and return its status. Like poll(), + * the only exception this can throw is std::logic_error if you call this + * on a Subprocess whose status is RUNNING. Aborts on egregious + * violations of contract, like an out-of-band waitpid(p.pid(), 0, 0). + */ + ProcessReturnCode wait(); + + /** + * Wait for the process to terminate, throw if unsuccessful. + */ + void waitChecked(); + + /** + * Send a signal to the child. Shortcuts for the commonly used Unix + * signals are below. + */ + void sendSignal(int signal); + void terminate() { sendSignal(SIGTERM); } + void kill() { sendSignal(SIGKILL); } + + //// + //// The methods below only affect the process's communication pipes, but + //// not its return code or state (they do not poll() or wait()). + //// + /** * Communicate with the child until all pipes to/from the child are closed. * @@ -362,6 +579,8 @@ class Subprocess : private boost::noncopyable { /** * Communicate with the child until all pipes to/from the child are closed. * + * == Semantics == + * * readCallback(pfd, cfd) will be called whenever there's data available * on any pipe *from* the child (PIPE_OUT). pfd is the file descriptor * in the parent (that you use to read from); cfd is the file descriptor @@ -379,27 +598,52 @@ class Subprocess : private boost::noncopyable { * child, or make its writes fail with EPIPE, so you should generally * avoid returning true unless you've reached end-of-file. * - * NOTE that you MUST consume all data passed to readCallback (or return - * true to close the pipe). Similarly, you MUST write to a writable pipe - * (or return true to close the pipe). To do otherwise is an error that - * can result in a deadlock. You must do this even for pipes you are not + * communicate() returns when all pipes to/from the child are closed; the + * child might stay alive after that, so you must still wait(). + * Conversely, the child may quit long before its pipes are closed, since + * its descendants can keep them alive forever. + * + * Most users won't need to use this callback version; the simpler version + * of communicate (which buffers data in memory) will probably work fine. + * + * == Things you must get correct == + * + * 1) You MUST consume all data passed to readCallback (or return true to + * close the pipe). Similarly, you MUST write to a writable pipe (or + * return true to close the pipe). To do otherwise is an error that can + * result in a deadlock. You must do this even for pipes you are not * interested in. * - * Note that pfd is nonblocking, so be prepared for read() / write() to - * return -1 and set errno to EAGAIN (in which case you should return - * false). Use readNoInt() from FileUtil.h to handle interrupted reads - * for you + * 2) pfd is nonblocking, so be prepared for read() / write() to return -1 + * and set errno to EAGAIN (in which case you should return false). Use + * readNoInt() from FileUtil.h to handle interrupted reads for you. * - * Note that communicate() returns when all pipes to/from the child are - * closed; the child might stay alive after that, so you must still wait(). + * 3) Your callbacks MUST NOT call any of the Subprocess methods that + * manipulate the pipe FDs. Check the docblocks, but, for example, + * neither closeParentFd (return true instead) nor takeOwnershipOfPipes + * are safe. Stick to reading/writing from pfd, as appropriate. * - * Most users won't need to use this; the simpler version of communicate - * (which buffers data in memory) will probably work fine. + * == Good to know == * - * See ReadLinesCallback for an easy way to consume the child's output + * 1) See ReadLinesCallback for an easy way to consume the child's output * streams line-by-line (or tokenized by another delimiter). + * + * 2) "Wait until the descendants close the pipes" is usually the behavior + * you want, since the descendants may have something to say even if the + * immediate child is dead. If you need to be able to force-close all + * parent FDs, communicate() will NOT work for you. Do it your own way by + * using takeOwnershipOfPipes(). + * + * Why not? You can return "true" from your callbacks to sever active + * pipes, but inactive ones can remain open indefinitely. It is + * impossible to safely close inactive pipes while another thread is + * blocked in communicate(). This is BY DESIGN. Racing communicate()'s + * read/write callbacks can result in wrong I/O and data corruption. This + * class would need internal synchronization and timeouts, a poor and + * expensive implementation choice, in order to make closeParentFd() + * thread-safe. */ - typedef std::function FdCallback; + using FdCallback = folly::Function; void communicate(FdCallback readCallback, FdCallback writeCallback); /** @@ -408,17 +652,13 @@ class Subprocess : private boost::noncopyable { * descriptors. Use the readLinesCallback() helper to get template * deduction. For example: * - * auto read_cb = Subprocess::readLinesCallback( - * [](int fd, folly::StringPiece s) { - * std::cout << fd << " said: " << s; - * return false; // Keep reading from the child - * } - * ); * subprocess.communicate( - * // ReadLinesCallback contains StreamSplitter contains IOBuf, making - * // it noncopyable, whereas std::function must be copyable. So, we - * // keep the callback in a local, and instead pass a reference. - * std::ref(read_cb), + * Subprocess::readLinesCallback( + * [](int fd, folly::StringPiece s) { + * std::cout << fd << " said: " << s; + * return false; // Keep reading from the child + * } + * ), * [](int pdf, int cfd){ return true; } // Don't write to the child * ); * @@ -451,7 +691,7 @@ class Subprocess : private boost::noncopyable { uint64_t maxLineLength = 0, // No line length limit by default char delimiter = '\n', uint64_t bufSize = 1024 - ) : fdLineCb_(std::move(fdLineCb)), + ) : fdLineCb_(std::forward(fdLineCb)), maxLineLength_(maxLineLength), delimiter_(delimiter), bufSize_(bufSize) {} @@ -470,6 +710,7 @@ class Subprocess : private boost::noncopyable { if (ret == -1 && errno == EAGAIN) { // No more data for now return false; } + checkUnixError(ret, "read"); if (ret == 0) { // Reached end-of-file splitter.flush(); // Ignore return since the file is over anyway return true; @@ -491,72 +732,50 @@ class Subprocess : private boost::noncopyable { // Helper to enable template deduction template - static ReadLinesCallback readLinesCallback( + static auto readLinesCallback( Callback&& fdLineCb, - uint64_t maxLineLength = 0, // No line length limit by default + uint64_t maxLineLength = 0, // No line length limit by default char delimiter = '\n', - uint64_t bufSize = 1024) { - return ReadLinesCallback( - std::move(fdLineCb), maxLineLength, delimiter, bufSize - ); + uint64_t bufSize = 1024) + -> ReadLinesCallback::type> { + return ReadLinesCallback::type>( + std::forward(fdLineCb), maxLineLength, delimiter, bufSize); } /** - * Enable notifications (callbacks) for one pipe to/from child. By default, - * all are enabled. Useful for "chatty" communication -- you want to disable - * write callbacks until you receive the expected message. + * communicate() callbacks can use this to temporarily enable/disable + * notifications (callbacks) for a pipe to/from the child. By default, + * all are enabled. Useful for "chatty" communication -- you want to + * disable write callbacks until you receive the expected message. + * + * Disabling a pipe does not free you from the requirement to consume all + * incoming data. Failing to do so will easily create deadlock bugs. + * + * Throws if the childFd is not known. */ void enableNotifications(int childFd, bool enabled); /** - * Are notifications for one pipe to/from child enabled? + * Are notifications for one pipe to/from child enabled? Throws if the + * childFd is not known. */ bool notificationsEnabled(int childFd) const; - /** - * Return the child's pid, or -1 if the child wasn't successfully spawned - * or has already been wait()ed upon. - */ - pid_t pid() const; - - /** - * Return the child's status (as per wait()) if the process has already - * been waited on, -1 if the process is still running, or -2 if the process - * hasn't been successfully started. NOTE that this does not poll, but - * returns the status stored in the Subprocess object. - */ - ProcessReturnCode returnCode() const { return returnCode_; } - - /** - * Poll the child's status and return it, return -1 if the process - * is still running. NOTE that it is illegal to call poll again after - * poll indicated that the process has terminated, or to call poll on a - * process that hasn't been successfully started (the constructor threw an - * exception). - */ - ProcessReturnCode poll(); - - /** - * Poll the child's status. If the process is still running, return false. - * Otherwise, return true if the process exited with status 0 (success), - * or throw CalledProcessError if the process exited with a non-zero status. - */ - bool pollChecked(); - - /** - * Wait for the process to terminate and return its status. - * Similarly to poll, it is illegal to call wait after the process - * has already been reaped or if the process has not successfully started. - */ - ProcessReturnCode wait(); + //// + //// The following methods are meant for the cases when communicate() is + //// not suitable. You should not need them when you call communicate(), + //// and, in fact, it is INHERENTLY UNSAFE to use closeParentFd() or + //// takeOwnershipOfPipes() from a communicate() callback. + //// /** - * Wait for the process to terminate, throw if unsuccessful. + * Close the parent file descriptor given a file descriptor in the child. + * DO NOT USE from communicate() callbacks; make them return true instead. */ - void waitChecked(); + void closeParentFd(int childFd); /** - * Set all pipes from / to child non-blocking. communicate() does + * Set all pipes from / to child to be non-blocking. communicate() does * this for you. */ void setAllNonBlocking(); @@ -564,27 +783,34 @@ class Subprocess : private boost::noncopyable { /** * Get parent file descriptor corresponding to the given file descriptor * in the child. Throws if childFd isn't a pipe (PIPE_IN / PIPE_OUT). - * Do not close() the return file descriptor; use closeParentFd, below. + * Do not close() the returned file descriptor; use closeParentFd, above. */ int parentFd(int childFd) const { - return pipes_[findByChildFd(childFd)].parentFd; + return pipes_[findByChildFd(childFd)].pipe.fd(); } - int stdin() const { return parentFd(0); } - int stdout() const { return parentFd(1); } - int stderr() const { return parentFd(2); } + int stdinFd() const { return parentFd(0); } + int stdoutFd() const { return parentFd(1); } + int stderrFd() const { return parentFd(2); } /** - * Close the parent file descriptor given a file descriptor in the child. - */ - void closeParentFd(int childFd); - - /** - * Send a signal to the child. Shortcuts for the commonly used Unix - * signals are below. + * The child's pipes are logically separate from the process metadata + * (they may even be kept alive by the child's descendants). This call + * lets you manage the pipes' lifetime separetely from the lifetime of the + * child process. + * + * After this call, the Subprocess instance will have no knowledge of + * these pipes, and the caller assumes responsibility for managing their + * lifetimes. Pro-tip: prefer to explicitly close() the pipes, since + * folly::File would otherwise silently suppress I/O errors. + * + * No, you may NOT call this from a communicate() callback. */ - void sendSignal(int signal); - void terminate() { sendSignal(SIGTERM); } - void kill() { sendSignal(SIGKILL); } + struct ChildPipe { + ChildPipe(int fd, folly::File&& ppe) : childFd(fd), pipe(std::move(ppe)) {} + int childFd; + folly::File pipe; // Owns the parent FD + }; + std::vector takeOwnershipOfPipes(); private: static const int RV_RUNNING = ProcessReturnCode::RV_RUNNING; @@ -621,48 +847,39 @@ class Subprocess : private boost::noncopyable { */ void readChildErrorPipe(int pfd, const char* executable); - /** - * Close all file descriptors. - */ - void closeAll(); + // Returns an index into pipes_. Throws std::invalid_argument if not found. + size_t findByChildFd(const int childFd) const; - // return index in pipes_ - int findByChildFd(int childFd) const; + pid_t pid_{-1}; + ProcessReturnCode returnCode_{RV_NOT_STARTED}; - pid_t pid_; - ProcessReturnCode returnCode_; + /** + * Represents a pipe between this process, and the child process (or its + * descendant). To interact with these pipes, you can use communicate(), + * or use parentFd() and related methods, or separate them from the + * Subprocess instance entirely via takeOwnershipOfPipes(). + */ + struct Pipe : private boost::totally_ordered { + folly::File pipe; // Our end of the pipe, wrapped in a File to auto-close. + int childFd = -1; // Identifies the pipe: what FD is this in the child? + int direction = PIPE_IN; // one of PIPE_IN / PIPE_OUT + bool enabled = true; // Are notifications enabled in communicate()? - // The number of pipes between parent and child is assumed to be small, - // so we're happy with a vector here, even if it means linear erase. - // sorted by childFd - struct PipeInfo : private boost::totally_ordered { - int parentFd = -1; - int childFd = -1; - int direction = PIPE_IN; // one of PIPE_IN / PIPE_OUT - bool enabled = true; - - bool operator<(const PipeInfo& other) const { + bool operator<(const Pipe& other) const { return childFd < other.childFd; } - bool operator==(const PipeInfo& other) const { + bool operator==(const Pipe& other) const { return childFd == other.childFd; } }; - std::vector pipes_; -}; -inline Subprocess::Options& Subprocess::Options::operator|=( - const Subprocess::Options& other) { - if (this == &other) return *this; - // Replace - for (auto& p : other.fdActions_) { - fdActions_[p.first] = p.second; - } - closeOtherFds_ |= other.closeOtherFds_; - usePath_ |= other.usePath_; - return *this; -} + // Populated at process start according to fdActions, empty after + // takeOwnershipOfPipes(). Sorted by childFd. Can only have elements + // erased, but not inserted, after being populated. + // + // The number of pipes between parent and child is assumed to be small, + // so we're happy with a vector here, even if it means linear erase. + std::vector pipes_; +}; } // namespace folly - -#endif /* FOLLY_SUBPROCESS_H_ */