github.com/jxskiss/gopkg/v2@v2.14.9-0.20240514120614-899f3e7952b4/perf/lru/interface.go (about)

     1  package lru
     2  
     3  import "time"
     4  
     5  var _ Interface[int, string] = (*Cache[int, string])(nil)
     6  var _ Interface[string, string] = (*ShardedCache[string, string])(nil)
     7  
     8  // Interface is a generic abstract interface of the LRU cache implemented
     9  // in this package.
    10  type Interface[K comparable, V any] interface {
    11  
    12  	// Len returns the number of cached values.
    13  	Len() int
    14  
    15  	// Has checks if a key is in the cache and whether it is expired,
    16  	// without updating its LRU score.
    17  	Has(key K) (exists, expired bool)
    18  
    19  	// Get returns the cached value for the given key and updates its LRU score.
    20  	// The returned value may be expired, caller can check the returned value
    21  	// "expired" to check whether the value is expired.
    22  	Get(key K) (v V, exists, expired bool)
    23  
    24  	// GetWithTTL returns the cached value for the given key and updates its
    25  	// LRU score. The returned value may be expired, caller can check the
    26  	// returned value "ttl" to check whether the value is expired.
    27  	GetWithTTL(key K) (v V, exists bool, ttl *time.Duration)
    28  
    29  	// GetQuiet returns the cached value for the given key, but don't modify its LRU score.
    30  	// The returned value may be expired, caller can check the returned value
    31  	// "expired" to check whether the value is expired.
    32  	GetQuiet(key K) (v V, exists, expired bool)
    33  
    34  	// GetNotStale returns the cached value for the given key. The returned value
    35  	// is guaranteed not expired. If unexpired value available, its LRU score
    36  	// will be updated.
    37  	GetNotStale(key K) (v V, exists bool)
    38  
    39  	// MGet returns map of cached values for the given interface keys and
    40  	// update their LRU scores. The returned values may be expired.
    41  	// It's a convenient and efficient way to retrieve multiple values.
    42  	MGet(keys ...K) map[K]V
    43  
    44  	// MGetNotStale is similar to MGet, but it returns only not stale values.
    45  	MGetNotStale(keys ...K) map[K]V
    46  
    47  	// Set adds an item to the cache overwriting existing one if it exists.
    48  	Set(key K, value V, ttl time.Duration)
    49  
    50  	// MSet adds multiple items to the cache overwriting existing ones.
    51  	// Unlike calling Set multiple times, it acquires lock only once for
    52  	// multiple key-value pairs.
    53  	MSet(kvmap map[K]V, ttl time.Duration)
    54  
    55  	// Delete removes a key from the cache if it exists.
    56  	Delete(key K)
    57  
    58  	// MDelete removes multiple interface keys from the cache if exists.
    59  	// It's a convenient and efficient way to remove multiple keys.
    60  	MDelete(keys ...K)
    61  }