shithub: furgit

Info  •  Files  •  Log  •  Branches

bufpool: Document how .Bytes is intended to be used

--- a/internal/bufpool/buffers.go

+++ b/internal/bufpool/buffers.go

@@ -25,6 +25,12 @@

 // Buffers must not be copied after first use; doing so can cause double-returns

 // to the pool and data races.

 //

+// In general, pass Buffer around when used internally, and directly .Bytes() when

+// returning output across our API boundary. It is neither necessary nor efficient

+// to copy/append the .Bytes() to a newly-allocated slice; in cases where we do

+// want the raw byte slice out of our API boundary, it is perfectly acceptable to

+// simply not call Release().

+//

 //go:nocopy

 type Buffer struct {

 	_    struct{} // for nocopy

-- 

⑨