Class RandomAccessCache<TKey, TValue>

Represents concurrent cache optimized for random access.

Inheritance

object

Disposable

RandomAccessCache<TKey, TValue>

RandomAccessCache<TKey, TValue, TWeight>

Implements

IDisposable

IAsyncDisposable

IEnumerable<KeyValuePair<TKey, TValue>>

IEnumerable

Inherited Members

Disposable.IsDisposed

Disposable.IsDisposing

Disposable.IsDisposingOrDisposed

Disposable.CreateException()

Disposable.DisposedTask

Disposable.GetDisposedTask<T>()

Disposable.TrySetDisposedException<T>(TaskCompletionSource<T>)

Disposable.TrySetDisposedException(TaskCompletionSource)

Disposable.TryBeginDispose()

Disposable.Dispose()

Disposable.Dispose(IEnumerable<IDisposable>)

Disposable.DisposeAsync(IEnumerable<IAsyncDisposable>)

Disposable.Dispose<T>(ReadOnlySpan<T>)

Disposable.DisposeAsync(params IAsyncDisposable[])

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.Threading.dll

Syntax

public class RandomAccessCache<TKey, TValue> : Disposable, IDisposable, IAsyncDisposable, IEnumerable<KeyValuePair<TKey, TValue>>, IEnumerable where TKey : notnull where TValue : notnull

Type Parameters

Name	Description
TKey	The type of the keys.
TValue	The type of the values.

Remarks

The cache evicts older records on overflow.

Constructors

RandomAccessCache(int)

Initializes a new cache.

Declaration

public RandomAccessCache(int cacheCapacity)

Parameters

Type	Name	Description
int	cacheCapacity	Maximum cache size.

Exceptions

Type	Condition
ArgumentOutOfRangeException	cacheCapacity is less than or equal to zero.

Properties

Capacity

Gets the capacity of this cache.

Declaration

public int Capacity { get; }

Property Value

Type	Description
int

Eviction

Gets or sets a callback that can be used to clean up the evicted value.

Declaration

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

Property Value

Type	Description
Action<TKey, TValue>

KeyComparer

Gets or sets key comparer.

Declaration

public IEqualityComparer<TKey>? KeyComparer { get; init; }

Property Value

Type	Description
IEqualityComparer<TKey>

Methods

Change(TKey, TimeSpan, CancellationToken)

Opens a session synchronously that can be used to modify the value associated with the key.

Declaration

public RandomAccessCache<TKey, TValue>.ReadWriteSession Change(TKey key, TimeSpan timeout, CancellationToken token = default)

Parameters

Type	Name	Description
TKey	key	The key of the cache record.
TimeSpan	timeout	The time to wait for the cache lock.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
RandomAccessCache<TKey, TValue>.ReadWriteSession	The session that can be used to read or modify the cache record.

Remarks

The cache guarantees that the value cannot be evicted concurrently with the returned session. However, the value can be evicted immediately after. The caller must dispose session.

Exceptions

Type	Condition
TimeoutException	The internal lock cannot be acquired in timely manner.
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

ChangeAsync(TKey, CancellationToken)

Opens a session that can be used to modify the value associated with the key.

Declaration

public ValueTask<RandomAccessCache<TKey, TValue>.ReadWriteSession> ChangeAsync(TKey key, CancellationToken token = default)

Parameters

Type	Name	Description
TKey	key	The key of the cache record.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<RandomAccessCache<TKey, TValue>.ReadWriteSession>	The session that can be used to read or modify the cache record.

Remarks

The cache guarantees that the value cannot be evicted concurrently with the returned session. However, the value can be evicted immediately after. The caller must dispose session.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

Contains(TKey)

Determines whether the cache entry associated with the specified key exists in the cache.

Declaration

public bool Contains(TKey key)

Parameters

Type	Name	Description
TKey	key	The key to check.

Returns

Type	Description
bool	true if the cache entry associated with key exists in the cache; otherwise, false.

Dispose(bool)

Releases managed and unmanaged resources associated with this object.

Declaration

protected override void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing	true if called from Dispose(); false if called from finalizer ~Disposable().

Overrides

Disposable.Dispose(bool)

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

Declaration

public ValueTask DisposeAsync()

Returns

Type	Description
ValueTask	A task that represents the asynchronous dispose operation.

DisposeAsyncCore()

Releases managed resources associated with this object asynchronously.

Declaration

protected override ValueTask DisposeAsyncCore()

Returns

Type	Description
ValueTask	The task representing asynchronous execution of this method.

Overrides

Disposable.DisposeAsyncCore()

Remarks

This method makes sense only if derived class implements IAsyncDisposable interface.

GetEnumerator()

Gets an enumerator over the cache entries.

Declaration

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

Returns

Type	Description
IEnumerator<KeyValuePair<TKey, TValue>>	The enumerator over the cache entries.

Remarks

SIEVE algorithm is not scan-resistant, the returned enumerator doesn't update the recency for the entry.

Invalidate(TKey, TimeSpan, CancellationToken)

Invalidates the cache record associated with the specified key.

Declaration

public bool Invalidate(TKey key, TimeSpan timeout, CancellationToken token = default)

Parameters

Type	Name	Description
TKey	key	The key of the cache record to be removed.
TimeSpan	timeout	The time to wait for the cache lock.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
bool	true if the cache record associated with key is removed successfully; otherwise, false.

Exceptions

Type	Condition
TimeoutException	The internal lock cannot be acquired in timely manner.
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

InvalidateAsync(CancellationToken)

Invalidates the entire cache.

Declaration

public ValueTask InvalidateAsync(CancellationToken token = default)

Parameters

Type	Name	Description
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

InvalidateAsync(TKey, CancellationToken)

Invalidates the cache record associated with the specified key.

Declaration

public ValueTask<bool> InvalidateAsync(TKey key, CancellationToken token = default)

Parameters

Type	Name	Description
TKey	key	The key of the cache record to be removed.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<bool>	true if the cache record associated with key is removed successfully; otherwise, false.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

Replace(TKey, TimeSpan, CancellationToken)

Replaces the cache entry associated with the specified key synchronously.

Declaration

public RandomAccessCache<TKey, TValue>.ReadWriteSession Replace(TKey key, TimeSpan timeout, CancellationToken token = default)

Parameters

Type	Name	Description
TKey	key	The key associated with the cache entry.
TimeSpan	timeout	The time to wait for the cache lock.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
RandomAccessCache<TKey, TValue>.ReadWriteSession	The session that can be used to modify the cache record.

Exceptions

Type	Condition
TimeoutException	The internal lock cannot be acquired in timely manner.
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

ReplaceAsync(TKey, CancellationToken)

Replaces the cache entry associated with the specified key.

Declaration

public ValueTask<RandomAccessCache<TKey, TValue>.ReadWriteSession> ReplaceAsync(TKey key, CancellationToken token = default)

Parameters

Type	Name	Description
TKey	key	The key associated with the cache entry.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<RandomAccessCache<TKey, TValue>.ReadWriteSession>	The session that can be used to modify the cache record.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

TryRead(TKey, out ReadSession)

Tries to read the cached record.

Declaration

public bool TryRead(TKey key, out RandomAccessCache<TKey, TValue>.ReadSession session)

Parameters

Type	Name	Description
TKey	key	The key of the cache record.
RandomAccessCache<TKey, TValue>.ReadSession	session	A session that can be used to read the cached record.

Returns

Type	Description
bool	true if the record is available for reading and the session is active; otherwise, false.

Remarks

The cache guarantees that the value cannot be evicted concurrently with the session. However, the value can be evicted immediately after. The caller must dispose session.

TryRemove(TKey, out ReadSession, TimeSpan, CancellationToken)

Tries to invalidate cache record associated with the provided key synchronously.

Declaration

public bool TryRemove(TKey key, out RandomAccessCache<TKey, TValue>.ReadSession session, TimeSpan timeout, CancellationToken token = default)

Parameters

Type	Name	Description
TKey	key	The key of the cache record to be removed.
RandomAccessCache<TKey, TValue>.ReadSession	session	The session that can be used to read the removed cache record.
TimeSpan	timeout	The time to wait for the cache lock.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
bool	true if the record associated with key exists; otherwise, false.

Exceptions

Type	Condition
TimeoutException	The internal lock cannot be acquired in timely manner.
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

TryRemoveAsync(TKey, CancellationToken)

Tries to invalidate cache record associated with the provided key.

Declaration

public ValueTask<RandomAccessCache<TKey, TValue>.ReadSession?> TryRemoveAsync(TKey key, CancellationToken token = default)

Parameters

Type	Name	Description
TKey	key	The key of the cache record to be removed.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<RandomAccessCache<TKey, TValue>.ReadSession?>	The session that can be used to read the removed cache record; or null if there is no record associated with key.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The cache is disposed.

Implements

IDisposable

IAsyncDisposable

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)

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>, bool)

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

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