sub-process.h 3.15 KB
Newer Older
1 2 3 4 5 6 7 8
#ifndef SUBPROCESS_H
#define SUBPROCESS_H

#include "git-compat-util.h"
#include "hashmap.h"
#include "run-command.h"

/*
9 10 11 12 13 14 15 16 17 18 19 20
 * 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.
21 22 23 24
 */

 /* data structures */

25
/* Members should not be accessed directly. */
26 27 28 29 30 31
struct subprocess_entry {
	struct hashmap_entry ent; /* must be the first member! */
	const char *cmd;
	struct child_process process;
};

32 33 34 35 36 37 38 39 40 41
struct subprocess_capability {
	const char *name;

	/*
	 * subprocess_handshake will "|=" this value to supported_capabilities
	 * if the server reports that it supports this capability.
	 */
	unsigned int flag;
};

42 43
/* subprocess functions */

44
/* Function to test two subprocess hashmap entries for equality. */
45
extern int cmd2process_cmp(const void *unused_cmp_data,
46 47
			   const void *e1,
			   const void *e2,
48
			   const void *unused_keydata);
49

50 51 52 53
/*
 * User-supplied function to initialize the sub-process.  This is
 * typically used to negotiate the interface version and capabilities.
 */
54
typedef int(*subprocess_start_fn)(struct subprocess_entry *entry);
55 56

/* Start a subprocess and add it to the subprocess hashmap. */
57 58 59
int subprocess_start(struct hashmap *hashmap, struct subprocess_entry *entry, const char *cmd,
		subprocess_start_fn startfn);

60
/* Kill a subprocess and remove it from the subprocess hashmap. */
61 62
void subprocess_stop(struct hashmap *hashmap, struct subprocess_entry *entry);

63
/* Find a subprocess in the subprocess hashmap. */
64 65 66 67
struct subprocess_entry *subprocess_find_entry(struct hashmap *hashmap, const char *cmd);

/* subprocess helper functions */

68
/* Get the underlying `struct child_process` from a subprocess. */
69 70 71 72 73 74
static inline struct child_process *subprocess_get_child_process(
		struct subprocess_entry *entry)
{
	return &entry->process;
}

75
/*
76 77
 * Perform the version and capability negotiation as described in the
 * "Handshake" section of long-running-process-protocol.txt using the
78 79 80 81 82 83 84 85 86 87 88 89 90
 * given requested versions and capabilities. The "versions" and "capabilities"
 * parameters are arrays terminated by a 0 or blank struct.
 *
 * This function is typically called when a subprocess is started (as part of
 * the "startfn" passed to subprocess_start).
 */
int subprocess_handshake(struct subprocess_entry *entry,
			 const char *welcome_prefix,
			 int *versions,
			 int *chosen_version,
			 struct subprocess_capability *capabilities,
			 unsigned int *supported_capabilities);

91 92 93 94 95
/*
 * Helper function that will read packets looking for "status=<foo>"
 * key/value pairs and return the value from the last "status" packet
 */

96
int subprocess_read_status(int fd, struct strbuf *status);
97 98

#endif