diff options
| -rw-r--r-- | Documentation/technical/api-sub-process.txt | 59 | ||||
| -rw-r--r-- | sub-process.h | 25 |
2 files changed, 23 insertions, 61 deletions
diff --git a/Documentation/technical/api-sub-process.txt b/Documentation/technical/api-sub-process.txt deleted file mode 100644 index 793508c..0000000 --- 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 96a2cca..e546216 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 struct subprocess_entry *e1, const struct subprocess_entry *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) { |