code review 85880044: sync.Pool: better documentation

sync.Pool: better documentation
Explain what its purpose is and give examples of good and bad use.
Fixes issue 7167.

[r, 2014-04-09 06:55:07]

Hello golang-codereviews@googlegroups.com,

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

[dvyukov, 2014-04-09 07:32:41]

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

https://codereview.appspot.com/85880044/diff/40001/src/pkg/sync/pool.go#newco...
src/pkg/sync/pool.go:22: // Any item stored in the Pool may be removed (and
freed) automatically at
"and freed" may be confusing ("can it be freed if I hold another pointer to the
object?")
the current text is more precise in this regard

https://codereview.appspot.com/85880044/diff/40001/src/pkg/sync/pool.go#newco...
src/pkg/sync/pool.go:32: // An appropriate use of a Pool is to manage temporary
buffers silently
"buffers" looks too narrow
above you use term "items", and it looks more general

https://codereview.appspot.com/85880044/diff/40001/src/pkg/sync/pool.go#newco...
src/pkg/sync/pool.go:33: // shared among concurrent independent clients of a
global resource. Since
I do not understand why "global resource" is mentioned here.
If I do lots of concurrent fmt.Sprintf calls, what is the global shared resource
in such case?

The only necessary condition for Pool usage is that a set of concurrent
operations need a temporal item of the same type.

[r, 2014-04-09 08:33:16]

Hello golang-codereviews@googlegroups.com, dvyukov@google.com (cc:
golang-codereviews@googlegroups.com),

Please take another look.

[r, 2014-04-09 08:33:37]

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

https://codereview.appspot.com/85880044/diff/40001/src/pkg/sync/pool.go#newco...
src/pkg/sync/pool.go:22: // Any item stored in the Pool may be removed (and
freed) automatically at
On 2014/04/09 07:32:41, dvyukov wrote:
> "and freed" may be confusing ("can it be freed if I hold another pointer to
the
> object?")
> the current text is more precise in this regard

Done.

https://codereview.appspot.com/85880044/diff/40001/src/pkg/sync/pool.go#newco...
src/pkg/sync/pool.go:32: // An appropriate use of a Pool is to manage temporary
buffers silently
On 2014/04/09 07:32:41, dvyukov wrote:
> "buffers" looks too narrow
> above you use term "items", and it looks more general

Done.

https://codereview.appspot.com/85880044/diff/40001/src/pkg/sync/pool.go#newco...
src/pkg/sync/pool.go:33: // shared among concurrent independent clients of a
global resource. Since
Done, although I think it loses a bit of pedagogical clarity in this revision.

[dvyukov, 2014-04-09 10:07:01]

LGTM

[rsc, 2014-04-09 13:39:55]

LGTM

[r, 2014-04-09 19:45:30]

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

sync.Pool: better documentation
Explain what its purpose is and give examples of good and bad use.
Fixes issue 7167.

LGTM=dvyukov, rsc
R=golang-codereviews, dvyukov, rsc
CC=golang-codereviews
https://codereview.appspot.com/85880044