This is an automated email from the ASF dual-hosted git repository. bmahler pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/mesos.git
commit 9befebac5f054657686c9a6490603afe9b7f8ce1 Author: Benjamin Mahler <[email protected]> AuthorDate: Thu Apr 30 16:08:59 2020 -0400 Moved documentation into os/exec.hpp interface. The os/exec.hpp wrapper provides a single place to read the interface and documentation for both POSIX and Windows, this makes it easier for us to document the interface and OS differences that a caller needs to know about in one place. Review: https://reviews.apache.org/r/72303/ --- 3rdparty/stout/include/stout/os/exec.hpp | 91 ++++++++++++++++++++++++ 3rdparty/stout/include/stout/os/posix/exec.hpp | 13 ---- 3rdparty/stout/include/stout/os/windows/exec.hpp | 9 --- 3 files changed, 91 insertions(+), 22 deletions(-) diff --git a/3rdparty/stout/include/stout/os/exec.hpp b/3rdparty/stout/include/stout/os/exec.hpp index 4ad130b..686e7a1 100644 --- a/3rdparty/stout/include/stout/os/exec.hpp +++ b/3rdparty/stout/include/stout/os/exec.hpp @@ -21,4 +21,95 @@ #include <stout/os/posix/exec.hpp> #endif // __WINDOWS__ +namespace os { + +// Forks a subprocess and executes the provided file with the provided +// arguments. +// +// Blocks until the subprocess terminates and returns the exit code of +// the subprocess, or `None` if an error occurred (e.g., fork / exec / +// waitpid or the Windows equivalents failed). +// +// POSIX: this function is async signal safe. We return an +// `Option<int>` instead of a `Try<int>`, because although `Try` +// does not dynamically allocate, `Error` uses `std::string`, +// which is not async signal safe. +// +// Windows: Note that on Windows, processes are started using +// a string command line, and each process does its own parsing +// of that command line into arguments. This function will quote +// and escape the arguments compatible with any programs that +// use `CommandLineToArgvW` (this is the most common way, and any +// programs that use libc-style main with an arguments array will +// use this under the covers). However, some programs, notably +// cmd.exe have their own approach for parsing quotes / arguments +// that are not compatible with CommandLineToArgvW, and therefore +// should not be used with this function! +// +// TODO(bmahler): Add a windows only overload that takes a single +// string command line (to support cmd.exe and others with non- +// CommandLineToArgvW parsing). See MESOS-10093. +inline Option<int> spawn( + const std::string& file, + const std::vector<std::string>& arguments); + + +// This wrapper allows a caller to call `execvp` on both POSIX +// and Windows systems. +// +// Windows: In order to emulate `execvp`, this function forks +// another subprocess to execute with the provided arguments, +// and once the subprocess terminates, the parent process will +// in turn exit with the same exit code. Note that on Windows, +// processes are started using a string command line, and each +// process does its own parsing of that command line into +// arguments. This function will quote and escape the arguments +// compatible with any programs that use `CommandLineToArgvW` +// (this is the most common way, and any programs that use +// libc-style main with an arguments array will use this under +// the covers). However, some programs, notably cmd.exe have +// their own approach for parsing quotes / arguments that are +// not compatible with CommandLineToArgvW, and therefore should +// not be used with this function! +// +// TODO(bmahler): Probably we shouldn't provide this windows +// emulation and should instead have the caller use windows +// subprocess functions directly? +inline int execvp(const char* file, char* const argv[]); + + +// This function is a portable version of execvpe ('p' means searching +// executable from PATH and 'e' means setting environments). We add +// this function because it is not available on all POSIX systems. +// +// POSIX: This function is not thread safe. It is supposed to be used +// only after fork (when there is only one thread). This function is +// async signal safe. +// +// Windows: In order to emulate `execvpe`, this function forks +// another subprocess to execute with the provided arguments, +// and once the subprocess terminates, the parent process will +// in turn exit with the same exit code. Note that on Windows, +// processes are started using a string command line, and each +// process does its own parsing of that command line into +// arguments. This function will quote and escape the arguments +// compatible with any programs that use `CommandLineToArgvW` +// (this is the most common way, and any programs that use +// libc-style main with an arguments array will use this under +// the covers). However, some programs, notably cmd.exe have +// their own approach for parsing quotes / arguments that are +// not compatible with CommandLineToArgvW, and therefore should +// not be used with this function! +// +// NOTE: This function can accept `Argv` and `Envp` constructs +// via their implicit type conversions, but on Windows, it cannot +// accept the os::raw forms. +// +// TODO(bmahler): Probably we shouldn't provide this windows +// emulation and should instead have the caller use windows +// subprocess functions directly? +inline int execvpe(const char* file, char** argv, char** envp); + +} // namespace os { + #endif // __STOUT_OS_EXEC_HPP__ diff --git a/3rdparty/stout/include/stout/os/posix/exec.hpp b/3rdparty/stout/include/stout/os/posix/exec.hpp index dd0f42d..3057b45 100644 --- a/3rdparty/stout/include/stout/os/posix/exec.hpp +++ b/3rdparty/stout/include/stout/os/posix/exec.hpp @@ -29,12 +29,6 @@ namespace os { -// Executes a command by calling "<command> <arguments...>", and returns after -// the command has been completed. Returns the exit code on success and `None` -// on error (e.g., fork/exec/waitpid failed). This function is async signal -// safe. We return an `Option<int>` instead of a `Try<int>`, because although -// `Try` does not dynamically allocate, `Error` uses `std::string`, which is -// not async signal safe. inline Option<int> spawn( const std::string& file, const std::vector<std::string>& arguments) @@ -67,13 +61,6 @@ inline int execvp(const char* file, char* const argv[]) } -// This function is a portable version of execvpe ('p' means searching -// executable from PATH and 'e' means setting environments). We add -// this function because it is not available on all systems. -// -// NOTE: This function is not thread safe. It is supposed to be used -// only after fork (when there is only one thread). This function is -// async signal safe. inline int execvpe(const char* file, char** argv, char** envp) { char** saved = os::raw::environment(); diff --git a/3rdparty/stout/include/stout/os/windows/exec.hpp b/3rdparty/stout/include/stout/os/windows/exec.hpp index 8c6f10b..21e1d15 100644 --- a/3rdparty/stout/include/stout/os/windows/exec.hpp +++ b/3rdparty/stout/include/stout/os/windows/exec.hpp @@ -409,9 +409,6 @@ inline Try<ProcessData> create_process( } // namespace windows { -// Executes a command by calling "<command> <arguments...>", and -// returns after the command has been completed. Returns the process exit -// code on success and `None` on error. inline Option<int> spawn( const std::string& command, const std::vector<std::string>& arguments, @@ -442,9 +439,6 @@ inline Option<int> spawn( } -// In order to emulate the semantics of `execvp`, `os::spawn` waits for the new -// process to exit, and returns its error code, which is propagated back to the -// parent via `exit` here. inline int execvp( const std::string& file, const std::vector<std::string>& argv) @@ -454,9 +448,6 @@ inline int execvp( } -// NOTE: This function can accept `Argv` and `Envp` constructs through their -// explicit type conversions, but unlike the POSIX implementations, it cannot -// accept the raw forms. inline int execvpe( const std::string& file, const std::vector<std::string>& argv,
