lru

Documentation

Overview

Copyright 2023 The acquirecloud Authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2023 The acquirecloud Authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Package lru contains the container with limited size capacity and LRU (Least Recently Used) pull out discipline. The continer uses golang generics, so the container can be instantiated for differenty key and value types.

Copyright 2023 The acquirecloud Authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2023 The acquirecloud Authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• type Cache
  • func NewCache[K comparable, V any](maxSize int, createNewF CreatePoolElemF[K, V], onDeleteF OnDeleteElemF[K, V]) (*Cache[K, V], error)
• type CacheItem
• type CreateCtxPoolElemF
• type CreatePoolElemF
• type ECache
  • func NewECache[PK any, K comparable, V any](maxSize int, toComparableF MapToInnerKeyF[PK, K], ...) (*ECache[PK, K, V], error)
  • func (p *ECache[PK, K, V]) Clear() int
  • func (p *ECache[PK, K, V]) GetOrCreate(pk PK) (V, error)
  • func (p *ECache[PK, K, V]) Remove(pk PK) bool
• type ExpirableCache
  • func NewExpirableCache[K comparable, V CacheItem](maxSize int, createNewF CreatePoolElemF[K, V], onDeleteF OnDeleteElemF[K, V]) (*ExpirableCache[K, V], error)
  • func (p *ExpirableCache[K, V]) GetOrCreate(k K) (V, error)
• type ExpirableItem
  • func NewCacheItem[V any](value V, expiresAt time.Time) ExpirableItem[V]
  • func (i ExpirableItem[V]) GetExpiresAt() time.Time
  • func (i ExpirableItem[V]) GetValue() any
• type MapToInnerKeyF
• type OnDeleteElemF
• type Releasable
  • func (rlsbl Releasable[V]) Value() V
• type ReleasableCache
  • func NewReleasableCache[K comparable, V any](maxSize int, createNewF CreateCtxPoolElemF[K, V], ...) (*ReleasableCache[K, V], error)
  • func (r *ReleasableCache[K, V]) Close() error
  • func (r *ReleasableCache[K, V]) GetOrCreate(ctx context.Context, k K) (Releasable[V], error)
  • func (r *ReleasableCache[K, V]) Release(rlsbl *Releasable[V])

Types

type Cache

type Cache[K comparable, V any] struct {
	*ECache[K, K, V]
}

Cache implements container with limited size capacity and LRU (Least Recently Used) pull out discipline. The elements can be created automatically if they are not found in the pool via the createNewF function call, which is provided via the Cache creation (see NewCache)

func NewCache

func NewCache[K comparable, V any](maxSize int, createNewF CreatePoolElemF[K, V], onDeleteF OnDeleteElemF[K, V]) (*Cache[K, V], error)

NewCache creates new pool object. It expects the maximum pull size (maxSize) and the create new element function in the parameters

type CacheItem

type CacheItem interface {
	GetValue() any
	GetExpiresAt() time.Time
}

CacheItem - interface for ExpirableItem that needs to be implemented in order to work with ExpirableCache cache

type CreateCtxPoolElemF

type CreateCtxPoolElemF[K any, V any] func(ctx context.Context, k K) (V, error)

CreateCtxPoolElemF a configuration type used for providing the function which will be called for creating new objects

type CreatePoolElemF

type CreatePoolElemF[K any, V any] func(k K) (V, error)

CreatePoolElemF function type for creating new pool elements

type ECache

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

ECache implements container with limited size capacity and LRU (Least Recently Used) pull out discipline. The elements can be created automatically if they are not found in the pool via the createNewF function call, which is provided via the Cache creation (see NewECache). ECache allows to operate with not comparable type as a primary key. For mapping the type to comparable on MapToInnerKeyF[] should be specified

func NewECache

func NewECache[PK any, K comparable, V any](maxSize int, toComparableF MapToInnerKeyF[PK, K], createNewF CreatePoolElemF[PK, V], onDeleteF OnDeleteElemF[PK, V]) (*ECache[PK, K, V], error)

NewECache creates new pool object. It expects the maximum pull size (maxSize) and the create new element function in the parameters

func (*ECache[PK, K, V]) Clear

func (p *ECache[PK, K, V]) Clear() int

Clear cleans up the cache removing all elements. The function will return number of the elements deleted

func (*ECache[PK, K, V]) GetOrCreate

func (p *ECache[PK, K, V]) GetOrCreate(pk PK) (V, error)

GetOrCreate returns an existing pool element or create the new one by its key

func (*ECache[PK, K, V]) Remove

func (p *ECache[PK, K, V]) Remove(pk PK) bool

Remove deletes the element by key k. It returns true if the element was in the collection and false if it was not found

type ExpirableCache

type ExpirableCache[K comparable, V CacheItem] struct {
	*Cache[K, V]
}

ExpirableCache - wrapper around cache that checks if value reached expires at timestamp and re-adds it to the cache by calling the createNewF

func NewExpirableCache

func NewExpirableCache[K comparable, V CacheItem](maxSize int, createNewF CreatePoolElemF[K, V], onDeleteF OnDeleteElemF[K, V]) (*ExpirableCache[K, V], error)

func (*ExpirableCache[K, V]) GetOrCreate

func (p *ExpirableCache[K, V]) GetOrCreate(k K) (V, error)

type ExpirableItem

type ExpirableItem[V any] struct {
	Value     V
	ExpiresAt time.Time
}

ExpirableItem - a helper struct for expirable cache. Allows to store any value in cache with a expires at timestamp.

func NewCacheItem

func NewCacheItem[V any](value V, expiresAt time.Time) ExpirableItem[V]

func (ExpirableItem[V]) GetExpiresAt

func (i ExpirableItem[V]) GetExpiresAt() time.Time

func (ExpirableItem[V]) GetValue

func (i ExpirableItem[V]) GetValue() any

type MapToInnerKeyF

type MapToInnerKeyF[V any, K any] func(V) K

type OnDeleteElemF

type OnDeleteElemF[K any, V any] func(k K, v V)

type Releasable

type Releasable[V any] struct {
	// contains filtered or unexported fields
}

Releasable struct represents an object retrieved from the cache. Clients can obtain the object by calling Releasable.Value() function

func (Releasable[V]) Value

func (rlsbl Releasable[V]) Value() V

Value returns the object value associated with Releasable. The function must not be called after the rlsbl is released back to the cache

type ReleasableCache

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

ReleasableCache is a cache which allows to keep up to N(maxSize) objects. The cache allows to delete only not used objects with the LRU discipline. To achieve the behavior, any object, retrieved from the cache, must be released as soon as it's not used anymore. The object can be kept in the cache and retrieved again or been deleted if the capacity of the cache is reached its maximum. The retrieved objects will not be deleted until they are released, so the cache clients must follow the protocol and release any object retrieved from the cache.

func NewReleasableCache

func NewReleasableCache[K comparable, V any](maxSize int, createNewF CreateCtxPoolElemF[K, V], onDeleteF OnDeleteElemF[K, V]) (*ReleasableCache[K, V], error)

NewReleasableCache creates the new ReleasableCache object

func (*ReleasableCache[K, V]) Close

func (r *ReleasableCache[K, V]) Close() error

Close removes all not borrowed objects. The objects that are not released yet will be deleted after the Release() call. After the Close() call the new objects cannot be created

func (*ReleasableCache[K, V]) GetOrCreate

func (r *ReleasableCache[K, V]) GetOrCreate(ctx context.Context, k K) (Releasable[V], error)

GetOrCreate retrieves an existing object or creates a new one if the object is not in the cache. The function accepts ctx and may be blocked until the object is created or the context is expired. If the cache is full and the new object cannot be created due to the capacity limits, the function will be blocked until the creation of the new object will be available or the context is closed.

func (*ReleasableCache[K, V]) Release

func (r *ReleasableCache[K, V]) Release(rlsbl *Releasable[V])

Release allows to return the object back into the cache and let the cache know that the client is not going to use the object. The client MUST NOT use the rlsbl after the call.