From 35170365c83085024e4855c14032599f5513d563 Mon Sep 17 00:00:00 2001 From: Martin Sucha Date: Tue, 22 Feb 2022 21:51:04 +0100 Subject: [PATCH] net: document methods of Buffers There is code in the wild that copies the Buffers slice, but not the contents. Let's document explicitly that it is not safe to do so. Updates #45163 Change-Id: Id45e27b93037d4e9f2bfde2558e7869983b60bcf Reviewed-on: https://go-review.googlesource.com/c/go/+/387434 Reviewed-by: Ian Lance Taylor Run-TryBot: Ian Lance Taylor TryBot-Result: Gopher Robot Reviewed-by: Damien Neil --- src/net/net.go | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/net/net.go b/src/net/net.go index 77e54a9125..d91e743a01 100644 --- a/src/net/net.go +++ b/src/net/net.go @@ -703,6 +703,12 @@ var ( _ io.Reader = (*Buffers)(nil) ) +// WriteTo writes contents of the buffers to w. +// +// WriteTo implements io.WriterTo for Buffers. +// +// WriteTo modifies the slice v as well as v[i] for 0 <= i < len(v), +// but does not modify v[i][j] for any i, j. func (v *Buffers) WriteTo(w io.Writer) (n int64, err error) { if wv, ok := w.(buffersWriter); ok { return wv.writeBuffers(v) @@ -719,6 +725,12 @@ func (v *Buffers) WriteTo(w io.Writer) (n int64, err error) { return n, nil } +// Read from the buffers. +// +// Read implements io.Reader for Buffers. +// +// Read modifies the slice v as well as v[i] for 0 <= i < len(v), +// but does not modify v[i][j] for any i, j. func (v *Buffers) Read(p []byte) (n int, err error) { for len(p) > 0 && len(*v) > 0 { n0 := copy(p, (*v)[0]) -- 2.50.0