Re: [PATCH v2] strbuf doc: reuse after strbuf_release is fine
- Date: Wed, 04 Oct 2017 14:00:08 +0900
- From: Junio C Hamano <gitster@xxxxxxxxx>
- Subject: Re: [PATCH v2] strbuf doc: reuse after strbuf_release is fine
Jonathan Nieder <jrnieder@xxxxxxxxx> writes:
> strbuf_release leaves the strbuf in a valid, initialized state, so
> there is no need to call strbuf_init after it.
> Moreover, this is not likely to change in the future: strbuf_release
> leaving the strbuf in a valid state has been easy to maintain and has
> been very helpful for Git's robustness and simplicity (e.g.,
> preventing use-after-free vulnerabilities).
> Document the semantics so the next generation of Git developers can
> become familiar with them without reading the implementation. It is
> still not advisable to call strbuf_release too often because it is
> wasteful, so add a note pointing to strbuf_reset for that.
> The same semantics apply to strbuf_detach. Add a similar note to its
> docstring to make that clear.
> Improved-by: Jeff King <peff@xxxxxxxx>
> Signed-off-by: Jonathan Nieder <jrnieder@xxxxxxxxx>
> Jeff King wrote:
>> I think it's actually OK to use the string buffer after this function.
>> It's just an empty string.
>> Perhaps we should be more explicit: this releases any resources and
>> resets to a pristine, empty state. I suspect strbuf_detach() probably
>> should make the same claim.
> Like this?
Looks good to me.
> strbuf.h | 11 +++++++++--
> 1 file changed, 9 insertions(+), 2 deletions(-)
> diff --git a/strbuf.h b/strbuf.h
> index 7496cb8ec5..249df86711 100644
> --- a/strbuf.h
> +++ b/strbuf.h
> @@ -82,8 +82,12 @@ extern char strbuf_slopbuf;
> extern void strbuf_init(struct strbuf *, size_t);
> - * Release a string buffer and the memory it used. You should not use the
> - * string buffer after using this function, unless you initialize it again.
> + * Release a string buffer and the memory it used. After this call, the
> + * strbuf points to an empty string that does not need to be free()ed, as
> + * if it had been set to `STRBUF_INIT` and never modified.
> + *
> + * To clear a strbuf in preparation for further use without the overhead
> + * of free()ing and malloc()ing again, use strbuf_reset() instead.
> extern void strbuf_release(struct strbuf *);
> @@ -91,6 +95,9 @@ extern void strbuf_release(struct strbuf *);
> * Detach the string from the strbuf and returns it; you now own the
> * storage the string occupies and it is your responsibility from then on
> * to release it with `free(3)` when you are done with it.
> + *
> + * The strbuf that previously held the string is reset to `STRBUF_INIT` so
> + * it can be reused after calling this function.
> extern char *strbuf_detach(struct strbuf *, size_t *);