Class ConcurrentCache<TKey, TValue>

Represents concurrent cache.

Inheritance

object

ConcurrentCache<TKey, TValue>

Implements

IReadOnlyDictionary<TKey, TValue>

IReadOnlyCollection<KeyValuePair<TKey, TValue>>

IEnumerable<KeyValuePair<TKey, TValue>>

IEnumerable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: DotNext.Runtime.Caching

Assembly: DotNext.dll

Syntax

[Obsolete("Use RandomAccessCache from DotNext.Threading library instead.")]
public class ConcurrentCache<TKey, TValue> : IReadOnlyDictionary<TKey, TValue>, IReadOnlyCollection<KeyValuePair<TKey, TValue>>, IEnumerable<KeyValuePair<TKey, TValue>>, IEnumerable where TKey : notnull

Type Parameters

Name	Description
TKey	The type of the keys.
TValue	The type of the cache items.

Remarks

The cache provides O(1) lookup performance if there is no hash collision. Asymptotic complexity of other operations are same as for ConcurrentDictionary<TKey, TValue> class. The cache has the following architecture to deal with lock contention: the access to the concurrent dictionary is synchronous while the access to the eviction deque is asynchronous. All actions need to be applied to the deque are delayed and distributed across concurrent threads. Thus, the deque is weakly consistent with the dictionary.

Constructors

ConcurrentCache(int, CacheEvictionPolicy, IEqualityComparer<TKey>?)

Initializes a new empty cache.

Declaration

public ConcurrentCache(int capacity, CacheEvictionPolicy evictionPolicy, IEqualityComparer<TKey>? keyComparer = null)

Parameters

Type	Name	Description
int	capacity	The maximum number of cached items.
CacheEvictionPolicy	evictionPolicy	The eviction policy describing how the cached items must be removed on cache overflow.
IEqualityComparer<TKey>	keyComparer	The comparer that can be used to compare keys within the cache.

Exceptions

Type	Condition
ArgumentOutOfRangeException	capacity is less than 1; or evictionPolicy is invalid.

ConcurrentCache(int, int, CacheEvictionPolicy, IEqualityComparer<TKey>?)

Initializes a new empty cache.

Declaration

public ConcurrentCache(int capacity, int concurrencyLevel, CacheEvictionPolicy evictionPolicy, IEqualityComparer<TKey>? keyComparer = null)

Parameters

Type	Name	Description
int	capacity	The maximum number of cached items.
int	concurrencyLevel	The number of thread that can access the cache concurrently.
CacheEvictionPolicy	evictionPolicy	The eviction policy describing how the cached items must be removed on cache overflow.
IEqualityComparer<TKey>	keyComparer	The comparer that can be used to compare keys within the cache.

Exceptions

Type	Condition
ArgumentOutOfRangeException	capacity is less than 1; or concurrencyLevel is less than 1; or evictionPolicy is invalid.

Properties

Capacity

Gets the capacity of this cache.

Declaration

public int Capacity { get; }

Property Value

Type	Description
int

Count

Gets the number of cache entries.

Declaration

public int Count { get; }

Property Value

Type	Description
int

Remarks

In contrast to Count, this property is fast and doesn't require an exclusive lock.

Eviction

Gets or sets a handler that can be used to capture evicted cache items.

Declaration

public Action<TKey, TValue>? Eviction { get; init; }

Property Value

Type	Description
Action<TKey, TValue>

ExecuteEvictionAsynchronously

Gets or sets a value indicating that Eviction callback must be executed asynchronously.

Declaration

public bool ExecuteEvictionAsynchronously { get; init; }

Property Value

Type	Description
bool

this[TKey]

Gets or sets cache entry.

Declaration

public TValue this[TKey key] { get; set; }

Parameters

Type	Name	Description
TKey	key	The key of the cache entry.

Property Value

Type	Description
TValue	The cache entry.

Exceptions

Type	Condition
KeyNotFoundException	The cache entry with key doesn't exist.

Methods

AddOrUpdate(TKey, TValue, out bool)

Adds or modifies the cache entry as an atomic operation.

Declaration

public TValue AddOrUpdate(TKey key, TValue value, out bool added)

Parameters

Type	Name	Description
TKey	key	The key of the cache entry.
TValue	value	The cache entry.
bool	added	true if a new entry is added; false if the existing entry is modified.

Returns

Type	Description
TValue	value if added is true; or the value before modification.

Clear()

Removes all items from the cache.

Declaration

public void Clear()

Remarks

This operation locks the entire cache exclusively.

GetEnumerator()

Gets enumerator over all key/value pairs.

Declaration

public IEnumerator<KeyValuePair<TKey, TValue>> GetEnumerator()

Returns

Type	Description
IEnumerator<KeyValuePair<TKey, TValue>>	Unsorted enumerator over all key/value pairs.

GetOrAdd(TKey, TValue, out bool)

Gets or adds the cache entry as an atomic operation.

Declaration

public TValue GetOrAdd(TKey key, TValue value, out bool added)

Parameters

Type	Name	Description
TKey	key	The key of the cache entry.
TValue	value	The cache entry.
bool	added	true if a new entry is added; false if the entry is already exist.

Returns

Type	Description
TValue	value if added is true; or existing value.

TakeSnapshot(Span<KeyValuePair<TKey, TValue>>, bool)

Gets a sorted set of cache entries.

Declaration

public int TakeSnapshot(Span<KeyValuePair<TKey, TValue>> buffer, bool descendingOrder = true)

Parameters

Type	Name	Description
Span<KeyValuePair<TKey, TValue>>	buffer	The buffer used as a destination to write cache entries.
bool	descendingOrder	true to start from the least (or most) recently used cache entry; false to start from the eldest used cache entry.

Returns

Type	Description
int	The actual number of written items.

Remarks

In contrast to GetEnumerator(), this method allows to obtain sorted set of cache entries. However, the method has impact performance on the overall cache. It suspends eviction process during execution.

TryAdd(TKey, TValue)

Adds a new cache entry if the cache is not full.

Declaration

public bool TryAdd(TKey key, TValue value)

Parameters

Type	Name	Description
TKey	key	The key of the cache entry.
TValue	value	The cache entry.

Returns

Type	Description
bool	true if the entry is added successfully; otherwise, false.

TryGetValue(TKey, out TValue)

Attempts to get existing cache entry.

Declaration

public bool TryGetValue(TKey key, out TValue value)

Parameters

Type	Name	Description
TKey	key	The key of the cache entry.
TValue	value	The cache entry, if successful.

Returns

Type	Description
bool	true if the cache entry exists; otherwise, false.

TryRemove(KeyValuePair<TKey, TValue>)

Attempts to remove the cache entry.

Declaration

public bool TryRemove(KeyValuePair<TKey, TValue> pair)

Parameters

Type	Name	Description
KeyValuePair<TKey, TValue>	pair	The pair to be removed.

Returns

Type	Description
bool	true if the cache entry removed successfully; otherwise, false.

Remarks

This method will not raise Eviction event for the removed entry.

TryRemove(TKey, out TValue)

Attempts to remove the cache entry.

Declaration

public bool TryRemove(TKey key, out TValue value)

Parameters

Type	Name	Description
TKey	key	The key of the cache entry.
TValue	value	The cache entry, if successful.

Returns

Type	Description
bool	true if the cache entry removed successfully; otherwise, false.

Remarks

This method will not raise Eviction event for the removed entry.

TryUpdate(TKey, TValue, TValue)

Updates the cache entry associated with the specified key.

Declaration

public bool TryUpdate(TKey key, TValue newValue, TValue expectedValue)

Parameters

Type	Name	Description
TKey	key	The key whose value is compared with expectedValue and possibly replaced.
TValue	newValue	The value that replaces the value of the entry with key if the comparison results in equality.
TValue	expectedValue	The value that is compared to the value of the element with key.

Returns

Type	Description
bool	true if the value with key was equal to expectedValue and replaced with newValue; otherwise, false.

Implements

IReadOnlyDictionary<TKey, TValue>

IReadOnlyCollection<T>

IEnumerable<T>

IEnumerable

Extension Methods

BasicExtensions.As<T>(T)

BasicExtensions.GetUserData<T>(T)

BasicExtensions.IsBetween<T, TLowerBound, TUpperBound>(T, TLowerBound, TUpperBound)

BasicExtensions.IsOneOf<T>(T, ReadOnlySpan<T>)

ExpressionBuilder.Const<T>(T)

AsyncLockAcquisition.AcquireLockAsync<T>(T, CancellationToken)

AsyncLockAcquisition.AcquireLockAsync<T>(T, TimeSpan, CancellationToken)

AsyncLockAcquisition.AcquireReadLockAsync<T>(T, CancellationToken)

AsyncLockAcquisition.AcquireReadLockAsync<T>(T, TimeSpan, CancellationToken)

AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, bool, CancellationToken)

AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, bool, TimeSpan, CancellationToken)

AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, CancellationToken)

AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, TimeSpan, CancellationToken)

LockAcquisition.AcquireReadLock<T>(T)

LockAcquisition.AcquireReadLock<T>(T, TimeSpan)

LockAcquisition.AcquireUpgradeableReadLock<T>(T)

LockAcquisition.AcquireUpgradeableReadLock<T>(T, TimeSpan)

LockAcquisition.AcquireWriteLock<T>(T)

LockAcquisition.AcquireWriteLock<T>(T, TimeSpan)

Collection.Append<T>(IEnumerable<T>, params T[])

Collection.Copy<T>(IEnumerable<T>, int, MemoryAllocator<T>?)

Collection.ElementAt<T>(IEnumerable<T>, int, out T)

Collection.FirstOrNone<T>(IEnumerable<T>)

Collection.ForEachAsync<T>(IEnumerable<T>, Func<T, CancellationToken, ValueTask>, CancellationToken)

Collection.ForEach<T>(IEnumerable<T>, Action<T>)

Collection.LastOrNone<T>(IEnumerable<T>)

Collection.Prepend<T>(IEnumerable<T>, params T[])

Collection.SequenceHashCode<T>(IEnumerable<T>, bool)

Collection.ToAsyncEnumerable<T>(IEnumerable<T>)

Collection.ToString<T>(IEnumerable<T>, string, string)

Enumerator.GetAsyncEnumerator<T>(IEnumerable<T>, CancellationToken)

Collection.Convert<TInput, TOutput>(IReadOnlyCollection<TInput>, Converter<TInput, TOutput>)

Dictionary.ConvertValues<TKey, TValue, TResult>(IReadOnlyDictionary<TKey, TValue>, Converter<TValue, TResult>)

Dictionary.IndexerGetter<TKey, TValue>(IReadOnlyDictionary<TKey, TValue>)

Dictionary.KeysGetter<TKey, TValue>(IReadOnlyDictionary<TKey, TValue>)

Dictionary.ValuesGetter<TKey, TValue>(IReadOnlyDictionary<TKey, TValue>)