herocache

Documentation

Index

• Constants
• type Cache
  • func NewCache(sizeLimit uint32, oversizeFactor uint32, ejectionMode heropool.EjectionMode, ...) *Cache
  • func (c *Cache) Add(entityID flow.Identifier, entity flow.Entity) bool
  • func (c *Cache) Adjust(entityID flow.Identifier, f func(flow.Entity) flow.Entity) (flow.Entity, bool)
  • func (c *Cache) AdjustWithInit(entityID flow.Identifier, adjust func(flow.Entity) flow.Entity, ...) (flow.Entity, bool)
  • func (c *Cache) All() map[flow.Identifier]flow.Entity
  • func (c *Cache) ByID(entityID flow.Identifier) (flow.Entity, bool)
  • func (c *Cache) Clear()
  • func (c *Cache) Entities() []flow.Entity
  • func (c *Cache) GetWithInit(entityID flow.Identifier, init func() flow.Entity) (flow.Entity, bool)
  • func (c *Cache) Has(entityID flow.Identifier) bool
  • func (c *Cache) Head() (flow.Entity, bool)
  • func (c *Cache) Identifiers() flow.IdentifierList
  • func (c *Cache) Remove(entityID flow.Identifier) (flow.Entity, bool)
  • func (c *Cache) Size() uint
• type CacheOpt
  • func WithTracer(t Tracer) CacheOpt
• type Tracer

Constants

const DefaultOversizeFactor = uint32(8)

DefaultOversizeFactor determines the default oversizing factor of HeroCache. What is oversize factor? Imagine adding n keys, rounds times to a hash table with a fixed number slots per bucket. The number of buckets can be chosen upon initialization and then never changes. If a bucket is full then the oldest key is ejected, and if that key is too new, this is a bucket overflow. How many buckets are needed to avoid a bucket overflow assuming cryptographic key hashing is used? The overSizeFactor is used to determine the number of buckets. Assume n 16, rounds 3, & slotsPerBucket 3 for the tiny example below showing overSizeFactor 1 thru 6. As overSizeFactor is increased the chance of overflowing a bucket is decreased. With overSizeFactor 1: 8 from 48 keys can be added before bucket overflow. With overSizeFactor 2: 10 from 48 keys can be added before bucket overflow. With overSizeFactor 3: 13 from 48 keys can be added before bucket overflow. With overSizeFactor 4: 15 from 48 keys can be added before bucket overflow. With overSizeFactor 5: 27 from 48 keys can be added before bucket overflow. With overSizeFactor 6: 48 from 48 keys can be added. The default overSizeFactor factor is different in the package code because slotsPerBucket is > 3.

Types

type Cache

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

Cache implements an array-based generic memory pool backed by a fixed total array. Note that this implementation is NOT thread-safe, and the higher-level Backend is responsible for concurrency management.

func NewCache

func NewCache(
	sizeLimit uint32,
	oversizeFactor uint32,
	ejectionMode heropool.EjectionMode,
	logger zerolog.Logger,
	collector module.HeroCacheMetrics,
	opts ...CacheOpt,
) *Cache

func (*Cache) Add

func (c *Cache) Add(entityID flow.Identifier, entity flow.Entity) bool

Add adds the given entity to the backdata and returns true if the entity was added or false if a valid entity already exists for the provided ID.

func (*Cache) Adjust

func (c *Cache) Adjust(entityID flow.Identifier, f func(flow.Entity) flow.Entity) (flow.Entity, bool)

Adjust adjusts the entity using the given function if the given identifier can be found. Returns a bool which indicates whether the entity was updated as well as the updated entity.

func (*Cache) AdjustWithInit

func (c *Cache) AdjustWithInit(entityID flow.Identifier, adjust func(flow.Entity) flow.Entity, init func() flow.Entity) (flow.Entity, bool)

AdjustWithInit adjusts the entity using the given function if the given identifier can be found. When the entity is not found, it initializes the entity using the given init function and then applies the adjust function. Args: - entityID: the identifier of the entity to adjust. - adjust: the function that adjusts the entity. - init: the function that initializes the entity when it is not found. Returns:

• the adjusted entity.

- a bool which indicates whether the entity was adjusted.

func (*Cache) All

func (c *Cache) All() map[flow.Identifier]flow.Entity

All returns all entities stored in the backdata.

func (*Cache) ByID

func (c *Cache) ByID(entityID flow.Identifier) (flow.Entity, bool)

ByID returns the given entity from the backdata.

func (*Cache) Clear

func (c *Cache) Clear()

Clear removes all entities from the backdata.

func (*Cache) Entities

func (c *Cache) Entities() []flow.Entity

Entities returns the list of entities stored in the backdata.

func (*Cache) GetWithInit

func (c *Cache) GetWithInit(entityID flow.Identifier, init func() flow.Entity) (flow.Entity, bool)

GetWithInit returns the given entity from the backdata. If the entity does not exist, it creates a new entity using the factory function and stores it in the backdata. Args: - entityID: the identifier of the entity to get. - init: the function that initializes the entity when it is not found. Returns:

• the entity.

- a bool which indicates whether the entity was found (or created).

func (*Cache) Has

func (c *Cache) Has(entityID flow.Identifier) bool

Has checks if backdata already contains the entity with the given identifier.

func (*Cache) Head

func (c *Cache) Head() (flow.Entity, bool)

Head returns the head of queue. Boolean return value determines whether there is a head available.

func (*Cache) Identifiers

func (c *Cache) Identifiers() flow.IdentifierList

Identifiers returns the list of identifiers of entities stored in the backdata.

func (*Cache) Remove

func (c *Cache) Remove(entityID flow.Identifier) (flow.Entity, bool)

Remove removes the entity with the given identifier and returns the removed entity and true if the entity was removed or false if the entity was not found.

func (*Cache) Size

func (c *Cache) Size() uint

Size returns the size of the backdata, i.e., total number of stored (entityId, entity) pairs.

type CacheOpt

type CacheOpt func(*Cache)

func WithTracer

func WithTracer(t Tracer) CacheOpt

WithTracer injects tracer into the cache

type Tracer

type Tracer interface {
	// EntityEjectionDueToEmergency reports ejected entity whenever a bucket is found full and all of its keys are valid, i.e.,
	// each key belongs to an existing (key, entity) pair.
	// Hence, adding a new key to that bucket will replace the oldest valid key inside that bucket.
	// This ejection happens with very low, but still cryptographically non-negligible probability.
	EntityEjectionDueToEmergency(ejectedEntity flow.Entity)
	// EntityEjectionDueToFullCapacity reports ejected entity whenever adding a new (key, entity) to the cache results in ejection of another (key', entity') pair.
	// This normally happens -- and is expected -- when the cache is full.
	EntityEjectionDueToFullCapacity(ejectedEntity flow.Entity)
}

Tracer is a generic interface that is used to report specific events that happen during lifetime of Cache and are potentially interesting for external consumer.