@matheusbsbs / matheus-bagliano / commits / e0222159fa

strbuf doc: reuse after strbuf_release is fine

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> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Jonathan Nieder committed Oct 3, 2017 at 19:39 UTC e0222159fa53ea24785cfb1dc5de0214e89b0117

1 file changed +9 -2

strbuf.h

+9 -2

@@ -82,8 +82,12 @@ extern char strbuf_slopbuf[];

82 extern void strbuf_init(struct strbuf *, size_t);

84 /**

85 - * Release a string buffer and the memory it used. You should not use the

86 - * string buffer after using this function, unless you initialize it again.

85 + * Release a string buffer and the memory it used. After this call, the

86 + * strbuf points to an empty string that does not need to be free()ed, as

87 + * if it had been set to `STRBUF_INIT` and never modified.

88 + *

89 + * To clear a strbuf in preparation for further use without the overhead

90 + * of free()ing and malloc()ing again, use strbuf_reset() instead.

91 */

92 extern void strbuf_release(struct strbuf *);

@@ -91,6 +95,9 @@ extern void strbuf_release(struct strbuf *);

95 * Detach the string from the strbuf and returns it; you now own the

96 * storage the string occupies and it is your responsibility from then on

97 * to release it with `free(3)` when you are done with it.

98 + *

99 + * The strbuf that previously held the string is reset to `STRBUF_INIT` so

100 + * it can be reused after calling this function.

101 */

102 extern char *strbuf_detach(struct strbuf *, size_t *);

103