Documentation/technical/api-sub-process.txt

   1 sub-process API
   2 ===============
   3
   4 The sub-process API makes it possible to run background sub-processes
   5 for the entire lifetime of a Git invocation. If Git needs to communicate
   6 with an external process multiple times, then this can reduces the process
   7 invocation overhead. Git and the sub-process communicate through stdin and
   8 stdout.
   9
  10 The sub-processes are kept in a hashmap by command name and looked up
  11 via the subprocess_find_entry function.  If an existing instance can not
  12 be found then a new process should be created and started.  When the
  13 parent git command terminates, all sub-processes are also terminated.
  14
  15 This API is based on the run-command API.
  16
  17 Data structures
  18 ---------------
  19
  20 * `struct subprocess_entry`
  21
  22 The sub-process structure.  Members should not be accessed directly.
  23
  24 Types
  25 -----
  26
  27 'int(*subprocess_start_fn)(struct subprocess_entry *entry)'::
  28
  29         User-supplied function to initialize the sub-process.  This is
  30         typically used to negotiate the interface version and capabilities.
  31
  32
  33 Functions
  34 ---------
  35
  36 `cmd2process_cmp`::
  37
  38         Function to test two subprocess hashmap entries for equality.
  39
  40 `subprocess_start`::
  41
  42         Start a subprocess and add it to the subprocess hashmap.
  43
  44 `subprocess_stop`::
  45
  46         Kill a subprocess and remove it from the subprocess hashmap.
  47
  48 `subprocess_find_entry`::
  49
  50         Find a subprocess in the subprocess hashmap.
  51
  52 `subprocess_get_child_process`::
  53
  54         Get the underlying `struct child_process` from a subprocess.
  55
  56 `subprocess_read_status`::
  57
  58         Helper function to read packets looking for the last "status=<foo>"
  59         key/value pair.