From dc8572c3fe1d77378a6deff2f05a4e04ae5061a8 Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Fri, 20 Dec 2013 11:15:50 -0800 Subject: [PATCH] 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 --- src/pkg/sync/pool.go | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) 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 -- 2.48.1