objtonum

Documentation

Overview

Package objtonum allows to allocate and assign an integer number to an object. Object can be any abstract entity. In EVE this can be for example: edge application, network bridge, network interface, etc. The assigned numbers can be published/persisted.

Index

• Constants
• type AllocOpt
• type AllocStrategy
• type Allocator
  • func NewAllocator(log *base.LogObject, numAlloc NumberAllocator, storage Map) (*Allocator, error)
  • func (a *Allocator) AllocatedCount() (allocatedCount, reservedCount int)
  • func (a *Allocator) Free(key ObjKey, keepReserved bool) error
  • func (a *Allocator) FreeMultiple(selectKey ObjKeySelector, keepReserved bool) (err error)
  • func (a *Allocator) GC(createdBefore time.Time) error
  • func (a *Allocator) GetOrAllocate(key ObjKey, allocOpts ...AllocOpt) (number int, err error)
• type ByteAllocator
  • func NewByteAllocator(withZeroVal bool) *ByteAllocator
  • func (ba *ByteAllocator) Allocate(allocOpts ...AllocOpt) (number int, err error)
  • func (ba *ByteAllocator) Free(number int) error
  • func (ba *ByteAllocator) FreeAll() error
  • func (ba *ByteAllocator) IsAllocated(number int) bool
• type Map
• type MapIterFunc
• type NumberAllocator
• type ObjKey
• type ObjKeySelector
• type ObjNumContainer
• type ObjNumPublisher
  • func NewObjNumPublisher(log *base.LogObject, ps *pubsub.PubSub, agentName string, persisted bool, ...) (*ObjNumPublisher, error)
  • func (p *ObjNumPublisher) Close() error
  • func (p *ObjNumPublisher) Get(key ObjKey) (ObjNumContainer, error)
  • func (p *ObjNumPublisher) GetAll() []ObjNumContainer
  • func (p *ObjNumPublisher) PrepareContainer(key ObjKey) ObjNumContainer
  • func (p *ObjNumPublisher) Publish(objNum ObjNumContainer) error
  • func (p *ObjNumPublisher) Unpublish(key ObjKey) error
• type PublishedMap
  • func NewPublishedMap(log *base.LogObject, publisher *ObjNumPublisher, numberType string, ...) *PublishedMap
  • func (pb *PublishedMap) Assign(key ObjKey, number int, exclusively bool) error
  • func (pb *PublishedMap) Delete(key ObjKey, keepReserved bool) error
  • func (pb *PublishedMap) Get(key ObjKey) (number int, reservedOnly bool, err error)
  • func (pb *PublishedMap) Iterate(callback MapIterFunc)
• type RequireNumber

Constants

const ByteAllocatorMaxNum = 255

ByteAllocatorMaxNum : maximum number that can be allocated with ByteAllocator.

Types

type AllocOpt

type AllocOpt interface {
	// contains filtered or unexported methods
}

AllocOpt allows to customize the process of number allocation.

type AllocStrategy

type AllocStrategy int

AllocStrategy : strategy to follow by NumberAllocator when allocating a number.

const (
	// LowestFree : select smallest free number.
	LowestFree AllocStrategy = iota
	// HighestFree : select highest free number.
	HighestFree
	// RandomFree : randomly select one of the free numbers.
	RandomFree
)

type Allocator

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

Allocator allocates and maps *unique* numbers to objects.

func NewAllocator

func NewAllocator(log *base.LogObject, numAlloc NumberAllocator, storage Map) (*Allocator, error)

NewAllocator creates new Allocator. Allocated Object->Number pairs are stored inside the given map. Allocator becomes sole owner of the map (it should not be manipulated outside the allocator or used for another allocator)

func (*Allocator) AllocatedCount

func (a *Allocator) AllocatedCount() (allocatedCount, reservedCount int)

AllocatedCount returns the count of allocated and reserved-only object numbers.

func (*Allocator) Free

func (a *Allocator) Free(key ObjKey, keepReserved bool) error

Free either fully removes number from an object, or keeps the pair but marks it as reserved. Note that reserved number will be used by the next GetOrAllocate for this object, but a reservation may as well be removed when allocator runs out of numbers to allocate from.

func (*Allocator) FreeMultiple

func (a *Allocator) FreeMultiple(selectKey ObjKeySelector, keepReserved bool) (err error)

FreeMultiple applies Free operation on a subset of objects.

func (*Allocator) GC

func (a *Allocator) GC(createdBefore time.Time) error

GC = garbage collection. The function removes all reservations (not full allocations) that originated from before the given time.

func (*Allocator) GetOrAllocate

func (a *Allocator) GetOrAllocate(key ObjKey, allocOpts ...AllocOpt) (number int, err error)

GetOrAllocate returns for a given object either an already allocated/reserved number or allocates a new one. Previously reserved number becomes fully allocated. If there is no free number left but there are some reserved, it will steal number from the oldest reservation.

type ByteAllocator

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

ByteAllocator allocates numbers from the range <0,255> or <1,255>.

func NewByteAllocator

func NewByteAllocator(withZeroVal bool) *ByteAllocator

NewByteAllocator is a constructor for ByteAllocator.

func (*ByteAllocator) Allocate

func (ba *ByteAllocator) Allocate(allocOpts ...AllocOpt) (number int, err error)

Allocate tries to allocate a new number.

func (*ByteAllocator) Free

func (ba *ByteAllocator) Free(number int) error

Free marks the number as available for future allocation.

func (*ByteAllocator) FreeAll

func (ba *ByteAllocator) FreeAll() error

FreeAll marks all numbers in the set as free for allocation.

func (*ByteAllocator) IsAllocated

func (ba *ByteAllocator) IsAllocated(number int) bool

IsAllocated returns true if the given number is already allocated.

type Map

type Map interface {
	// Get returns number assigned to the given object.
	Get(ObjKey) (number int, reservedOnly bool, err error)
	// Assign either adds new Object->Number pair into the map or modifies number
	// assigned to the given object.
	// Disallow modification by requesting exclusive assignment.
	// Removes reserved-only flag from the assigned number.
	// Assign also causes update of "lastUpdatedAt" timestamp stored alongside the number.
	Assign(key ObjKey, number int, exclusively bool) error
	// Delete either fully removes Object->Number pair from the map,
	// or just marks the number as only reserved if keepReserved is true.
	Delete(key ObjKey, keepReserved bool) error
	// Iterate over every Object->Number pair stored in the map.
	// It is safe to Delete pair during iteration.
	Iterate(MapIterFunc)
}

Map maps numbers (integers) to objects (can be anything that can be referenced using ObjKey).

type MapIterFunc

type MapIterFunc func(key ObjKey, number int, onlyReserved bool,
	createdAt, lastUpdatedAt time.Time) (stop bool)

MapIterFunc is a callback applied to every Object->Number pair inside the Map during iteration. Return stop as true to terminate the iteration.

type NumberAllocator

type NumberAllocator interface {
	// IsAllocated returns true if the given number is already allocated.
	IsAllocated(number int) bool
	// Allocate tries to allocate a new number.
	// Returns error if there is are no numbers left to allocate from
	// or allocOpts cannot be satisfied.
	Allocate(allocOpts ...AllocOpt) (number int, err error)
	// Free marks the number as available for future allocation.
	Free(number int) error
	// FreeAll marks all numbers in the set as free for allocation.
	FreeAll() error
}

NumberAllocator allows to allocate a not yet allocated number from a set of integers.

type ObjKey

type ObjKey interface {
	// Key returns string representation of the key.
	Key() string
}

ObjKey is a key uniquely referencing an object.

type ObjKeySelector

type ObjKeySelector func(ObjKey) bool

ObjKeySelector is function that selects a subset of keys. To select a given key it should return true, false otherwise.

var AllKeys ObjKeySelector = func(ObjKey) bool { return true }

AllKeys selects all keys.

type ObjNumContainer

type ObjNumContainer interface {
	// New is a constructor for the ObjNumContainer.
	// New works even when the method receiver is nil.
	New(ObjKey) ObjNumContainer
	// GetKey returns the key of the object whose number is stored by this container.
	GetKey() ObjKey
	// SetNumber updates the number stored by the container.
	// numberType can give a semantic label to the number. It allows to reuse the same
	// pubsub topic (ObjNumContainer) for multiple semantically different mappings.
	// Additionally, the method updates <lastUpdatedAt> timestamp, which can be obtained
	// using GetTimestamps.
	SetNumber(number int, numberType string)
	// GetNumber returns number stored by the container.
	GetNumber() (number int, numberType string)
	// GetTimestamps returns time when the container was created and also time when
	// the stored number or the reserved flag was last changed.
	GetTimestamps() (createdAt time.Time, lastUpdatedAt time.Time)
	// SetReservedOnly allows to change the reservation status.
	// Number is either fully assigned to the object or just reserved for a potential
	// future assignment to this object.
	SetReservedOnly(reservedOnly bool)
	// IsReservedOnly returns true if the number is only reserved.
	IsReservedOnly() bool
}

ObjNumContainer is used by ObjNumPublisher to store and publish number assigned to an object.

type ObjNumPublisher

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

ObjNumPublisher is used by PublishedMap to publish Object->Number pairs.

func NewObjNumPublisher

func NewObjNumPublisher(log *base.LogObject, ps *pubsub.PubSub, agentName string,
	persisted bool, objNumCont ObjNumContainer) (*ObjNumPublisher, error)

NewObjNumPublisher is a constructor for ObjNumPublisher

func (*ObjNumPublisher) Close

func (p *ObjNumPublisher) Close() error

Close publisher and the pubsub channel.

func (*ObjNumPublisher) Get

func (p *ObjNumPublisher) Get(key ObjKey) (ObjNumContainer, error)

Get returns last published number for the given object or error if nothing is currently published under this object key.

func (*ObjNumPublisher) GetAll

func (p *ObjNumPublisher) GetAll() []ObjNumContainer

GetAll returns all object numbers currently published inside the pubsub topic.

func (*ObjNumPublisher) PrepareContainer

func (p *ObjNumPublisher) PrepareContainer(key ObjKey) ObjNumContainer

PrepareContainer returns a new container to later store inside and publish an assigned object number.

func (*ObjNumPublisher) Publish

func (p *ObjNumPublisher) Publish(objNum ObjNumContainer) error

Publish publishes the given object number into the pubsub topic.

func (*ObjNumPublisher) Unpublish

func (p *ObjNumPublisher) Unpublish(key ObjKey) error

Unpublish removes number currently published for the given object from the pubsub topic.

type PublishedMap

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

PublishedMap implements (potentially persisted) objtonum.Map using a pubsub publication.

func NewPublishedMap

func NewPublishedMap(log *base.LogObject, publisher *ObjNumPublisher,
	numberType string, usedFor ObjKeySelector) *PublishedMap

NewPublishedMap is a constructor for PublishedMap. PublishedMap publishes map updates using the provided ObjNumPublisher. Multiple PublishedMap can use the same publisher provided that their numberType-s are different or, if they publish numbers of the same type, usedFor key selectors must select disjoint sets of keys.

func (*PublishedMap) Assign

func (pb *PublishedMap) Assign(key ObjKey, number int, exclusively bool) error

Assign either adds new Object->Number pair into the map or modifies number assigned to the given object. Disallow modification by requesting exclusive assignment. Removes reserved-only flag from the assigned number. Assign also causes update of lastUpdatedAt timestamp stored alongside the number.

func (*PublishedMap) Delete

func (pb *PublishedMap) Delete(key ObjKey, keepReserved bool) error

Delete either fully removes Object->Number pair from the map, or just marks the number as only reserved if keepReserved is true.

func (*PublishedMap) Get

func (pb *PublishedMap) Get(key ObjKey) (number int, reservedOnly bool, err error)

Get returns number assigned to the given object.

func (*PublishedMap) Iterate

func (pb *PublishedMap) Iterate(callback MapIterFunc)

Iterate over every Object->Number pair stored in the map.

type RequireNumber

type RequireNumber struct {
	Number int
}

RequireNumber : tries to specifically allocate the given number. Will fail if this number is already allocated.