Documentation
¶
Overview ¶
Package weak provides a thread-safe weak pointer cache that automatically cleans up entries when the weakly referenced objects are garbage collected. It supports basic operations like Get, Set and Del. The internal implementation uses sharded maps for concurrency and performance. The cache has no size limit and relies on Go's runtime to manage memory once objects are no longer referenced. This can be used to implement caches on top of more durable storage layers via the filler, setter, and deleter functions. You can then wrap calls for database Set(), Get(), and Delete() operations with this cache to improve performance while keeping memory usage in check via weak references.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache[K comparable, V any] struct { // contains filtered or unexported fields }
Cache is a weak pointer cache.
func New ¶
func New[K comparable, V any](ctx context.Context, name string, options ...Option) (*Cache[K, V], error)
New creates a new Cache with the given options. Name is a unique identifier for the cache, used for metrics.
func (*Cache[K, V]) Del ¶
Del deletes a value for a key. Returns the deleted value, or false when no value was assigned.
func (*Cache[K, V]) Get ¶
Get returns a value for a key. Returns false when no value has been assign for key.
type Filler ¶
type Filler[K comparable, V any] = shardmap.Filler[K, V]
Filler is a function that will be run if the cache needs to fill a missing value. If this function returns a value, it will be set in the cache and returned to the caller. If it returns an error, the Get call will fail with that error.
type Option ¶
type Option func(o opts) (opts, error)
Option is an option for New().
func WithDeDupe ¶
WithDeDupe enables de-duplication of values in the cache based on the provided less function. When enabled, the cache will ensure that only one instance of a value exists in the cache for any given key, based on the comparison provided by the less function. This can help reduce memory usage when many identical values are stored in the cache.
func WithFiller ¶
func WithFiller[K comparable, V any](f Filler[K, V]) Option
WithFiller sets a custom filler function for the cache. This is used to load missing values into the cache on Get calls.
func WithSetter ¶
func WithSetter[K comparable, V any](s Setter[K, V]) Option
WithSetter sets a custom setter function for the cache. This is used to set values in durable storage when they are added to the cache.
func WithSingleFlight ¶
func WithSingleFlight() Option
WithSingleFlight enables the use of the singleflight package for Get operations. This adds another lock on Get operations, but prevents multiple concurrent Get() calls for the same key from causing multiple loads of the same value. Use this to prevent thundering herd problems when loading values from the cache. If not using WithFiller() to retrieve missing values, this option will likely slow operations down instead of speeding them up.
func WithTTL ¶
WithTTL sets the time-to-live for entries in the cache and the cleanup interval. Entries older than ttl will be removed during cleanup. The ttl must be at least 1 second and is the minimum duration an entry will be kept in the cache. The maxTTL parameter is optional and can be set to 0 to disable it. If set, ttl cannot be greater than maxTTL. This causes entries to be removed after maxTTL even if they are still being referenced. The maxTTL cleanup happens during the same cleanup process as the regular ttl, so it may stick around for up to interval longer than maxTTL. The interval parameter sets how often the cleanup runs, which must be at least 1 second.
Source Files
Directories