sub-process: move sub-process functions into separate files
[git/git.git] / Documentation / technical / api-sub-process.txt
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.