idpool

Documentation

Index

• type ID
  • func (i ID) String() string
• type IDPool
  • func NewIDPool(minID ID, maxID ID) *IDPool
  • func (p *IDPool) AllocateID() ID
  • func (p *IDPool) Insert(id ID) bool
  • func (p *IDPool) LeaseAvailableID() ID
  • func (p *IDPool) Release(id ID) bool
  • func (p *IDPool) Remove(id ID) bool
  • func (p *IDPool) Use(id ID) bool

Types

type ID

type ID uint64

ID is a numeric identifier

const NoID ID = 0

NoID is a special ID that represents "no ID available"

func (ID) String

func (i ID) String() string

String returns the string representation of an allocated ID

type IDPool

type IDPool struct {
	// contains filtered or unexported fields
}

IDPool represents a pool of IDs that can be managed concurrently via local usage and external events.

An intermediate state (leased) is introduced to the life cycle of an ID in the pool, in order to prevent lost updates to the pool that can occur as a result of employing both management schemes simultaneously. Local usage of an ID becomes a two stage process of leasing the ID from the pool, and later, Use()ing or Release()ing the ID on the pool upon successful or unsuccessful usage respectively,

The table below shows the state transitions in the ID's life cycle. In the case of LeaseAvailableID() the ID is returned rather than provided as an input to the operation. All ID's begin in the available state.

--------------------------------------------------------------------- |state\event | LeaseAvailableID | Release | Use | Insert | Remove | --------------------------------------------------------------------- |1 available | 2 | * | * | * | 3 | --------------------------------------------------------------------- |2 leased | ** | 1 | 3 | * | 3 | --------------------------------------------------------------------- |3 unavailable | ** | * | * | 1 | * | --------------------------------------------------------------------- * The event has no effect. ** This is guaranteed never to occur.

func NewIDPool

func NewIDPool(minID ID, maxID ID) *IDPool

NewIDPool returns a new ID pool

func (*IDPool) AllocateID

func (p *IDPool) AllocateID() ID

AllocateID returns a random available ID. Unlike LeaseAvailableID, the ID is immediately marked for use and there is no need to call Use().

func (*IDPool) Insert

func (p *IDPool) Insert(id ID) bool

Insert makes an unavailable ID available in the pool and has no effect otherwise. Returns true if the ID was added back to the pool.

func (*IDPool) LeaseAvailableID

func (p *IDPool) LeaseAvailableID() ID

LeaseAvailableID returns an available ID at random from the pool. Returns an ID or NoID if no there is no available ID in the pool.

func (*IDPool) Release

func (p *IDPool) Release(id ID) bool

Release returns a leased ID back to the pool. This operation accounts for IDs that were previously leased from the pool but were unused, e.g if allocation was unsuccessful. Thus, it has no effect if the ID is not currently leased in the pool, or the pool has since been refreshed.

Returns true if the ID was returned back to the pool as a result of this call.

func (*IDPool) Remove

func (p *IDPool) Remove(id ID) bool

Remove makes an ID unavailable in the pool. Returns true if the ID was previously available in the pool.

func (*IDPool) Use

func (p *IDPool) Use(id ID) bool

Use makes a leased ID unavailable in the pool and has no effect otherwise. Returns true if the ID was made unavailable as a result of this call.