Documentation: migrate sub-process docs to header
Move the documentation for the sub-process API from a separate txt file to its header file. Signed-off-by: Jonathan Tan <jonathantanmy@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jonathan Tan committed
Jul 26, 2017 at 11:17 UTC
7e2e1bbb24a5a0868fc83f1eddf804574f9e4b54
2 files changed
+23
-61
Documentation/technical/api-sub-process.txt
deleted
-59
@@ -1,59 +0,0 @@
1
-sub-process API
2
-===============
3
-
4
-The sub-process API makes it possible to run background sub-processes
5
-for the entire lifetime of a Git invocation. If Git needs to communicate
6
-with an external process multiple times, then this can reduces the process
7
-invocation overhead. Git and the sub-process communicate through stdin and
8
-stdout.
9
-
10
-The sub-processes are kept in a hashmap by command name and looked up
11
-via the subprocess_find_entry function. If an existing instance can not
12
-be found then a new process should be created and started. When the
13
-parent git command terminates, all sub-processes are also terminated.
14
-
15
-This API is based on the run-command API.
16
-
17
-Data structures
18
----------------
19
-
20
-* `struct subprocess_entry`
21
-
22
-The sub-process structure. Members should not be accessed directly.
23
-
24
-Types
25
------
26
-
27
-'int(*subprocess_start_fn)(struct subprocess_entry *entry)'::
28
-
29
- User-supplied function to initialize the sub-process. This is
30
- typically used to negotiate the interface version and capabilities.
31
-
32
-
33
-Functions
34
----------
35
-
36
-`cmd2process_cmp`::
37
-
38
- Function to test two subprocess hashmap entries for equality.
39
-
40
-`subprocess_start`::
41
-
42
- Start a subprocess and add it to the subprocess hashmap.
43
-
44
-`subprocess_stop`::
45
-
46
- Kill a subprocess and remove it from the subprocess hashmap.
47
-
48
-`subprocess_find_entry`::
49
-
50
- Find a subprocess in the subprocess hashmap.
51
-
52
-`subprocess_get_child_process`::
53
-
54
- Get the underlying `struct child_process` from a subprocess.
55
-
56
-`subprocess_read_status`::
57
-
58
- Helper function to read packets looking for the last "status=<foo>"
59
- key/value pair.
sub-process.h
+23
-2
@@ -6,12 +6,23 @@
6
#include "run-command.h"
7
8
/*
9
- * Generic implementation of background process infrastructure.
10
- * See: Documentation/technical/api-sub-process.txt
9
+ * The sub-process API makes it possible to run background sub-processes
10
+ * for the entire lifetime of a Git invocation. If Git needs to communicate
11
+ * with an external process multiple times, then this can reduces the process
12
+ * invocation overhead. Git and the sub-process communicate through stdin and
13
+ * stdout.
14
+ *
15
+ * The sub-processes are kept in a hashmap by command name and looked up
16
+ * via the subprocess_find_entry function. If an existing instance can not
17
+ * be found then a new process should be created and started. When the
18
+ * parent git command terminates, all sub-processes are also terminated.
19
+ *
20
+ * This API is based on the run-command API.
21
*/
22
23
/* data structures */
24
25
+/* Members should not be accessed directly. */
26
struct subprocess_entry {
27
struct hashmap_entry ent; /* must be the first member! */
28
const char *cmd;
@@ -20,21 +31,31 @@ struct subprocess_entry {
31
32
/* subprocess functions */
33
34
+/* Function to test two subprocess hashmap entries for equality. */
35
extern int cmd2process_cmp(const void *unused_cmp_data,
36
const struct subprocess_entry *e1,
37
const struct subprocess_entry *e2,
38
const void *unused_keydata);
39
40
+/*
41
+ * User-supplied function to initialize the sub-process. This is
42
+ * typically used to negotiate the interface version and capabilities.
43
+ */
44
typedef int(*subprocess_start_fn)(struct subprocess_entry *entry);
45
+
46
+/* Start a subprocess and add it to the subprocess hashmap. */
47
int subprocess_start(struct hashmap *hashmap, struct subprocess_entry *entry, const char *cmd,
48
subprocess_start_fn startfn);
49
50
+/* Kill a subprocess and remove it from the subprocess hashmap. */
51
void subprocess_stop(struct hashmap *hashmap, struct subprocess_entry *entry);
52
53
+/* Find a subprocess in the subprocess hashmap. */
54
struct subprocess_entry *subprocess_find_entry(struct hashmap *hashmap, const char *cmd);
55
56
/* subprocess helper functions */
57
58
+/* Get the underlying `struct child_process` from a subprocess. */
59
static inline struct child_process *subprocess_get_child_process(
60
struct subprocess_entry *entry)
61
{