code review 44680043: sync: explain Pool's intentions

sync: explain Pool's intentions
Expand the type's doc comment to make its purpose clear
and discourage misuse.

[r, 2013-12-20 18:02:05]

Hello golang-codereviews@googlegroups.com,

I'd like you to review this change to
https://code.google.com/p/go/

[gobot, 2013-12-20 18:06:05]

R=rsc@golang.org (assigned by r@golang.org)

[rsc, 2013-12-20 18:13:46]

https://codereview.appspot.com/44680043/diff/20001/src/pkg/sync/pool.go
File src/pkg/sync/pool.go (right):

https://codereview.appspot.com/44680043/diff/20001/src/pkg/sync/pool.go#newco...
src/pkg/sync/pool.go:17: // Pool is not intended for general-purpose free lists.
Instead, its
i think i'd lead with what it's for instead of what it's not for.

some other minor tweaks (good/not appropriate -> appropriate/not appropriate; to
be shared -> shared)

// Pool's intended use is for free lists maintained in global variables,
typically accessed
// by multiple goroutines simultaneously. Using a Pool instead of, say, a list
allows the
// runtime to reclaim entries from the free list when it makes sense to do so.
// An appropriate use of sync.Pool is to create a pool of temporary buffers
shared between
// independent clients of a global resource. On the other hand, if a free list
is maintained
// as part of an object used only by a single client and freed when the client
completes,
// implementing that free list as a Pool is not appropriate.

[r, 2013-12-20 18:33:35]

Hello golang-codereviews@googlegroups.com, gobot@golang.org, rsc@golang.org (cc:
golang-codereviews@googlegroups.com),

Please take another look.

[rsc, 2013-12-20 19:09:51]

LGTM

https://codereview.appspot.com/44680043/diff/60001/src/pkg/sync/pool.go
File src/pkg/sync/pool.go (right):

https://codereview.appspot.com/44680043/diff/60001/src/pkg/sync/pool.go#newco...
src/pkg/sync/pool.go:20: // entries from the pool when it makes sense to do so. 
An
spacespace -> space

https://codereview.appspot.com/44680043/diff/60001/src/pkg/sync/pool.go#newco...
src/pkg/sync/pool.go:27: // This is an experimental package and might not be
released.
s/package/type/

[r, 2013-12-20 19:15:53]

*** Submitted as https://code.google.com/p/go/source/detail?r=d9681a334cc4 ***

sync: explain Pool's intentions
Expand the type's doc comment to make its purpose clear
and discourage misuse.

R=golang-codereviews, gobot, rsc
CC=golang-codereviews
https://codereview.appspot.com/44680043