mirror/ git
1
0
Fork 0
mirror of https://github.com/git/git.git synced 2024-04-28 12:05:28 +02:00
Code

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 <jonathantanmy@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Jonathan Tan 2017-07-26 11:17:28 -07:00 committed by Junio C Hamano
parent 487fe1ffcd
commit 7e2e1bbb24
2 changed files with 23 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
Documentation/technical/api-sub-process.txt
View File

@ -1,59 +0,0 @@
sub-process API
===============
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
---------------
* `struct subprocess_entry`
The sub-process structure. Members should not be accessed directly.
Types
-----
'int(*subprocess_start_fn)(struct subprocess_entry *entry)'::
User-supplied function to initialize the sub-process. This is
typically used to negotiate the interface version and capabilities.
Functions
---------
`cmd2process_cmp`::
Function to test two subprocess hashmap entries for equality.
`subprocess_start`::
Start a subprocess and add it to the subprocess hashmap.
`subprocess_stop`::
Kill a subprocess and remove it from the subprocess hashmap.
`subprocess_find_entry`::
Find a subprocess in the subprocess hashmap.
`subprocess_get_child_process`::
Get the underlying `struct child_process` from a subprocess.
`subprocess_read_status`::
Helper function to read packets looking for the last "status=<foo>"
key/value pair.

25
sub-process.h
View File

@ -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)
{