From: Rob Pike <r@golang.org>
Date: Fri, 20 Dec 2013 19:15:50 +0000 (-0800)
Subject: sync: explain Pool's intentions
X-Git-Tag: go1.3beta1~1124
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=dc8572c3fe1d77378a6deff2f05a4e04ae5061a8;p=gostls13.git

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://golang.org/cl/44680043
---

diff --git a/src/pkg/sync/pool.go b/src/pkg/sync/pool.go
index 3facba98fa..9eb07c3a03 100644
--- a/src/pkg/sync/pool.go
+++ b/src/pkg/sync/pool.go
@@ -14,7 +14,17 @@ package sync
 //
 // A Pool is safe for use by multiple goroutines simultaneously.
 //
-// This is an experimental package and might not be released.
+// Pool's intended use is for free lists maintained in global variables,
+// typically accessed by multiple goroutines simultaneously. Using a
+// Pool instead of a custom free list allows the runtime to reclaim
+// entries from the pool 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.
+//
+// This is an experimental type and might not be released.
 type Pool struct {
 	next *Pool         // for use by runtime. must be first.
 	list []interface{} // offset known to runtime