Merge branch 'cb/do-not-use-test-cmp-with-a'
[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
fa64a2fd
JT
32struct subprocess_capability {
33 const char *name;
34
35 /*
36 * subprocess_handshake will "|=" this value to supported_capabilities
37 * if the server reports that it supports this capability.
38 */
39 unsigned int flag;
40};
41
99605d62
BP
42/* subprocess functions */
43
7e2e1bbb 44/* Function to test two subprocess hashmap entries for equality. */
55454427 45int cmd2process_cmp(const void *unused_cmp_data,
ad6dad09
DL
46 const void *e1,
47 const void *e2,
48 const void *unused_keydata);
99605d62 49
7e2e1bbb
JT
50/*
51 * User-supplied function to initialize the sub-process. This is
52 * typically used to negotiate the interface version and capabilities.
53 */
99605d62 54typedef int(*subprocess_start_fn)(struct subprocess_entry *entry);
7e2e1bbb
JT
55
56/* Start a subprocess and add it to the subprocess hashmap. */
99605d62
BP
57int subprocess_start(struct hashmap *hashmap, struct subprocess_entry *entry, const char *cmd,
58 subprocess_start_fn startfn);
59
7e2e1bbb 60/* Kill a subprocess and remove it from the subprocess hashmap. */
99605d62
BP
61void subprocess_stop(struct hashmap *hashmap, struct subprocess_entry *entry);
62
7e2e1bbb 63/* Find a subprocess in the subprocess hashmap. */
99605d62
BP
64struct subprocess_entry *subprocess_find_entry(struct hashmap *hashmap, const char *cmd);
65
66/* subprocess helper functions */
67
7e2e1bbb 68/* Get the underlying `struct child_process` from a subprocess. */
99605d62
BP
69static inline struct child_process *subprocess_get_child_process(
70 struct subprocess_entry *entry)
71{
72 return &entry->process;
73}
74
fa64a2fd 75/*
addad105
JT
76 * Perform the version and capability negotiation as described in the
77 * "Handshake" section of long-running-process-protocol.txt using the
fa64a2fd
JT
78 * given requested versions and capabilities. The "versions" and "capabilities"
79 * parameters are arrays terminated by a 0 or blank struct.
80 *
81 * This function is typically called when a subprocess is started (as part of
82 * the "startfn" passed to subprocess_start).
83 */
84int subprocess_handshake(struct subprocess_entry *entry,
85 const char *welcome_prefix,
86 int *versions,
87 int *chosen_version,
88 struct subprocess_capability *capabilities,
89 unsigned int *supported_capabilities);
90
99605d62
BP
91/*
92 * Helper function that will read packets looking for "status=<foo>"
93 * key/value pairs and return the value from the last "status" packet
94 */
95
4f2a2e9f 96int subprocess_read_status(int fd, struct strbuf *status);
99605d62
BP
97
98#endif