Move the documentation for the sub-process API from a separate txt file
to its header file.
Signed-off-by: Jonathan Tan <jonathantanmy@xxxxxxxxxx>
---
Documentation/technical/api-sub-process.txt | 59 -----------------------------
sub-process.h | 25 +++++++++++-
2 files changed, 23 insertions(+), 61 deletions(-)
delete mode 100644 Documentation/technical/api-sub-process.txt
diff --git a/Documentation/technical/api-sub-process.txt b/Documentation/technical/api-sub-process.txt
deleted file mode 100644
index 793508cf3..000000000
--- a/Documentation/technical/api-sub-process.txt
+++ /dev/null
@@ -1,59 +0,0 @@
-sub-process API
-===============
-
-The sub-process API makes it possible to run background sub-processes
-for the entire lifetime of a Git invocation. If Git needs to communicate
-with an external process multiple times, then this can reduces the process
-invocation overhead. Git and the sub-process communicate through stdin and
-stdout.
-
-The sub-processes are kept in a hashmap by command name and looked up
-via the subprocess_find_entry function. If an existing instance can not
-be found then a new process should be created and started. When the
-parent git command terminates, all sub-processes are also terminated.
-
-This API is based on the run-command API.
-
-Data structures
----------------
-
-* `struct subprocess_entry`
-
-The sub-process structure. Members should not be accessed directly.
-
-Types
------
-
-'int(*subprocess_start_fn)(struct subprocess_entry *entry)'::
-
- User-supplied function to initialize the sub-process. This is
- typically used to negotiate the interface version and capabilities.
-
-
-Functions
----------
-
-`cmd2process_cmp`::
-
- Function to test two subprocess hashmap entries for equality.
-
-`subprocess_start`::
-
- Start a subprocess and add it to the subprocess hashmap.
-
-`subprocess_stop`::
-
- Kill a subprocess and remove it from the subprocess hashmap.
-
-`subprocess_find_entry`::
-
- Find a subprocess in the subprocess hashmap.
-
-`subprocess_get_child_process`::
-
- Get the underlying `struct child_process` from a subprocess.
-
-`subprocess_read_status`::
-
- Helper function to read packets looking for the last "status=<foo>"
- key/value pair.
diff --git a/sub-process.h b/sub-process.h
index 8cd07a59a..d37c1499a 100644
--- a/sub-process.h
+++ b/sub-process.h
@@ -6,12 +6,23 @@
#include "run-command.h"
/*
- * Generic implementation of background process infrastructure.
- * See: Documentation/technical/api-sub-process.txt
+ * The sub-process API makes it possible to run background sub-processes
+ * for the entire lifetime of a Git invocation. If Git needs to communicate
+ * with an external process multiple times, then this can reduces the process
+ * invocation overhead. Git and the sub-process communicate through stdin and
+ * stdout.
+ *
+ * The sub-processes are kept in a hashmap by command name and looked up
+ * via the subprocess_find_entry function. If an existing instance can not
+ * be found then a new process should be created and started. When the
+ * parent git command terminates, all sub-processes are also terminated.
+ *
+ * This API is based on the run-command API.
*/
/* data structures */
+/* Members should not be accessed directly. */
struct subprocess_entry {
struct hashmap_entry ent; /* must be the first member! */
const char *cmd;
@@ -20,21 +31,31 @@ struct subprocess_entry {
/* subprocess functions */
+/* Function to test two subprocess hashmap entries for equality. */
extern int cmd2process_cmp(const void *unused_cmp_data,
const void *e1,
const void *e2,
const void *unused_keydata);
+/*
+ * User-supplied function to initialize the sub-process. This is
+ * typically used to negotiate the interface version and capabilities.
+ */
typedef int(*subprocess_start_fn)(struct subprocess_entry *entry);
+
+/* Start a subprocess and add it to the subprocess hashmap. */
int subprocess_start(struct hashmap *hashmap, struct subprocess_entry *entry, const char *cmd,
subprocess_start_fn startfn);
+/* Kill a subprocess and remove it from the subprocess hashmap. */
void subprocess_stop(struct hashmap *hashmap, struct subprocess_entry *entry);
+/* Find a subprocess in the subprocess hashmap. */
struct subprocess_entry *subprocess_find_entry(struct hashmap *hashmap, const char *cmd);
/* subprocess helper functions */
+/* Get the underlying `struct child_process` from a subprocess. */
static inline struct child_process *subprocess_get_child_process(
struct subprocess_entry *entry)
{
--
2.14.0.rc0.400.g1c36432dff-goog
