Merge branch 'km/merge-recursive-typofix'

[thirdparty/git.git] / run-command.h

diff --git a/run-command.h b/run-command.h
index 0e85e5846a568d12472e24958860b11598d93599..072db56a4dff15996889bded735dd02f2bc52e73 100644 (file)
--- a/run-command.h
+++ b/run-command.h
@@ -150,9 +150,7 @@ struct child_process {
 }
 
 /**
- * The functions: child_process_init, start_command, finish_command,
- * run_command, run_command_v_opt, run_command_v_opt_cd_env, child_process_clear
- * do the following:
+ * 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.
@@ -224,36 +222,6 @@ int run_command(struct child_process *);
  */
 int run_auto_maintenance(int quiet);
 
-#define RUN_COMMAND_NO_STDIN           (1<<0)
-#define RUN_GIT_CMD                    (1<<1)
-#define RUN_COMMAND_STDOUT_TO_STDERR   (1<<2)
-#define RUN_SILENT_EXEC_FAILURE                (1<<3)
-#define RUN_USING_SHELL                        (1<<4)
-#define RUN_CLEAN_ON_EXIT              (1<<5)
-#define RUN_WAIT_AFTER_CLEAN           (1<<6)
-#define RUN_CLOSE_OBJECT_STORE         (1<<7)
-
-/**
- * Convenience functions that encapsulate a sequence of
- * start_command() followed by finish_command(). The argument argv
- * specifies the program and its arguments. The argument opt is zero
- * or more of the flags `RUN_COMMAND_NO_STDIN`, `RUN_GIT_CMD`,
- * `RUN_COMMAND_STDOUT_TO_STDERR`, or `RUN_SILENT_EXEC_FAILURE`
- * that correspond to the members .no_stdin, .git_cmd,
- * .stdout_to_stderr, .silent_exec_failure of `struct child_process`.
- * The argument dir corresponds the member .dir. The argument env
- * corresponds to the member .env.
- */
-int run_command_v_opt(const char **argv, int opt);
-int run_command_v_opt_tr2(const char **argv, int opt, const char *tr2_class);
-/*
- * env (the environment) is to be formatted like environ: "VAR=VALUE".
- * To unset an environment variable use just "VAR".
- */
-int run_command_v_opt_cd_env(const char **argv, int opt, const char *dir, const char *const *env);
-int run_command_v_opt_cd_env_tr2(const char **argv, int opt, const char *dir,
-                                const char *const *env, const char *tr2_class);
-
 /**
  * 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
@@ -459,17 +427,64 @@ typedef int (*task_finished_fn)(int result,
                                void *pp_task_cb);
 
 /**
- * Runs up to n processes at the same time. Whenever a process can be
- * started, the callback get_next_task_fn is called to obtain the data
+ * 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).
  *
- * start_failure_fn and task_finished_fn can be NULL to omit any
- * special handling.
- *
  * 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
@@ -479,20 +494,8 @@ typedef int (*task_finished_fn)(int result,
  * 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.
- * The "ungroup" option can be enabled by setting the global
- * "run_processes_parallel_ungroup" to "1" before invoking
- * run_processes_parallel(), it will be set back to "0" as soon as the
- * API reads that setting.
  */
-extern int run_processes_parallel_ungroup;
-int run_processes_parallel(int n,
-                          get_next_task_fn,
-                          start_failure_fn,
-                          task_finished_fn,
-                          void *pp_cb);
-int run_processes_parallel_tr2(int n, get_next_task_fn, start_failure_fn,
-                              task_finished_fn, void *pp_cb,
-                              const char *tr2_category, const char *tr2_label);
+void run_processes_parallel(const struct run_process_parallel_opts *opts);
 
 /**
  * Convenience function which prepares env for a command to be run in a