Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit c46ba1f

Browse files
mknyszekgopherbot
authored andcommitted
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>
1 parent 795d95d commit c46ba1f

File tree

1 file changed

+13
-7
lines changed

1 file changed

+13
-7
lines changed

‎src/weak/doc.go

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,21 +6,27 @@
66
Package weak provides weak pointers with the goal of memory efficiency.
77
The primary use-cases for weak pointers are for implementing caches,
88
canonicalization maps (like the unique package), and for tying together
9-
the lifetimes of separate values.
9+
the lifetimes of separate values (for example, through a map with weak
10+
keys).
1011
1112
## Advice
1213
1314
This package is intended to target niche use-cases like the unique
14-
package, not as a general replacement for regular Go pointers, maps,
15-
etc.
16-
Misuse of the structures in this package will generate unexpected and
15+
package, and the structures inside are not intended to be general
16+
replacements for regular Go pointers, maps, etc.
17+
Misuse of the structures in this package may generate unexpected and
1718
hard-to-reproduce bugs.
1819
Using the facilities in this package to try and resolve out-of-memory
19-
issues and/or memory leaks is very likely the wrong answer.
20+
issues requires careful consideration, and even so, will likely be the
21+
wrong answer if the solution does not fall into one of the listed
22+
use-cases above.
2023
2124
The structures in this package are intended to be an implementation
2225
detail of the package they are used by (again, see the unique package).
23-
Avoid exposing weak structures across API boundaries, since that exposes
24-
users of your package to the subtleties of this package.
26+
If you're writing a package intended to be used by others, as a rule of
27+
thumb, avoid exposing the behavior of any weak structures in your package's
28+
API.
29+
Doing so will almost certainly make your package more difficult to use
30+
correctly.
2531
*/
2632
package weak

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /