Documentation: migrate sub-process docs to header
[git/git.git] / sub-process.h
CommitLineData
99605d62
BP
1#ifndef SUBPROCESS_H
2#define SUBPROCESS_H
3
4#include "git-compat-util.h"
5#include "hashmap.h"
6#include "run-command.h"
7
8/*
7e2e1bbb
JT
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.
99605d62
BP
21 */
22
23 /* data structures */
24
7e2e1bbb 25/* Members should not be accessed directly. */
99605d62
BP
26struct subprocess_entry {
27 struct hashmap_entry ent; /* must be the first member! */
28 const char *cmd;
29 struct child_process process;
30};
31
32/* subprocess functions */
33
7e2e1bbb 34/* Function to test two subprocess hashmap entries for equality. */
7663cdc8
SB
35extern 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);
99605d62 39
7e2e1bbb
JT
40/*
41 * User-supplied function to initialize the sub-process. This is
42 * typically used to negotiate the interface version and capabilities.
43 */
99605d62 44typedef int(*subprocess_start_fn)(struct subprocess_entry *entry);
7e2e1bbb
JT
45
46/* Start a subprocess and add it to the subprocess hashmap. */
99605d62
BP
47int subprocess_start(struct hashmap *hashmap, struct subprocess_entry *entry, const char *cmd,
48 subprocess_start_fn startfn);
49
7e2e1bbb 50/* Kill a subprocess and remove it from the subprocess hashmap. */
99605d62
BP
51void subprocess_stop(struct hashmap *hashmap, struct subprocess_entry *entry);
52
7e2e1bbb 53/* Find a subprocess in the subprocess hashmap. */
99605d62
BP
54struct subprocess_entry *subprocess_find_entry(struct hashmap *hashmap, const char *cmd);
55
56/* subprocess helper functions */
57
7e2e1bbb 58/* Get the underlying `struct child_process` from a subprocess. */
99605d62
BP
59static inline struct child_process *subprocess_get_child_process(
60 struct subprocess_entry *entry)
61{
62 return &entry->process;
63}
64
65/*
66 * Helper function that will read packets looking for "status=<foo>"
67 * key/value pairs and return the value from the last "status" packet
68 */
69
4f2a2e9f 70int subprocess_read_status(int fd, struct strbuf *status);
99605d62
BP
71
72#endif