concept pool in category go

appears as: pool, A pool
Go in Action

This is an excerpt from Manning's book Go in Action.

The purpose of the pool package is to show how you can use a buffered channel to pool a set of resources that can be shared and individually used by any number of goroutines. This pattern is useful when you have a static set of resources to share, such as database connections or memory buffers. When a goroutine needs one of these resources from the pool, it can acquire the resource, use it, and then return it to the pool.

Let’s take a look at the pool.go code file from the pool package.

Listing 7.14. pool/pool.go
01 // Example provided with help from Fatih Arslan and Gabriel Aszalos. 02 // Package pool manages a user defined set of resources. 03 package pool 04 05 import ( 06 "errors" 07 "log" 08 "io" 09 "sync" 10 ) 11 12 // Pool manages a set of resources that can be shared safely by 13 // multiple goroutines. The resource being managed must implement 14 // the io.Closer interface. 15 type Pool struct { 16 m sync.Mutex 17 resources chan io.Closer 18 factory func() (io.Closer, error) 19 closed bool 20 } 21 22 // ErrPoolClosed is returned when an Acquire returns on a 23 // closed pool. 24 var ErrPoolClosed = errors.New("Pool has been closed.") 25 26 // New creates a pool that manages resources. A pool requires a 27 // function that can allocate a new resource and the size of 28 // the pool. 29 func New(fn func() (io.Closer, error), size uint) (*Pool, error) { 30 if size <= 0 { 31 return nil, errors.New("Size value too small.") 32 } 33 34 return &Pool{ 35 factory: fn, 36 resources: make(chan io.Closer, size), 37 }, nil 38 } 39 40 // Acquire retrieves a resource from the pool. 41 func (p *Pool) Acquire() (io.Closer, error) { 42 select { 43 // Check for a free resource. 44 case r, ok := <-p.resources: 45 log.Println("Acquire:", "Shared Resource") 46 if !ok { 47 return nil, ErrPoolClosed 48 } 49 return r, nil 50 51 // Provide a new resource since there are none available. 52 default: 53 log.Println("Acquire:", "New Resource") 54 return p.factory() 55 } 56 } 57 58 // Release places a new resource onto the pool. 59 func (p *Pool) Release(r io.Closer) { 60 // Secure this operation with the Close operation. 61 p.m.Lock() 62 defer p.m.Unlock() 63 64 // If the pool is closed, discard the resource. 65 if p.closed { 66 r.Close() 67 return 68 } 69 70 select { 71 // Attempt to place the new resource on the queue. 72 case p.resources <- r: 73 log.Println("Release:", "In Queue") 74 75 // If the queue is already at capacity we close the resource. 76 default: 77 log.Println("Release:", "Closing") 78 r.Close() 79 } 80 } 81 82 // Close will shutdown the pool and close all existing resources. 83 func (p *Pool) Close() { 84 // Secure this operation with the Release operation. 85 p.m.Lock() 86 defer p.m.Unlock() 87 88 // If the pool is already closed, don't do anything. 89 if p.closed { 90 return 91 } 92 93 // Set the pool as closed. 94 p.closed = true 95 96 // Close the channel before we drain the channel of its 97 // resources. If we don't do this, we will have a deadlock. 98 close(p.resources) 99 100 // Close the resources 101 for r := range p.resources { 102 r.Close() 103 } 104 }

The code for the pool package in listing 7.14 declares a struct named Pool that allows the caller to create as many different pools as needed. Each pool can manage any type of resource as long as the type implements the io.Closer interface. Let’s take a look at the declaration of the Pool struct.

Listing 7.15. pool/pool.go: lines 12–20
12 // Pool manages a set of resources that can be shared safely by 13 // multiple goroutines. The resource being managed must implement 14 // the io.Closer interface. 15 type Pool struct { 16 m sync.Mutex 17 resources chan io.Closer 18 factory func() (io.Closer, error) 19 closed bool 20 }

The Pool struct declares four fields, each of which helps manage the pool in a goroutine-safe way. On line 16 the struct starts off with a field of type sync.Mutex. This mutex is used to keep all the operations against a Pool value-safe for multigoroutine access. The second field is named resources and is declared as a channel of interface type io.Closer. This channel will be created as a buffered channel and will contain the resources being shared. Because an interface type is being used, the pool can manage any type of resource that implements the io.Closer interface.

The factory field is of a function type. Any function that takes no parameters and returns an io.Closer and an error interface value can be assigned to this field. The purpose of this function is to create a new resource when the pool requires one. This functionality is an implementation detail beyond the scope of the pool package and needs to be implemented and supplied by the user using this package.