Stowage/go
2
0
Fork 0
mirror of https://github.com/golang/go.git synced 2025-12-08 06:10:04 +00:00
Code Issues Projects Releases Packages Wiki Activity

weak: massage package docs a little bit

Browse source 
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>
This commit is contained in:
Michael Anthony Knyszek 2024-12-04 19:33:26 +00:00 • committed by Gopher Robot
parent 795d95d6ba
commit c46ba1f9ef
1 changed files with 13 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

20
src/weak/doc.go
View file

@ -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