Documentation
¶
Overview ¶
Package xcache provides an in-memory LRU cache with extra features inspired from nginx caching. It is based on https://github.com/karlseguin/ccache for the basic caching features (LRU, concurrency optimizations).
It adds cache locking (prevents 2 concurrent fetches for the same item), infinite serving of stale values in case of fetch errors, asynchronous refresh of stale values, concurrency-limited refresh fetchers, and negative cache.
Its usage makes use of a single function Fetch() (no Get()/Set()), which is provided with a closure capturing the parameters necessary to fetch for the given key.
Index ¶
- type Cache
- type Fetcher
- type Option
- func WithFetchers(n int) Option
- func WithNegPruneSize(n int32) Option
- func WithNegSize(n int32) Option
- func WithNegTTL(t time.Duration) Option
- func WithPruneSize(n int32) Option
- func WithSize(n int32) Option
- func WithStale(useStale bool) Option
- func WithStaleFetchers(n int) Option
- func WithStaleQueueSize(n int) Option
- func WithStaleValidator(f func(interface{}, time.Duration) bool) Option
- func WithTTL(t time.Duration) Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache is the type supporting the local caching of objects.
func (*Cache) Fetch ¶
Fetch returns an object given its cache key and a Fetcher function for fetching it if it expired or missing.
This function will usually be implemented as a closure in order to capture the various parameters needed for fetching from the backend the entry corresponding to the cache key.
Entries are first looked up in the positive cache, then negative, then fetched.
An asynchronous fetch will happen if the entry is stale.
func (*Cache) NewFetches ¶
NewFetches returns the number of fetches for items not in cache, since start.
func (*Cache) Requests ¶
Requests returns the number of cache requests (hits and misses) since start.
func (*Cache) StaleFetches ¶
StaleFetches returns the number of fetches for expired items, since start.
type Fetcher ¶
Fetcher is the type of the closure passed to Fetch() for fetching the desired object if missing or stale.
Depending on the boolean validity and error returned by the closure, the entry will end in the positive or the negative cache (and possibly removed from the other).
If non-nil error, entry will be stored in negative cache (but positive entry will be untouched - use this for transient backend failures); else if validity is false, will be stored in negative cache and positive entry will be deleted (use this case when the item is not "positive" anymore - has invalid state or has been removed); else (nil error nil and true validity) store in positive cache and remove neg entry
type Option ¶
type Option func(c *Cache)
Option is the type of option passed to the constructor.
func WithFetchers ¶
WithFetchers sets the max number of concurrent fetches. Default: 100
func WithNegPruneSize ¶
WithNegPruneSize sets the number of entries to evict when the negative cache is full. Default: negSize/20
func WithNegSize ¶
WithNegSize sets the size of the negative cache, used for storing errors and invalid objects. Default: 500
func WithNegTTL ¶
WithNegTTL sets the duration of a negative cache entry. Default: 5 * time.Second
func WithPruneSize ¶
WithPruneSize sets the number of entries to evict when the positive cache is full. Default: posSize/20
func WithSize ¶
WithSize sets the max cache size (in number of objets). When the cache is full, a portion of the least recently used objets will be evicted. Default: 5000
func WithStale ¶
WithStale allows to decide globally if expired items are served. If false, WithStaleValidator will be ignored. Default: true
func WithStaleFetchers ¶
WithStaleFetchers sets the number of fetchers in the pool for async fetch of stale entries. Default: 3
func WithStaleQueueSize ¶
WithStaleQueueSize sets the size of the chan for queuing items. Default: 1000
func WithStaleValidator ¶
WithStaleValidator allows to use a function to decide if a stale item will be served. The duration is the extra time after expiration. Default: nil (WithStale() will decide if stale items are served)
Source Files