cache

Documentation

Index

• type Cache
  • func NewCache[K comparable, V any](minimumCapacity int, options ...Option[K, V]) *Cache[K, V]
  • func (c *Cache[K, V]) Add(key K, value V, ttl time.Duration)
  • func (c *Cache[K, V]) Get(key K) (*V, bool)
  • func (c *Cache[K, V]) OnEvict(fn func(K, V))
• type Click
• type Fn
• type Option
  • func WithClock[K comparable, V any](clock Click) Option[K, V]
  • func WithEvictDuration[K comparable, V any](evictDuration time.Duration) Option[K, V]
  • func WithOnEvict[K comparable, V any](onEvict Fn[K, V]) Option[K, V]

Types

type Cache

type Cache[K comparable, V any] struct {
	// contains filtered or unexported fields
}

Cache is a thread-safe cache implementation that stores key-value pairs with a time-to-live (TTL) for each item. It is implemented as a map where the keys are strings and the values are pointers to item structs. The cache has a maximum size, which is specified by the maxSize parameter. The clock parameter is an interface that provides the current time. The onEvict parameter is a function that is called when an item is evicted from the cache. The evictDuration parameter specifies the duration after which an item is evicted from the cache.

func NewCache

func NewCache[K comparable, V any](minimumCapacity int, options ...Option[K, V]) *Cache[K, V]

NewCacheWithOptions creates a new Cache instance with the specified minimum capacity and optional configurations.

The function initializes a new Cache instance with the specified minimum capacity and default values. It takes the minimumCapacity parameter, which specifies the minimum capacity of the cache. The options parameter is a variadic list of Option functions that can be used to configure the cache.

Parameters:

• minimumCapacity: The minimum capacity of the cache.
• options: Optional configurations for the cache.

Returns:

• A pointer to the initialized Cache instance.

func (*Cache[K, V]) Add

func (c *Cache[K, V]) Add(key K, value V, ttl time.Duration)

Add adds a new item to the cache with the given key, value, and time-to-live (TTL).

If the key already exists in the cache, its value and TTL are updated.

Parameters:

• key: The key used to identify the item in the cache.
• value: The value associated with the key.
• ttl: The time-to-live (TTL) of the item. The item will be automatically removed from the cache after the TTL has expired.

This function locks the cache for write access, creates a new cache item with the given key, value, and TTL, and adds it to the cache. If the key already exists in the cache, its value and TTL are updated.

func (*Cache[K, V]) Get

func (c *Cache[K, V]) Get(key K) (*V, bool)

Get retrieves the value from the cache associated with the given key.

It returns a pointer to the value and a boolean indicating whether the key was found in the cache. If the key is not found, the pointer will be nil and the boolean will be false.

Parameters:

• key: The key used to identify the item in the cache.

Returns:

• value: A pointer to the value associated with the key.
• found: A boolean indicating whether the key was found in the cache.

This function locks the cache for read access to prevent concurrent modifications. It retrieves the value associated with the given key from the cache. If the key is found in the cache, it returns a pointer to the value and true. If the key is not found in the cache, it returns nil and false.

func (*Cache[K, V]) OnEvict

func (c *Cache[K, V]) OnEvict(fn func(K, V))

OnEvict sets a callback function that will be called when an item is evicted from the cache. The callback function takes the key of the evicted item as a parameter.

Parameters:

• fn: The callback function that will be called when an item is evicted from the cache. The callback function takes the key of the evicted item as a parameter.

This function sets the onEvict callback function for the cache. The onEvict callback function is called when an item is evicted from the cache. It takes the key of the evicted item as a parameter. The onEvict function is useful for performing actions when an item is evicted from the cache, such as logging the eviction of an item.

The onEvict function is executed after the default onEvict function, which removes the item from the cache. If an onEvict function is already set, the new function is composed with the old onEvict function. The composed function calls the provided callback function and then calls the old onEvict function.

Parameters:

• fn: The callback function that will be called when an item is evicted from the cache. The callback function takes the key of the evicted item as a parameter.

type Click

type Click interface {
	// Now returns the current local time.
	Now() time.Time
}

Click is an interface that provides the current time.

It defines the Now method that returns the current local time.

type Fn

type Fn[K comparable, V any] func(key K, value V)

Fn is a function type that represents a callback function.

It is used as the OnEvict parameter of the Cache struct. The OnEvict parameter is a function that is called when an item is evicted from the cache. The function takes the key and value of the evicted item as parameters.

OnEvict functions are useful for performing actions when an item is evicted from the cache. For example, you can log the eviction of an item or perform additional cleanup operations.

Parameters:

• key: The key of the evicted item.
• value: The value of the evicted item.

Example:

// Log the eviction of an item
func itemEvicted(key string, value int) {
    log.Printf("Item with key %s and value %d evicted from cache", key, value)
}

cache := cache.NewCache[string, int](10, cache.WithOnEvict(itemEvicted))

type Option

type Option[K comparable, V any] func(c *Cache[K, V])

Option is a function that can be used to configure a Cache instance.

It takes a pointer to a Cache instance and returns nothing. The purpose of the Option function is to provide a way to configure a Cache instance with different options, such as setting the maximum number of items in the cache or setting the onEvict function.

Parameters:

• c: A pointer to the Cache struct that will be customized.

Returns:

None.

func WithClock

func WithClock[K comparable, V any](clock Click) Option[K, V]

WithClock returns an Option that sets the clock for the cache.

The clock is used to get the current time, which is used to determine when items in the cache have expired. The clock can be used to control the behavior of the cache, such as setting the initial time for the cache, or setting the maximum time-to-live for items in the cache.

Parameters:

• clock: The clock to use for the cache. It must implement the Click interface.

Returns:

An Option that sets the clock for the cache.

func WithEvictDuration

func WithEvictDuration[K comparable, V any](evictDuration time.Duration) Option[K, V]

WithEvictDuration is an option that sets the eviction duration for the cache.

The eviction duration is the time after which an item is evicted from the cache. The parameter evictDuration specifies the duration after which an item is evicted from the cache. The default value for evictDuration is 1 minute.

Parameters:

• evictDuration: The duration after which an item is evicted from the cache.

Returns:

An option that sets the eviction duration for the cache.

func WithOnEvict

func WithOnEvict[K comparable, V any](onEvict Fn[K, V]) Option[K, V]

WithOnEvict returns an Option that sets the onEvict function for the cache.

The onEvict function is called when an item is evicted from the cache. It takes the key of the evicted item as a parameter, and can be used to perform an action when an item is evicted, such as logging the eviction of an item.

The onEvict function is called after the item has been removed from the cache, and is not called if the item is not evicted from the cache (e.g. if the cache is cleared).

Parameters:

• onEvict: The function to be called when an item is evicted from the cache.

Returns:

• An Option that sets the onEvict function for the cache.