diff options
| author | Michael Anthony Knyszek <mknyszek@google.com> | 2024-12-04 19:33:26 +0000 |
|---|---|---|
| committer | Gopher Robot <gobot@golang.org> | 2024-12-04 22:20:08 +0000 |
| commit | c46ba1f9efeb8efa6d8f513ec92f36ae1bfb8cd0 (patch) | |
| tree | 77cd4f1c3e52065a31055dd6d2b58e6367dd7449 /src | |
| parent | 795d95d6ba3f92091f55af81f8ee840048fb2499 (diff) | |
| download | go-c46ba1f9efeb8efa6d8f513ec92f36ae1bfb8cd0.tar.xz | |
weak: massage package docs a little bit
This is an attempt to clarify the "advice" section of the package docs a
little bit and encourage a specific style of use for weak structures.
It's not perfect, but it's something.
Change-Id: Id84b76d207619cc2e78439c5c903ec9575199734
Reviewed-on: https://go-review.googlesource.com/c/go/+/633675
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Carlos Amedee <carlos@golang.org>
Auto-Submit: Michael Knyszek <mknyszek@google.com>
Diffstat (limited to 'src')
| -rw-r--r-- | src/weak/doc.go | 20 |
1 files changed, 13 insertions, 7 deletions
diff --git a/src/weak/doc.go b/src/weak/doc.go index e6fc9b63f8..84911e10ee 100644 --- a/src/weak/doc.go +++ b/src/weak/doc.go @@ -6,21 +6,27 @@ Package weak provides weak pointers with the goal of memory efficiency. The primary use-cases for weak pointers are for implementing caches, canonicalization maps (like the unique package), and for tying together -the lifetimes of separate values. +the lifetimes of separate values (for example, through a map with weak +keys). ## Advice This package is intended to target niche use-cases like the unique -package, not as a general replacement for regular Go pointers, maps, -etc. -Misuse of the structures in this package will generate unexpected and +package, and the structures inside are not intended to be general +replacements for regular Go pointers, maps, etc. +Misuse of the structures in this package may generate unexpected and hard-to-reproduce bugs. Using the facilities in this package to try and resolve out-of-memory -issues and/or memory leaks is very likely the wrong answer. +issues requires careful consideration, and even so, will likely be the +wrong answer if the solution does not fall into one of the listed +use-cases above. The structures in this package are intended to be an implementation detail of the package they are used by (again, see the unique package). -Avoid exposing weak structures across API boundaries, since that exposes -users of your package to the subtleties of this package. +If you're writing a package intended to be used by others, as a rule of +thumb, avoid exposing the behavior of any weak structures in your package's +API. +Doing so will almost certainly make your package more difficult to use +correctly. */ package weak |