Add comments for workspace.

groupcache.go

@@ -68,7 +68,7 @@ func (f GetterFunc) Get(ctx context.Context, key string, dest Sink) error {
 	return f(ctx, key, dest)
 }
 
-// GetGroup returns the named group previously created with NewGroup, or
+// GetGroupWithWorkspace returns the named group previously created with NewGroup, or
 // nil if there's no such group.
 func GetGroupWithWorkspace(ws *workspace, name string) *Group {
 	ws.mu.RLock()
@@ -83,7 +83,7 @@ func GetGroup(name string) *Group {
 	return GetGroupWithWorkspace(DefaultWorkspace, name)
 }
 
-// NewGroup creates a coordinated group-aware Getter from a Getter.
+// NewGroupWithWorkspace creates a coordinated group-aware Getter from a Getter.
 //
 // The returned Getter tries (but does not guarantee) to run only one
 // Get call at once for a given key across an entire set of peer
@@ -109,7 +109,7 @@ func NewGroup(name string, cacheBytes int64, getter Getter) *Group {
 	return newGroup(DefaultWorkspace, name, cacheBytes, getter, nil)
 }
 
-// DeregisterGroup removes group from group pool
+// DeregisterGroupWithWorkspace removes group from group pool
 func DeregisterGroupWithWorkspace(ws *workspace, name string) {
 	ws.mu.Lock()
 	delete(ws.groups, name)
@@ -149,7 +149,7 @@ func newGroup(ws *workspace, name string, cacheBytes int64, getter Getter, peers
 	return g
 }
 
-// RegisterNewGroupHook registers a hook that is run each time
+// RegisterNewGroupHookWithWorkspace registers a hook that is run each time
 // a group is created.
 func RegisterNewGroupHookWithWorkspace(ws *workspace, fn func(*Group)) {
 	if ws.newGroupHook != nil {
@@ -164,7 +164,7 @@ func RegisterNewGroupHook(fn func(*Group)) {
 	RegisterNewGroupHookWithWorkspace(DefaultWorkspace, fn)
 }
 
-// RegisterServerStart registers a hook that is run when the first
+// RegisterServerStartWithWorkspace registers a hook that is run when the first
 // group is created.
 func RegisterServerStartWithWorkspace(ws *workspace, fn func()) {
 	if ws.initPeerServer != nil {

workspace.go

@@ -2,6 +2,7 @@ package groupcache
 
 import "sync"
 
+// workspace holds the "global" state for groupcache.
 type workspace struct {
 	httpPoolMade bool
 	portPicker   func(groupName string) PeerPicker
@@ -16,8 +17,17 @@ type workspace struct {
 	newGroupHook func(*Group)
 }
 
+// DefaultWorkspace is the default workspace used by non-workspace-aware APIs.
+// If your application does not need to recreate groupcache resources,
+// you should use the non-workspace-aware APIs.
+// This is likely the most common case.
 var DefaultWorkspace = NewWorkspace()
 
+// NewWorkspace creates an explicit workspace for workspace-aware APIs.
+// If your application needs to recreate groupcache resources at some
+// point, you should use the workspace-aware APIs.
+// In order to release current groupcache resources, your application
+// would drop all references to the workspace.
 func NewWorkspace() *workspace {
 	return &workspace{
 		groups: make(map[string]*Group),