sub-process.h

   1 #ifndef SUBPROCESS_H
   2 #define SUBPROCESS_H
   3
   4 #include "hashmap.h"
   5 #include "run-command.h"
   6
   7 /*
   8  * The sub-process API makes it possible to run background sub-processes
   9  * for the entire lifetime of a Git invocation. If Git needs to communicate
  10  * with an external process multiple times, then this can reduces the process
  11  * invocation overhead. Git and the sub-process communicate through stdin and
  12  * stdout.
  13  *
  14  * The sub-processes are kept in a hashmap by command name and looked up
  15  * via the subprocess_find_entry function.  If an existing instance can not
  16  * be found then a new process should be created and started.  When the
  17  * parent git command terminates, all sub-processes are also terminated.
  18  *
  19  * This API is based on the run-command API.
  20  */
  21
  22  /* data structures */
  23
  24 /* Members should not be accessed directly. */
  25 struct subprocess_entry {
  26         struct hashmap_entry ent;
  27         const char *cmd;
  28         struct child_process process;
  29 };
  30
  31 struct subprocess_capability {
  32         const char *name;
  33
  34         /*
  35          * subprocess_handshake will "|=" this value to supported_capabilities
  36          * if the server reports that it supports this capability.
  37          */
  38         unsigned int flag;
  39 };
  40
  41 /* subprocess functions */
  42
  43 /* Function to test two subprocess hashmap entries for equality. */
  44 int cmd2process_cmp(const void *unused_cmp_data,
  45                     const struct hashmap_entry *e,
  46                     const struct hashmap_entry *entry_or_key,
  47                     const void *unused_keydata);
  48
  49 /*
  50  * User-supplied function to initialize the sub-process.  This is
  51  * typically used to negotiate the interface version and capabilities.
  52  */
  53 typedef int(*subprocess_start_fn)(struct subprocess_entry *entry);
  54
  55 /* Start a subprocess and add it to the subprocess hashmap. */
  56 int subprocess_start(struct hashmap *hashmap, struct subprocess_entry *entry, const char *cmd,
  57                 subprocess_start_fn startfn);
  58
  59 /* Kill a subprocess and remove it from the subprocess hashmap. */
  60 void subprocess_stop(struct hashmap *hashmap, struct subprocess_entry *entry);
  61
  62 /* Find a subprocess in the subprocess hashmap. */
  63 struct subprocess_entry *subprocess_find_entry(struct hashmap *hashmap, const char *cmd);
  64
  65 /* subprocess helper functions */
  66
  67 /* Get the underlying `struct child_process` from a subprocess. */
  68 static inline struct child_process *subprocess_get_child_process(
  69                 struct subprocess_entry *entry)
  70 {
  71         return &entry->process;
  72 }
  73
  74 /*
  75  * Perform the version and capability negotiation as described in the
  76  * "Handshake" section of long-running-process-protocol.txt using the
  77  * given requested versions and capabilities. The "versions" and "capabilities"
  78  * parameters are arrays terminated by a 0 or blank struct.
  79  *
  80  * This function is typically called when a subprocess is started (as part of
  81  * the "startfn" passed to subprocess_start).
  82  */
  83 int subprocess_handshake(struct subprocess_entry *entry,
  84                          const char *welcome_prefix,
  85                          int *versions,
  86                          int *chosen_version,
  87                          struct subprocess_capability *capabilities,
  88                          unsigned int *supported_capabilities);
  89
  90 /*
  91  * Helper function that will read packets looking for "status=<foo>"
  92  * key/value pairs and return the value from the last "status" packet
  93  */
  94
  95 int subprocess_read_status(int fd, struct strbuf *status);
  96
  97 #endif