package lru

Import Path
	github.com/hashicorp/golang-lru/v2 (on go.dev)

Dependency Relation
	imports 3 packages, and imported by one package

Involved Source Files

	    2q.go
	  d doc.go
		Package lru provides three different LRU caches of varying sophistication.
		
		Cache is a simple LRU cache. It is based on the LRU implementation in
		groupcache: https://github.com/golang/groupcache/tree/master/lru
		
		TwoQueueCache tracks frequently used and recently used entries separately.
		This avoids a burst of accesses from taking out frequently used entries, at
		the cost of about 2x computational overhead and some extra bookkeeping.
		
		ARCCache is an adaptive replacement cache. It tracks recent evictions as well
		as recent usage in both the frequent and recent caches. Its computational
		overhead is comparable to TwoQueueCache, but the memory overhead is linear
		with the size of the cache.
		
		ARC has been patented by IBM, so do not use it if that is problematic for
		your program. For this reason, it is in a separate go module contained within
		this repository.
		
		All caches in this package take locks while operating, and are therefore
		thread-safe for consumers.

	    lru.go
Package-Level Type Names (total 2)

	/* sort by: alphabet | popularity */
	 type Cache[K, V] (struct)

		Type Parameters:
			K: comparable
			V: any

		Cache is a thread-safe fixed size LRU cache.

		Methods (total 14)
			(*Cache[K, V]) Add(key K, value V) (evicted bool)
				Add adds a value to the cache. Returns true if an eviction occurred.

			(*Cache[K, V]) Contains(key K) bool
				Contains checks if a key is in the cache, without updating the
				recent-ness or deleting it for being stale.

			(*Cache[K, V]) ContainsOrAdd(key K, value V) (ok, evicted bool)
				ContainsOrAdd checks if a key is in the cache without updating the
				recent-ness or deleting it for being stale, and if not, adds the value.
				Returns whether found and whether an eviction occurred.

			(*Cache[K, V]) Get(key K) (value V, ok bool)
				Get looks up a key's value from the cache.

			(*Cache[K, V]) GetOldest() (key K, value V, ok bool)
				GetOldest returns the oldest entry

			(*Cache[K, V]) Keys() []K
				Keys returns a slice of the keys in the cache, from oldest to newest.

			(*Cache[K, V]) Len() int
				Len returns the number of items in the cache.

			(*Cache[K, V]) Peek(key K) (value V, ok bool)
				Peek returns the key value (or undefined if not found) without updating
				the "recently used"-ness of the key.

			(*Cache[K, V]) PeekOrAdd(key K, value V) (previous V, ok, evicted bool)
				PeekOrAdd checks if a key is in the cache without updating the
				recent-ness or deleting it for being stale, and if not, adds the value.
				Returns whether found and whether an eviction occurred.

			(*Cache[K, V]) Purge()
				Purge is used to completely clear the cache.

			(*Cache[K, V]) Remove(key K) (present bool)
				Remove removes the provided key from the cache.

			(*Cache[K, V]) RemoveOldest() (key K, value V, ok bool)
				RemoveOldest removes the oldest item from the cache.

			(*Cache[K, V]) Resize(size int) (evicted int)
				Resize changes the cache size.

			(*Cache[K, V]) Values() []V
				Values returns a slice of the values in the cache, from oldest to newest.

		As Outputs Of (at least 2)
			func New[K, V](size int) (*Cache[K, V], error)
			func NewWithEvict[K, V](size int, onEvicted func(key K, value V)) (c *Cache[K, V], err error)

	 type TwoQueueCache[K, V] (struct)

		Type Parameters:
			K: comparable
			V: any

		TwoQueueCache is a thread-safe fixed size 2Q cache.
		2Q is an enhancement over the standard LRU cache
		in that it tracks both frequently and recently used
		entries separately. This avoids a burst in access to new
		entries from evicting frequently used entries. It adds some
		additional tracking overhead to the standard LRU cache, and is
		computationally about 2x the cost, and adds some metadata over
		head. The ARCCache is similar, but does not require setting any
		parameters.

		Methods (total 10)
			(*TwoQueueCache[K, V]) Add(key K, value V)
				Add adds a value to the cache.

			(*TwoQueueCache[K, V]) Contains(key K) bool
				Contains is used to check if the cache contains a key
				without updating recency or frequency.

			(*TwoQueueCache[K, V]) Get(key K) (value V, ok bool)
				Get looks up a key's value from the cache.

			(*TwoQueueCache[K, V]) Keys() []K
				Keys returns a slice of the keys in the cache.
				The frequently used keys are first in the returned slice.

			(*TwoQueueCache[K, V]) Len() int
				Len returns the number of items in the cache.

			(*TwoQueueCache[K, V]) Peek(key K) (value V, ok bool)
				Peek is used to inspect the cache value of a key
				without updating recency or frequency.

			(*TwoQueueCache[K, V]) Purge()
				Purge is used to completely clear the cache.

			(*TwoQueueCache[K, V]) Remove(key K)
				Remove removes the provided key from the cache.

			(*TwoQueueCache[K, V]) Resize(size int) (evicted int)
				Resize changes the cache size.

			(*TwoQueueCache[K, V]) Values() []V
				Values returns a slice of the values in the cache.
				The frequently used values are first in the returned slice.

		As Outputs Of (at least 2)
			func New2Q[K, V](size int) (*TwoQueueCache[K, V], error)
			func New2QParams[K, V](size int, recentRatio, ghostRatio float64) (*TwoQueueCache[K, V], error)


Package-Level Functions (total 4)

	 func New[K, V](size int) (*Cache[K, V], error)

		Type Parameters:
			K: comparable
			V: any

		New creates an LRU of the given size.

	 func New2Q[K, V](size int) (*TwoQueueCache[K, V], error)

		Type Parameters:
			K: comparable
			V: any

		New2Q creates a new TwoQueueCache using the default
		values for the parameters.

	 func New2QParams[K, V](size int, recentRatio, ghostRatio float64) (*TwoQueueCache[K, V], error)

		Type Parameters:
			K: comparable
			V: any

		New2QParams creates a new TwoQueueCache using the provided
		parameter values.

	 func NewWithEvict[K, V](size int, onEvicted func(key K, value V)) (c *Cache[K, V], err error)

		Type Parameters:
			K: comparable
			V: any

		NewWithEvict constructs a fixed size cache with the given eviction
		callback.


Package-Level Constants (total 3)

	const Default2QGhostEntries = 0.5
		Default2QGhostEntries is the default ratio of ghost
		entries kept to track entries recently evicted

	const Default2QRecentRatio = 0.25
		Default2QRecentRatio is the ratio of the 2Q cache dedicated
		to recently added entries that have only been accessed once.

	const DefaultEvictedBufferSize = 16
		DefaultEvictedBufferSize defines the default buffer size to store evicted key/val

The pages are generated with Golds v0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.