diff options
| author | Michael Anthony Knyszek <mknyszek@google.com> | 2020-12-07 15:03:51 +0000 |
|---|---|---|
| committer | Michael Knyszek <mknyszek@google.com> | 2020-12-10 21:08:17 +0000 |
| commit | e0d20e52ee00fdf197f359d98526ff7ca0842e6b (patch) | |
| tree | fc0392864116c9305cb8c5854e0762d9078f60e3 | |
| parent | d0f40d29223a2aef58475f81a559b2d27396134a (diff) | |
| download | go-e0d20e52ee00fdf197f359d98526ff7ca0842e6b.tar.gz go-e0d20e52ee00fdf197f359d98526ff7ca0842e6b.zip | |
runtime/metrics: expand Read documention with caveats
This change modifies the documentation of Read with some caveats about
reusing the slice passed in to Read as well as with what concurrent
situations are safe.
Change-Id: I76fd31acc67ae384546a8442dfbf9d16b7445cff
Reviewed-on: https://go-review.googlesource.com/c/go/+/275853
Run-TryBot: Michael Knyszek <mknyszek@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Trust: Michael Knyszek <mknyszek@google.com>
Reviewed-by: Michael Pratt <mpratt@google.com>
| -rw-r--r-- | src/runtime/metrics/sample.go | 10 |
1 files changed, 10 insertions, 0 deletions
diff --git a/src/runtime/metrics/sample.go b/src/runtime/metrics/sample.go index 60189cb334..35534dd70d 100644 --- a/src/runtime/metrics/sample.go +++ b/src/runtime/metrics/sample.go @@ -30,6 +30,16 @@ func runtime_readMetrics(unsafe.Pointer, int, int) // The user of this API is encouraged to re-use the same slice between calls for // efficiency, but is not required to do so. // +// Note that re-use has some caveats. Notably, Values should not be read or +// manipulated while a Read with that value is outstanding; that is a data race. +// This property includes pointer-typed Values (e.g. Float64Histogram) whose +// underlying storage will be reused by Read when possible. To safely use such +// values in a concurrent setting, all data must be deep-copied. +// +// It is safe to execute multiple Read calls concurrently, but their arguments +// must share no underlying memory. When in doubt, create a new []Sample from +// scratch, which is always safe, though may be inefficient. +// // Sample values with names not appearing in All will have their Value populated // as KindBad to indicate that the name is unknown. func Read(m []Sample) { |