From 8b71466c439dfd316906a6b1ef2ff7a30f4221ad Mon Sep 17 00:00:00 2001 From: Alp Toker Date: Tue, 10 Dec 2013 16:31:09 +0000 Subject: [PATCH] Support: Update documentation for Program functions The docstrings were describing an older interface that has been replaced with functions. Also describe the performance characteristics of FindProgramByName() and ExecuteAndWait() explaining when it's best to avoid them. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@196932 91177308-0d34-0410-b5e6-96231b3b80d8 --- include/llvm/Support/Program.h | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/include/llvm/Support/Program.h b/include/llvm/Support/Program.h index 00571a40801..60b21818306 100644 --- a/include/llvm/Support/Program.h +++ b/include/llvm/Support/Program.h @@ -52,13 +52,16 @@ struct ProcessInfo { ProcessInfo(); }; - /// This static constructor (factory) will attempt to locate a program in - /// the operating system's file system using some pre-determined set of - /// locations to search (e.g. the PATH on Unix). Paths with slashes are - /// returned unmodified. - /// @returns A Path object initialized to the path of the program or a - /// Path object that is empty (invalid) if the program could not be found. - /// @brief Construct a Program by finding it by name. + /// This function attempts to locate a program in the operating + /// system's file system using some pre-determined set of locations to search + /// (e.g. the PATH on Unix). Paths with slashes are returned unmodified. + /// + /// It does not perform hashing as a shell would but instead stats each PATH + /// entry individually so should generally be avoided. Core LLVM library + /// functions and options should instead require fully specified paths. + /// + /// @returns A string containing the path of the program or an empty string if + /// the program could not be found. std::string FindProgramByName(const std::string& name); // These functions change the specified standard stream (stdin, stdout, or @@ -72,7 +75,9 @@ struct ProcessInfo { /// invoked program will inherit the stdin, stdout, and stderr file /// descriptors, the environment and other configuration settings of the /// invoking program. - /// This function waits the program to finish. + /// This function waits for the program to finish, so should be avoided in + /// library functions that aren't expected to block. Consider using + /// ExecuteNoWait() instead. /// @returns an integer result code indicating the status of the program. /// A zero or positive value indicates the result code of the program. /// -1 indicates failure to execute