sync

Documentation

Overview

Package sync defines various functions useful with sync of any type.

Index

• Constants
• func WithLock(lk sync.Locker, fn func())
• type EvictCallback
• type FixedPool
  • func NewCachedPool[E any](f func() E) *FixedPool[E]
  • func NewFixedPool[E any](f func() E, size int) *FixedPool[E]
  • func NewTempPool[E any](f func() E) *FixedPool[E]
  • func (p *FixedPool[E]) Cap() int
  • func (p *FixedPool[E]) Emplace(x E)
  • func (p *FixedPool[E]) Get() *FixedPoolElement[E]
  • func (p *FixedPool[E]) GetContext(ctx context.Context) (*FixedPoolElement[E], error)
  • func (p *FixedPool[E]) Init() *FixedPool[E]
  • func (p *FixedPool[E]) Len() int
  • func (p *FixedPool[E]) Put(x *FixedPoolElement[E]) (stored bool)
  • func (p *FixedPool[E]) TryGet() *FixedPoolElement[E]
  • func (p *FixedPool[E]) TryPut(x *FixedPoolElement[E]) (stored bool)
• type FixedPoolElement
  • func (e *FixedPoolElement[E]) Finalize()
  • func (e *FixedPoolElement[E]) Get() E
• type LRU
  • func NewLRU[K comparable, V any](size int) *LRU[K, V]
  • func (c *LRU[K, V]) Add(key K, value V) (evicted bool)
  • func (c *LRU[K, V]) Cap() int
  • func (c *LRU[K, V]) CompareAndDelete(key K, old V) (deleted bool)
  • func (c *LRU[K, V]) CompareAndSwap(key K, old, new V) (swapped bool)
  • func (c *LRU[K, V]) Contains(key K) (ok bool)
  • func (c *LRU[K, V]) Delete(key K)
  • func (c *LRU[K, V]) Get(key K) (value V, ok bool)
  • func (c *LRU[K, V]) GetOldest() (key K, value V, ok bool)
  • func (c *LRU[K, V]) Init() *LRU[K, V]
  • func (c *LRU[K, V]) Keys() []K
  • func (c *LRU[K, V]) Len() int
  • func (c *LRU[K, V]) Load(key K) (value V, ok bool)
  • func (c *LRU[K, V]) LoadAndDelete(key K) (value V, loaded bool)
  • func (c *LRU[K, V]) LoadOrStore(key K, value V) (actual V, loaded bool)
  • func (c *LRU[K, V]) Peek(key K) (value V, ok bool)
  • func (c *LRU[K, V]) PeekAndDeleteOldest() (key K, value V, loaded bool)
  • func (c *LRU[K, V]) PeekOldest() (key K, value V, ok bool)
  • func (c *LRU[K, V]) Purge()
  • func (c *LRU[K, V]) Range(f func(key K, value V) bool)
  • func (c *LRU[K, V]) Remove(key K) (present bool)
  • func (c *LRU[K, V]) RemoveOldest() (key K, value V, ok bool)
  • func (c *LRU[K, V]) Resize(size int) (evicted int)
  • func (c *LRU[K, V]) SetEvictCallback(onEvict EvictCallback[K, V]) *LRU[K, V]
  • func (c *LRU[K, V]) SetEvictCallbackFunc(onEvict func(key K, value V)) *LRU[K, V]
  • func (c *LRU[K, V]) Store(key K, value V)
  • func (c *LRU[K, V]) Swap(key K, value V) (previous V, loaded bool)

Constants

const (
	UnlimitedResident = -1
	UnlimitedCapacity = 0
)

Functions

func WithLock

func WithLock(lk sync.Locker, fn func())

WithLock runs while holding lk.

Types

type EvictCallback

type EvictCallback[K comparable, V any] lru.EvictCallback[K, V]

EvictCallback is used to get a callback when a cache entry is evicted type EvictCallback[K comparable, V any] func(key K, value V)

type FixedPool

type FixedPool[E any] struct {

	// New optionally specifies a function to generate
	// a value when Get would otherwise return nil.
	// It may not be changed concurrently with calls to Get.
	New func() E

	// MinResidentSize controls the minimum number of keep-alive items. items will be preallocated.
	MinResidentSize int
	// MaxResidentSize controls the maximum number of keep-alive items. Negative means no limit.
	MaxResidentSize int
	// MaxCapacity controls the maximum number of allocated items. Zero means no limit.
	MaxCapacity int
	// contains filtered or unexported fields
}

FixedPool is a set of resident and temporary items that may be individually saved and retrieved.

Any item stored in the Pool may be removed automatically at any time without notification. If the Pool holds the only reference when this happens, the item might be deallocated.

A Pool is safe for use by multiple goroutines simultaneously.

func NewCachedPool

func NewCachedPool[E any](f func() E) *FixedPool[E]

NewCachedPool Creates a pool that creates new items as needed, but will reuse previously constructed items when they are available. the pool will reuse previously constructed items and items will never be dropped.

func NewFixedPool

func NewFixedPool[E any](f func() E, size int) *FixedPool[E]

NewFixedPool returns an initialized fixed pool. resident controls the maximum number of keep-alive items. Negative means no limit. cap controls the maximum number of allocated items. Zero means no limit.

func NewTempPool

func NewTempPool[E any](f func() E) *FixedPool[E]

NewTempPool Creates a pool that creates new items as needed, but will be dropped at second GC if only referenced by the pool self. the pool will reuse previously constructed items when they are available and not dropped.

func (*FixedPool[E]) Cap

func (p *FixedPool[E]) Cap() int

Cap returns the capacity of pool, that is object len allocated The complexity is O(1).

func (*FixedPool[E]) Emplace

func (p *FixedPool[E]) Emplace(x E)

Emplace adds x to the pool. NOTE: Emplace may break through the len and cap boundaries, as x be allocated already.

func (*FixedPool[E]) Get

func (p *FixedPool[E]) Get() *FixedPoolElement[E]

Get selects an arbitrary item from the Pool, removes it from the Pool, and returns it to the caller. Get may choose to ignore the pool and treat it as empty. Callers should not assume any relation between values passed to Put and the values returned by Get.

If Get would otherwise return nil and p.New is non-nil, Get returns the result of calling p.New.

Get uses context.Background internally; to specify the context, use GetContext.

func (*FixedPool[E]) GetContext

func (p *FixedPool[E]) GetContext(ctx context.Context) (*FixedPoolElement[E], error)

GetContext selects an arbitrary item from the Pool, removes it from the Pool, and returns it to the caller. Get may choose to ignore the pool and treat it as empty. Callers should not assume any relation between values passed to Put and the values returned by Get.

If GetContext would otherwise return nil and p.New is non-nil, Get returns the result of calling p.New.

func (*FixedPool[E]) Init

func (p *FixedPool[E]) Init() *FixedPool[E]

Init initializes fixed pool l.

func (*FixedPool[E]) Len

func (p *FixedPool[E]) Len() int

Len returns the len of pool, that is object len idle, allocated and still in cache The complexity is O(1).

func (*FixedPool[E]) Put

func (p *FixedPool[E]) Put(x *FixedPoolElement[E]) (stored bool)

Put adds x to the pool.

func (*FixedPool[E]) TryGet

func (p *FixedPool[E]) TryGet() *FixedPoolElement[E]

func (*FixedPool[E]) TryPut

func (p *FixedPool[E]) TryPut(x *FixedPoolElement[E]) (stored bool)

TryPut adds x to the pool, .

type FixedPoolElement

type FixedPoolElement[E any] struct {
	// The value stored with this element.
	Value E
	// contains filtered or unexported fields
}

func (*FixedPoolElement[E]) Finalize

func (e *FixedPoolElement[E]) Finalize()

func (*FixedPoolElement[E]) Get

func (e *FixedPoolElement[E]) Get() E

type LRU

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

LRU is like a Go map[K]V but implements a thread safe fixed size LRU cache. Loads, stores, and deletes run in amortized constant time. A LRU is safe for use by multiple goroutines simultaneously. A LRU must not be copied after first use.

func NewLRU

func NewLRU[K comparable, V any](size int) *LRU[K, V]

NewLRU constructs an LRU of the given size

func (*LRU[K, V]) Add

func (c *LRU[K, V]) Add(key K, value V) (evicted bool)

Add adds a value to the cache. Returns true if an eviction occurred.

func (*LRU[K, V]) Cap

func (c *LRU[K, V]) Cap() int

Cap returns the capacity of the cache.

func (*LRU[K, V]) CompareAndDelete

func (c *LRU[K, V]) CompareAndDelete(key K, old V) (deleted bool)

CompareAndDelete deletes the entry for key if its value is equal to old. The old value must be of a comparable type.

If there is no current value for key in the map, CompareAndDelete returns false (even if the old value is the nil interface value).

func (*LRU[K, V]) CompareAndSwap

func (c *LRU[K, V]) CompareAndSwap(key K, old, new V) (swapped bool)

CompareAndSwap swaps the old and new values for key if the value stored in the map is equal to old. The old value must be of a comparable type.

func (*LRU[K, V]) Contains

func (c *LRU[K, V]) Contains(key K) (ok bool)

Contains checks if a key is in the cache, without updating the recent-ness or deleting it for being stale.

func (*LRU[K, V]) Delete

func (c *LRU[K, V]) Delete(key K)

Delete deletes the value for a key.

func (*LRU[K, V]) Get

func (c *LRU[K, V]) Get(key K) (value V, ok bool)

Get looks up a key's value from the cache, with updating the "recently used"-ness of the key.

func (*LRU[K, V]) GetOldest

func (c *LRU[K, V]) GetOldest() (key K, value V, ok bool)

GetOldest returns the oldest entry

func (*LRU[K, V]) Init

func (c *LRU[K, V]) Init() *LRU[K, V]

Init initializes or clears LRU l.

func (*LRU[K, V]) Keys

func (c *LRU[K, V]) Keys() []K

Keys returns a slice of the keys in the cache, from oldest to newest.

func (*LRU[K, V]) Len

func (c *LRU[K, V]) Len() int

Len returns the number of items in the cache.

func (*LRU[K, V]) Load

func (c *LRU[K, V]) Load(key K) (value V, ok bool)

Load returns the value stored in the cache for a key, or zero if no value is present. The ok result indicates whether value was found in the cache.

func (*LRU[K, V]) LoadAndDelete

func (c *LRU[K, V]) LoadAndDelete(key K) (value V, loaded bool)

LoadAndDelete deletes the value for a key, returning the previous value if any. The loaded result reports whether the key was present.

func (*LRU[K, V]) LoadOrStore

func (c *LRU[K, V]) LoadOrStore(key K, value V) (actual V, loaded bool)

LoadOrStore returns the existing value for the key if present. Otherwise, it stores and returns the given value. The loaded result is true if the value was loaded, false if stored.

func (*LRU[K, V]) Peek

func (c *LRU[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.

func (*LRU[K, V]) PeekAndDeleteOldest

func (c *LRU[K, V]) PeekAndDeleteOldest() (key K, value V, loaded bool)

PeekAndDeleteOldest deletes the value for a key, returning the previous value if any. The loaded result reports whether the key was present.

func (*LRU[K, V]) PeekOldest

func (c *LRU[K, V]) PeekOldest() (key K, value V, ok bool)

PeekOldest returns the value stored in the cache for the oldest entry, or zero if no value is present. The ok result indicates whether value was found in the cache. Without updating the "recently used"-ness of the key.

func (*LRU[K, V]) Purge

func (c *LRU[K, V]) Purge()

Purge is used to completely clear the cache.

func (*LRU[K, V]) Range

func (c *LRU[K, V]) Range(f func(key K, value V) bool)

Range calls f sequentially for each key and value present in the lru from oldest to newest. If f returns false, range stops the iteration. Without updating the "recently used"-ness of the key.

func (*LRU[K, V]) Remove

func (c *LRU[K, V]) Remove(key K) (present bool)

Remove removes the provided key from the cache, returning if the key was contained.

func (*LRU[K, V]) RemoveOldest

func (c *LRU[K, V]) RemoveOldest() (key K, value V, ok bool)

RemoveOldest removes the oldest item from the cache.

func (*LRU[K, V]) Resize

func (c *LRU[K, V]) Resize(size int) (evicted int)

Resize changes the cache size.

func (*LRU[K, V]) SetEvictCallback

func (c *LRU[K, V]) SetEvictCallback(onEvict EvictCallback[K, V]) *LRU[K, V]

SetEvictCallback sets a callback when a cache entry is evicted

func (*LRU[K, V]) SetEvictCallbackFunc

func (c *LRU[K, V]) SetEvictCallbackFunc(onEvict func(key K, value V)) *LRU[K, V]

SetEvictCallbackFunc sets a callback when a cache entry is evicted

Deprecated, use SetEvictCallback instead.

func (*LRU[K, V]) Store

func (c *LRU[K, V]) Store(key K, value V)

Store sets the value for a key.

func (*LRU[K, V]) Swap

func (c *LRU[K, V]) Swap(key K, value V) (previous V, loaded bool)

Swap swaps the value for a key and returns the previous value if any. The loaded result reports whether the key was present.