From: Jonathan Nieder <jrnieder@gmail.com>
To: Jeff King <peff@peff.net>
Cc: Stefan Beller <sbeller@google.com>,
git@vger.kernel.org, Junio C Hamano <gitster@pobox.com>
Subject: [PATCH v2] strbuf doc: reuse after strbuf_release is fine
Date: Tue, 3 Oct 2017 19:39:54 -0700 [thread overview]
Message-ID: <20171004023954.GK19555@aiede.mtv.corp.google.com> (raw)
In-Reply-To: <20171003234919.qsr54ncmw6cihowi@sigill.intra.peff.net>
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@peff.net>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
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?
Thanks,
Jonathan
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 *);
--
2.14.2.920.gcf0c67979c
next prev parent reply other threads:[~2017-10-04 2:40 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-10-03 21:14 [PATCH] branch: reset instead of release a strbuf Stefan Beller
2017-10-03 21:46 ` Jonathan Nieder
2017-10-03 22:17 ` Stefan Beller
2017-10-03 22:24 ` Jonathan Nieder
2017-10-03 23:49 ` Jeff King
2017-10-04 2:19 ` Junio C Hamano
2017-10-04 2:39 ` Jonathan Nieder [this message]
2017-10-04 5:00 ` [PATCH v2] strbuf doc: reuse after strbuf_release is fine Junio C Hamano
2017-10-04 5:27 ` Jeff King
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=20171004023954.GK19555@aiede.mtv.corp.google.com \
--to=jrnieder@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=peff@peff.net \
--cc=sbeller@google.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).