From c46ba1f9efeb8efa6d8f513ec92f36ae1bfb8cd0 Mon Sep 17 00:00:00 2001 From: Michael Anthony Knyszek Date: Wed, 4 Dec 2024 19:33:26 +0000 Subject: [PATCH] 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 Reviewed-by: Carlos Amedee Auto-Submit: Michael Knyszek --- src/weak/doc.go | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/src/weak/doc.go b/src/weak/doc.go index e6fc9b63f875f2..84911e10ee29ce 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