From: Brandon Williams <bmwill@google.com>
To: Jonathan Tan <jonathantanmy@google.com>
Cc: git@vger.kernel.org, jrnieder@gmail.com, peartben@gmail.com
Subject: Re: [PATCH v2 1/2] Documentation: migrate sub-process docs to header
Date: Tue, 25 Jul 2017 13:18:58 -0700 [thread overview]
Message-ID: <20170725201858.GJ92874@google.com> (raw)
In-Reply-To: <2d97d07a4977048a8147292ac13db48f5202d52f.1501007300.git.jonathantanmy@google.com>
On 07/25, Jonathan Tan wrote:
> 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>
I really like this change!
> ---
> Documentation/technical/api-sub-process.txt | 59 -----------------------------
> sub-process.h | 25 +++++++++++-
> 2 files changed, 23 insertions(+), 61 deletions(-)
> delete mode 100644 Documentation/technical/api-sub-process.txt
>
> diff --git a/Documentation/technical/api-sub-process.txt b/Documentation/technical/api-sub-process.txt
> deleted file mode 100644
> index 793508cf3..000000000
> --- a/Documentation/technical/api-sub-process.txt
> +++ /dev/null
> @@ -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.
> diff --git a/sub-process.h b/sub-process.h
> index 96a2cca36..9e6975b5e 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)
> {
> --
> 2.14.0.rc0.400.g1c36432dff-goog
>
--
Brandon Williams
next prev parent reply other threads:[~2017-07-25 20:19 UTC|newest]
Thread overview: 22+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-07-24 21:38 [PATCH] sub-process: refactor handshake to common function Jonathan Tan
2017-07-24 22:21 ` Jonathan Nieder
2017-07-25 14:38 ` Ben Peart
2017-07-25 17:53 ` Jonathan Tan
2017-07-25 18:29 ` [PATCH v2 0/2] " Jonathan Tan
2017-07-25 18:29 ` [PATCH v2 1/2] Documentation: migrate sub-process docs to header Jonathan Tan
2017-07-25 20:18 ` Brandon Williams [this message]
2017-07-25 18:29 ` [PATCH v2 2/2] sub-process: refactor handshake to common function Jonathan Tan
2017-07-25 20:28 ` Brandon Williams
2017-07-25 22:25 ` Junio C Hamano
2017-07-26 16:52 ` [PATCH] " Lars Schneider
2017-07-26 18:14 ` Junio C Hamano
2017-07-26 18:17 ` [PATCH for NEXT v3 0/2] " Jonathan Tan
2017-07-26 19:48 ` Junio C Hamano
2017-07-29 16:26 ` Junio C Hamano
2017-07-26 18:17 ` [PATCH for NEXT v3 1/2] Documentation: migrate sub-process docs to header Jonathan Tan
2017-07-26 18:17 ` [PATCH for NEXT v3 2/2] sub-process: refactor handshake to common function Jonathan Tan
2017-08-06 19:58 ` Lars Schneider
2017-08-07 17:21 ` Jonathan Tan
2017-08-07 17:51 ` Lars Schneider
2017-08-07 18:17 ` Jonathan Tan
2017-08-07 18:29 ` Ben Peart
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20170725201858.GJ92874@google.com \
--to=bmwill@google.com \
--cc=git@vger.kernel.org \
--cc=jonathantanmy@google.com \
--cc=jrnieder@gmail.com \
--cc=peartben@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).