From c8bae7493d2f2910b57f13ded012e86bdcfb0532 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 16:47:53 +0200 Subject: Adding upstream version 1:2.39.2. Signed-off-by: Daniel Baumann --- run-command.h | 567 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 567 insertions(+) create mode 100644 run-command.h (limited to 'run-command.h') diff --git a/run-command.h b/run-command.h new file mode 100644 index 0000000..072db56 --- /dev/null +++ b/run-command.h @@ -0,0 +1,567 @@ +#ifndef RUN_COMMAND_H +#define RUN_COMMAND_H + +#include "thread-utils.h" + +#include "strvec.h" + +/** + * The run-command API offers a versatile tool to run sub-processes with + * redirected input and output as well as with a modified environment + * and an alternate current directory. + * + * A similar API offers the capability to run a function asynchronously, + * which is primarily used to capture the output that the function + * produces in the caller in order to process it. + */ + + +/** + * This describes the arguments, redirections, and environment of a + * command to run in a sub-process. + * + * The caller: + * + * 1. allocates and clears (using child_process_init() or + * CHILD_PROCESS_INIT) a struct child_process variable; + * 2. initializes the members; + * 3. calls start_command(); + * 4. processes the data; + * 5. closes file descriptors (if necessary; see below); + * 6. calls finish_command(). + * + * Special forms of redirection are available by setting these members + * to 1: + * + * .no_stdin, .no_stdout, .no_stderr: The respective channel is + * redirected to /dev/null. + * + * .stdout_to_stderr: stdout of the child is redirected to its + * stderr. This happens after stderr is itself redirected. + * So stdout will follow stderr to wherever it is + * redirected. + */ +struct child_process { + + /** + * The .args is a `struct strvec', use that API to manipulate + * it, e.g. strvec_pushv() to add an existing "const char **" + * vector. + * + * If the command to run is a git command, set the first + * element in the strvec to the command name without the + * 'git-' prefix and set .git_cmd = 1. + * + * The memory in .args will be cleaned up automatically during + * `finish_command` (or during `start_command` when it is unsuccessful). + */ + struct strvec args; + + /** + * Like .args the .env is a `struct strvec'. + * + * To modify the environment of the sub-process, specify an array of + * environment settings. Each string in the array manipulates the + * environment. + * + * - If the string is of the form "VAR=value", i.e. it contains '=' + * the variable is added to the child process's environment. + * + * - If the string does not contain '=', it names an environment + * variable that will be removed from the child process's environment. + * + * The memory in .env will be cleaned up automatically during + * `finish_command` (or during `start_command` when it is unsuccessful). + */ + struct strvec env; + pid_t pid; + + int trace2_child_id; + uint64_t trace2_child_us_start; + const char *trace2_child_class; + const char *trace2_hook_name; + + /* + * Using .in, .out, .err: + * - Specify 0 for no redirections. No new file descriptor is allocated. + * (child inherits stdin, stdout, stderr from parent). + * - Specify -1 to have a pipe allocated as follows: + * .in: returns the writable pipe end; parent writes to it, + * the readable pipe end becomes child's stdin + * .out, .err: returns the readable pipe end; parent reads from + * it, the writable pipe end becomes child's stdout/stderr + * The caller of start_command() must close the returned FDs + * after it has completed reading from/writing to it! + * - Specify > 0 to set a channel to a particular FD as follows: + * .in: a readable FD, becomes child's stdin + * .out: a writable FD, becomes child's stdout/stderr + * .err: a writable FD, becomes child's stderr + * The specified FD is closed by start_command(), even in case + * of errors! + */ + int in; + int out; + int err; + + /** + * To specify a new initial working directory for the sub-process, + * specify it in the .dir member. + */ + const char *dir; + + unsigned no_stdin:1; + unsigned no_stdout:1; + unsigned no_stderr:1; + unsigned git_cmd:1; /* if this is to be git sub-command */ + + /** + * If the program cannot be found, the functions return -1 and set + * errno to ENOENT. Normally, an error message is printed, but if + * .silent_exec_failure is set to 1, no message is printed for this + * special error condition. + */ + unsigned silent_exec_failure:1; + + /** + * Run the command from argv[0] using a shell (but note that we may + * still optimize out the shell call if the command contains no + * metacharacters). Note that further arguments to the command in + * argv[1], etc, do not need to be shell-quoted. + */ + unsigned use_shell:1; + + /** + * Release any open file handles to the object store before running + * the command; This is necessary e.g. when the spawned process may + * want to repack because that would delete `.pack` files (and on + * Windows, you cannot delete files that are still in use). + */ + unsigned close_object_store:1; + + unsigned stdout_to_stderr:1; + unsigned clean_on_exit:1; + unsigned wait_after_clean:1; + void (*clean_on_exit_handler)(struct child_process *process); +}; + +#define CHILD_PROCESS_INIT { \ + .args = STRVEC_INIT, \ + .env = STRVEC_INIT, \ +} + +/** + * The functions: start_command, finish_command, run_command do the following: + * + * - If a system call failed, errno is set and -1 is returned. A diagnostic + * is printed. + * + * - If the program was not found, then -1 is returned and errno is set to + * ENOENT; a diagnostic is printed only if .silent_exec_failure is 0. + * + * - Otherwise, the program is run. If it terminates regularly, its exit + * code is returned. No diagnostic is printed, even if the exit code is + * non-zero. + * + * - If the program terminated due to a signal, then the return value is the + * signal number + 128, ie. the same value that a POSIX shell's $? would + * report. A diagnostic is printed. + * + */ + +/** + * Initialize a struct child_process variable. + */ +void child_process_init(struct child_process *); + +/** + * Release the memory associated with the struct child_process. + * Most users of the run-command API don't need to call this + * function explicitly because `start_command` invokes it on + * failure and `finish_command` calls it automatically already. + */ +void child_process_clear(struct child_process *); + +int is_executable(const char *name); + +/** + * Check if the command exists on $PATH. This emulates the path search that + * execvp would perform, without actually executing the command so it + * can be used before fork() to prepare to run a command using + * execve() or after execvp() to diagnose why it failed. + * + * The caller should ensure that command contains no directory separators. + * + * Returns 1 if it is found in $PATH or 0 if the command could not be found. + */ +int exists_in_PATH(const char *command); + +/** + * Start a sub-process. Takes a pointer to a `struct child_process` + * that specifies the details and returns pipe FDs (if requested). + * See below for details. + */ +int start_command(struct child_process *); + +/** + * Wait for the completion of a sub-process that was started with + * start_command(). + */ +int finish_command(struct child_process *); + +int finish_command_in_signal(struct child_process *); + +/** + * A convenience function that encapsulates a sequence of + * start_command() followed by finish_command(). Takes a pointer + * to a `struct child_process` that specifies the details. + */ +int run_command(struct child_process *); + +/* + * Trigger an auto-gc + */ +int run_auto_maintenance(int quiet); + +/** + * Execute the given command, sending "in" to its stdin, and capturing its + * stdout and stderr in the "out" and "err" strbufs. Any of the three may + * be NULL to skip processing. + * + * Returns -1 if starting the command fails or reading fails, and otherwise + * returns the exit code of the command. Any output collected in the + * buffers is kept even if the command returns a non-zero exit. The hint fields + * gives starting sizes for the strbuf allocations. + * + * The fields of "cmd" should be set up as they would for a normal run_command + * invocation. But note that there is no need to set the in, out, or err + * fields; pipe_command handles that automatically. + */ +int pipe_command(struct child_process *cmd, + const char *in, size_t in_len, + struct strbuf *out, size_t out_hint, + struct strbuf *err, size_t err_hint); + +/** + * Convenience wrapper around pipe_command for the common case + * of capturing only stdout. + */ +static inline int capture_command(struct child_process *cmd, + struct strbuf *out, + size_t hint) +{ + return pipe_command(cmd, NULL, 0, out, hint, NULL, 0); +} + +/* + * The purpose of the following functions is to feed a pipe by running + * a function asynchronously and providing output that the caller reads. + * + * It is expected that no synchronization and mutual exclusion between + * the caller and the feed function is necessary so that the function + * can run in a thread without interfering with the caller. + * + * The caller: + * + * 1. allocates and clears (memset(&asy, 0, sizeof(asy));) a + * struct async variable; + * 2. initializes .proc and .data; + * 3. calls start_async(); + * 4. processes communicates with proc through .in and .out; + * 5. closes .in and .out; + * 6. calls finish_async(). + * + * There are serious restrictions on what the asynchronous function can do + * because this facility is implemented by a thread in the same address + * space on most platforms (when pthreads is available), but by a pipe to + * a forked process otherwise: + * + * - It cannot change the program's state (global variables, environment, + * etc.) in a way that the caller notices; in other words, .in and .out + * are the only communication channels to the caller. + * + * - It must not change the program's state that the caller of the + * facility also uses. + * + */ +struct async { + + /** + * The function pointer in .proc has the following signature: + * + * int proc(int in, int out, void *data); + * + * - in, out specifies a set of file descriptors to which the function + * must read/write the data that it needs/produces. The function + * *must* close these descriptors before it returns. A descriptor + * may be -1 if the caller did not configure a descriptor for that + * direction. + * + * - data is the value that the caller has specified in the .data member + * of struct async. + * + * - The return value of the function is 0 on success and non-zero + * on failure. If the function indicates failure, finish_async() will + * report failure as well. + * + */ + int (*proc)(int in, int out, void *data); + + void *data; + + /** + * The members .in, .out are used to provide a set of fd's for + * communication between the caller and the callee as follows: + * + * - Specify 0 to have no file descriptor passed. The callee will + * receive -1 in the corresponding argument. + * + * - Specify < 0 to have a pipe allocated; start_async() replaces + * with the pipe FD in the following way: + * + * .in: Returns the writable pipe end into which the caller + * writes; the readable end of the pipe becomes the function's + * in argument. + * + * .out: Returns the readable pipe end from which the caller + * reads; the writable end of the pipe becomes the function's + * out argument. + * + * The caller of start_async() must close the returned FDs after it + * has completed reading from/writing from them. + * + * - Specify a file descriptor > 0 to be used by the function: + * + * .in: The FD must be readable; it becomes the function's in. + * .out: The FD must be writable; it becomes the function's out. + * + * The specified FD is closed by start_async(), even if it fails to + * run the function. + */ + int in; /* caller writes here and closes it */ + int out; /* caller reads from here and closes it */ +#ifdef NO_PTHREADS + pid_t pid; +#else + pthread_t tid; + int proc_in; + int proc_out; +#endif + int isolate_sigpipe; +}; + +/** + * Run a function asynchronously. Takes a pointer to a `struct + * async` that specifies the details and returns a set of pipe FDs + * for communication with the function. See below for details. + */ +int start_async(struct async *async); + +/** + * Wait for the completion of an asynchronous function that was + * started with start_async(). + */ +int finish_async(struct async *async); + +int in_async(void); +int async_with_fork(void); +void check_pipe(int err); + +/** + * This callback should initialize the child process and preload the + * error channel if desired. The preloading of is useful if you want to + * have a message printed directly before the output of the child process. + * pp_cb is the callback cookie as passed to run_processes_parallel. + * You can store a child process specific callback cookie in pp_task_cb. + * + * See run_processes_parallel() below for a discussion of the "struct + * strbuf *out" parameter. + * + * Even after returning 0 to indicate that there are no more processes, + * this function will be called again until there are no more running + * child processes. + * + * Return 1 if the next child is ready to run. + * Return 0 if there are currently no more tasks to be processed. + * To send a signal to other child processes for abortion, + * return the negative signal number. + */ +typedef int (*get_next_task_fn)(struct child_process *cp, + struct strbuf *out, + void *pp_cb, + void **pp_task_cb); + +/** + * This callback is called whenever there are problems starting + * a new process. + * + * See run_processes_parallel() below for a discussion of the "struct + * strbuf *out" parameter. + * + * pp_cb is the callback cookie as passed into run_processes_parallel, + * pp_task_cb is the callback cookie as passed into get_next_task_fn. + * + * Return 0 to continue the parallel processing. To abort return non zero. + * To send a signal to other child processes for abortion, return + * the negative signal number. + */ +typedef int (*start_failure_fn)(struct strbuf *out, + void *pp_cb, + void *pp_task_cb); + +/** + * This callback is called on every child process that finished processing. + * + * See run_processes_parallel() below for a discussion of the "struct + * strbuf *out" parameter. + * + * pp_cb is the callback cookie as passed into run_processes_parallel, + * pp_task_cb is the callback cookie as passed into get_next_task_fn. + * + * Return 0 to continue the parallel processing. To abort return non zero. + * To send a signal to other child processes for abortion, return + * the negative signal number. + */ +typedef int (*task_finished_fn)(int result, + struct strbuf *out, + void *pp_cb, + void *pp_task_cb); + +/** + * Option used by run_processes_parallel(), { 0 }-initialized means no + * options. + */ +struct run_process_parallel_opts +{ + /** + * tr2_category & tr2_label: sets the trace2 category and label for + * logging. These must either be unset, or both of them must be set. + */ + const char *tr2_category; + const char *tr2_label; + + /** + * processes: see 'processes' in run_processes_parallel() below. + */ + size_t processes; + + /** + * ungroup: see 'ungroup' in run_processes_parallel() below. + */ + unsigned int ungroup:1; + + /** + * get_next_task: See get_next_task_fn() above. This must be + * specified. + */ + get_next_task_fn get_next_task; + + /** + * start_failure: See start_failure_fn() above. This can be + * NULL to omit any special handling. + */ + start_failure_fn start_failure; + + /** + * task_finished: See task_finished_fn() above. This can be + * NULL to omit any special handling. + */ + task_finished_fn task_finished; + + /** + * data: user data, will be passed as "pp_cb" to the callback + * parameters. + */ + void *data; +}; + +/** + * Options are passed via the "struct run_process_parallel_opts" above. + * + * Runs N 'processes' at the same time. Whenever a process can be + * started, the callback opts.get_next_task is called to obtain the data + * required to start another child process. + * + * The children started via this function run in parallel. Their output + * (both stdout and stderr) is routed to stderr in a manner that output + * from different tasks does not interleave (but see "ungroup" below). + * + * If the "ungroup" option isn't specified, the API will set the + * "stdout_to_stderr" parameter in "struct child_process" and provide + * the callbacks with a "struct strbuf *out" parameter to write output + * to. In this case the callbacks must not write to stdout or + * stderr as such output will mess up the output of the other parallel + * processes. If "ungroup" option is specified callbacks will get a + * NULL "struct strbuf *out" parameter, and are responsible for + * emitting their own output, including dealing with any race + * conditions due to writing in parallel to stdout and stderr. + */ +void run_processes_parallel(const struct run_process_parallel_opts *opts); + +/** + * Convenience function which prepares env for a command to be run in a + * new repo. This adds all GIT_* environment variables to env with the + * exception of GIT_CONFIG_PARAMETERS and GIT_CONFIG_COUNT (which cause the + * corresponding environment variables to be unset in the subprocess) and adds + * an environment variable pointing to new_git_dir. See local_repo_env in + * cache.h for more information. + */ +void prepare_other_repo_env(struct strvec *env, const char *new_git_dir); + +/** + * Possible return values for start_bg_command(). + */ +enum start_bg_result { + /* child process is "ready" */ + SBGR_READY = 0, + + /* child process could not be started */ + SBGR_ERROR, + + /* callback error when testing for "ready" */ + SBGR_CB_ERROR, + + /* timeout expired waiting for child to become "ready" */ + SBGR_TIMEOUT, + + /* child process exited or was signalled before becomming "ready" */ + SBGR_DIED, +}; + +/** + * Callback used by start_bg_command() to ask whether the + * child process is ready or needs more time to become "ready". + * + * The callback will receive the cmd and cb_data arguments given to + * start_bg_command(). + * + * Returns 1 is child needs more time (subject to the requested timeout). + * Returns 0 if child is "ready". + * Returns -1 on any error and cause start_bg_command() to also error out. + */ +typedef int(start_bg_wait_cb)(const struct child_process *cmd, void *cb_data); + +/** + * Start a command in the background. Wait long enough for the child + * to become "ready" (as defined by the provided callback). Capture + * immediate errors (like failure to start) and any immediate exit + * status (such as a shutdown/signal before the child became "ready") + * and return this like start_command(). + * + * We run a custom wait loop using the provided callback to wait for + * the child to start and become "ready". This is limited by the given + * timeout value. + * + * If the child does successfully start and become "ready", we orphan + * it into the background. + * + * The caller must not call finish_command(). + * + * The opaque cb_data argument will be forwarded to the callback for + * any instance data that it might require. This may be NULL. + */ +enum start_bg_result start_bg_command(struct child_process *cmd, + start_bg_wait_cb *wait_cb, + void *cb_data, + unsigned int timeout_sec); + +#endif -- cgit v1.2.3