From 7e2e1bbb24a5a0868fc83f1eddf804574f9e4b54 Mon Sep 17 00:00:00 2001 From: Jonathan Tan Date: Wed, 26 Jul 2017 11:17:28 -0700 Subject: Documentation: migrate sub-process docs to header Move the documentation for the sub-process API from a separate txt file to its header file. Signed-off-by: Jonathan Tan Signed-off-by: Junio C Hamano --- sub-process.h | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) (limited to 'sub-process.h') diff --git a/sub-process.h b/sub-process.h index 96a2cca360..e546216145 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) { -- cgit v1.2.3 From fa64a2fdbeedd98c5f24d1662bcc470a8449abcf Mon Sep 17 00:00:00 2001 From: Jonathan Tan Date: Wed, 26 Jul 2017 11:17:29 -0700 Subject: sub-process: refactor handshake to common function Refactor, into a common function, the version and capability negotiation done when invoking a long-running process as a clean or smudge filter. This will be useful for other Git code that needs to interact similarly with a long-running process. As you can see in the change to t0021, this commit changes the error message reported when the long-running process does not introduce itself with the expected "server"-terminated line. Originally, the error message reports that the filter "does not support filter protocol version 2", differentiating between the old single-file filter protocol and the new multi-file filter protocol - I have updated it to something more generic and useful. Signed-off-by: Jonathan Tan Signed-off-by: Junio C Hamano --- sub-process.h | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'sub-process.h') diff --git a/sub-process.h b/sub-process.h index e546216145..caa91a9b92 100644 --- a/sub-process.h +++ b/sub-process.h @@ -29,6 +29,16 @@ struct subprocess_entry { struct child_process process; }; +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; +}; + /* subprocess functions */ /* Function to test two subprocess hashmap entries for equality. */ @@ -62,6 +72,22 @@ static inline struct child_process *subprocess_get_child_process( return &entry->process; } +/* + * Perform the version and capability negotiation as described in the "Long + * Running Filter Process" section of the gitattributes documentation using the + * 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); + /* * Helper function that will read packets looking for "status=" * key/value pairs and return the value from the last "status" packet -- cgit v1.2.3