5824: Document ClientPool.

[arvados.git] / sdk / go / arvadosclient / pool.go

diff --git a/sdk/go/arvadosclient/pool.go b/sdk/go/arvadosclient/pool.go
index 1c5893aa319b82bcd5663d6bf22653c43c9afe6d..87b67c39b67c6f3ee95a165f9cc50f83ba5be3a7 100644 (file)
--- a/sdk/go/arvadosclient/pool.go
+++ b/sdk/go/arvadosclient/pool.go
@@ -4,11 +4,17 @@ import (
        "sync"
 )
 
+// A ClientPool is a pool of ArvadosClients. This is useful for
+// applications that make API calls using a dynamic set of tokens,
+// like web services that pass through their own clients'
+// credentials. See arvados-git-httpd for an example, and sync.Pool
+// for more information about garbage collection.
 type ClientPool struct {
        sync.Pool
        lastErr error
 }
 
+// MakeClientPool returns a new empty ClientPool.
 func MakeClientPool() *ClientPool {
        p := &ClientPool{}
        p.Pool = sync.Pool{New: func() interface{} {
@@ -22,10 +28,16 @@ func MakeClientPool() *ClientPool {
        return p
 }
 
+// Err returns the error that was encountered last time Get returned
+// nil.
 func (p *ClientPool) Err() error {
        return p.lastErr
 }
 
+// Get returns an ArvadosClient taken from the pool, or a new one if
+// the pool is empty. If an existing client is returned, its state
+// (including its ApiToken) will be just as it was when it was Put
+// back in the pool.
 func (p *ClientPool) Get() *ArvadosClient {
        c, ok := p.Pool.Get().(*ArvadosClient)
        if !ok {
@@ -34,6 +46,7 @@ func (p *ClientPool) Get() *ArvadosClient {
        return c
 }
 
+// Put puts an ArvadosClient back in the pool.
 func (p *ClientPool) Put(c *ArvadosClient) {
        p.Pool.Put(c)
 }