Interface ICache<TK, TV>

Main entry point for Ignite cache APIs. You can get a named cache by calling GetCache<TK, TV>(String) method.

Cache API supports distributed transactions. All Get(...), Put(...), Replace(...), and Remove(...) operations are transactional and will participate in an ongoing transaction, if any. Other methods like Peek(...) or various Contains(...) methods may be transaction-aware, i.e. check in-transaction entries first, but will not affect the current state of transaction. See ITransaction documentation for more information about transactions.

Neither null keys or values are allowed to be stored in cache. If a null value happens to be in cache (e.g. after invalidation or remove), then cache will treat this case as there is no value at all.

Note that cache is generic and you can only work with provided key and value types. If cache also contains keys or values of other types, any attempt to retrieve them will result in . Use ICache<TK, TV> in order to work with entries of arbitrary types.

All members are thread-safe and may be used concurrently from multiple threads.

Namespace: Apache.Ignite.Core.Cache

Assembly: Apache.Ignite.Core.dll

Syntax

public interface ICache<TK, TV>

Type Parameters

Name	Description
TK	Key type.
TV	Value type.

Properties

Ignite

Ignite hosting this cache.

Declaration

IIgnite Ignite { get; }

Property Value

Type	Description
IIgnite

IsAllowAtomicOpsInTx

Gets a value indicating whether to allow use atomic operations in transactions.

Declaration

bool IsAllowAtomicOpsInTx { get; }

Property Value

Type	Description
System.Boolean

IsKeepBinary

Gets a value indicating whether to keep values in binary form.

Declaration

bool IsKeepBinary { get; }

Property Value

Type	Description
System.Boolean

Item[TK]

Gets or sets a cache value with the specified key. Shortcut to Get(TK) and Put(TK, TV)

Declaration

TV this[TK key] { get; set; }

Parameters

Type	Name	Description
TK	key	Key.

Property Value

Type	Description
TV	Cache value with the specified key.

Name

Name of this cache (null for default cache).

Declaration

string Name { get; }

Property Value

Type	Description
System.String

Methods

Clear()

Clears the contents of the cache, without notifying listeners or CacheWriters.

Declaration

void Clear()

Clear(TK)

Clear entry from the cache and swap storage, without notifying listeners or CacheWriters. Entry is cleared only if it is not currently locked, and is not participating in a transaction.

Declaration

void Clear(TK key)

Parameters

Type	Name	Description
TK	key	Key to clear.

ClearAll(IEnumerable<TK>)

Clear entries from the cache and swap storage, without notifying listeners or CacheWriters. Entry is cleared only if it is not currently locked, and is not participating in a transaction.

Declaration

void ClearAll(IEnumerable<TK> keys)

Parameters

Type	Name	Description
IEnumerable<TK>	keys	Keys to clear.

ClearAllAsync(IEnumerable<TK>)

Clear entries from the cache and swap storage, without notifying listeners or CacheWriters. Entry is cleared only if it is not currently locked, and is not participating in a transaction.

Declaration

Task ClearAllAsync(IEnumerable<TK> keys)

Parameters

Type	Name	Description
IEnumerable<TK>	keys	Keys to clear.

Returns

Type	Description
Task

ClearAsync()

Clears the contents of the cache, without notifying listeners or CacheWriters.

Declaration

Task ClearAsync()

Returns

Type	Description
Task

ClearAsync(TK)

Clear entry from the cache and swap storage, without notifying listeners or CacheWriters. Entry is cleared only if it is not currently locked, and is not participating in a transaction.

Declaration

Task ClearAsync(TK key)

Parameters

Type	Name	Description
TK	key	Key to clear.

Returns

Type	Description
Task

ClearStatistics()

Clears cluster statistics for this cache.

Declaration

void ClearStatistics()

ContainsKey(TK)

Check if cache contains mapping for this key.

Declaration

bool ContainsKey(TK key)

Parameters

Type	Name	Description
TK	key	Key.

Returns

Type	Description
System.Boolean	True if cache contains mapping for this key.

ContainsKeyAsync(TK)

Check if cache contains mapping for this key.

Declaration

Task<bool> ContainsKeyAsync(TK key)

Parameters

Type	Name	Description
TK	key	Key.

Returns

Type	Description
Task<System.Boolean>	True if cache contains mapping for this key.

ContainsKeys(IEnumerable<TK>)

Check if cache contains mapping for these keys.

Declaration

bool ContainsKeys(IEnumerable<TK> keys)

Parameters

Type	Name	Description
IEnumerable<TK>	keys	Keys.

Returns

Type	Description
System.Boolean	True if cache contains mapping for all these keys.

ContainsKeysAsync(IEnumerable<TK>)

Check if cache contains mapping for these keys.

Declaration

Task<bool> ContainsKeysAsync(IEnumerable<TK> keys)

Parameters

Type	Name	Description
IEnumerable<TK>	keys	Keys.

Returns

Type	Description
Task<System.Boolean>	True if cache contains mapping for all these keys.

EnableStatistics(Boolean)

Sets statistics (metrics) enabled flag cluster wide for this cache.

Declaration

void EnableStatistics(bool enabled)

Parameters

Type	Name	Description
System.Boolean	enabled	Enabled flag

Get(TK)

Retrieves value mapped to the specified key from cache.

If the value is not present in cache, then it will be looked up from swap storage. If it's not present in swap, or if swap is disable, and if read-through is allowed, value will be loaded from persistent store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Declaration

TV Get(TK key)

Parameters

Type	Name	Description
TK	key	Key.

Returns

Type	Description
TV	Value.

GetAll(IEnumerable<TK>)

Retrieves values mapped to the specified keys from cache. If some value is not present in cache, then it will be looked up from swap storage. If it's not present in swap, or if swap is disabled, and if read-through is allowed, value will be loaded from persistent store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Declaration

ICollection<ICacheEntry<TK, TV>> GetAll(IEnumerable<TK> keys)

Parameters

Type	Name	Description
IEnumerable<TK>	keys	Keys.

Returns

Type	Description
ICollection<ICacheEntry<TK, TV>>	Map of key-value pairs.

GetAllAsync(IEnumerable<TK>)

Retrieves values mapped to the specified keys from cache. If some value is not present in cache, then it will be looked up from swap storage. If it's not present in swap, or if swap is disabled, and if read-through is allowed, value will be loaded from persistent store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Declaration

Task<ICollection<ICacheEntry<TK, TV>>> GetAllAsync(IEnumerable<TK> keys)

Parameters

Type	Name	Description
IEnumerable<TK>	keys	Keys.

Returns

Type	Description
Task<ICollection<ICacheEntry<TK, TV>>>	Map of key-value pairs.

GetAndPut(TK, TV)

Associates the specified value with the specified key in this cache, returning an existing value if one existed.

Declaration

CacheResult<TV> GetAndPut(TK key, TV val)

Parameters

Type	Name	Description
TK	key	Key with which the specified value is to be associated.
TV	val	Value to be associated with the specified key.

Returns

Type	Description
CacheResult<TV>	The value associated with the key at the start of the operation.

GetAndPutAsync(TK, TV)

Associates the specified value with the specified key in this cache, returning an existing value if one existed.

Declaration

Task<CacheResult<TV>> GetAndPutAsync(TK key, TV val)

Parameters

Type	Name	Description
TK	key	Key with which the specified value is to be associated.
TV	val	Value to be associated with the specified key.

Returns

Type	Description
Task<CacheResult<TV>>	The value associated with the key at the start of the operation.

GetAndPutIfAbsent(TK, TV)

Stores given key-value pair in cache only if cache had no previous mapping for it. If cache previously contained value for the given key, then this value is returned. In case of PARTITIONED or REPLICATED caches, the value will be loaded from the primary node, which in its turn may load the value from the swap storage, and consecutively, if it's not in swap, from the underlying persistent storage. If the returned value is not needed, method putxIfAbsent() should be used instead of this one to avoid the overhead associated with returning of the previous value. If write-through is enabled, the stored value will be persisted to store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Declaration

CacheResult<TV> GetAndPutIfAbsent(TK key, TV val)

Parameters

Type	Name	Description
TK	key	Key to store in cache.
TV	val	Value to be associated with the given key.

Returns

Type	Description
CacheResult<TV>	Previously contained value regardless of whether put happened or not.

GetAndPutIfAbsentAsync(TK, TV)

Stores given key-value pair in cache only if cache had no previous mapping for it. If cache previously contained value for the given key, then this value is returned. In case of PARTITIONED or REPLICATED caches, the value will be loaded from the primary node, which in its turn may load the value from the swap storage, and consecutively, if it's not in swap, from the underlying persistent storage. If the returned value is not needed, method putxIfAbsent() should be used instead of this one to avoid the overhead associated with returning of the previous value. If write-through is enabled, the stored value will be persisted to store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Declaration

Task<CacheResult<TV>> GetAndPutIfAbsentAsync(TK key, TV val)

Parameters

Type	Name	Description
TK	key	Key to store in cache.
TV	val	Value to be associated with the given key.

Returns

Type	Description
Task<CacheResult<TV>>	Previously contained value regardless of whether put happened or not.

GetAndRemove(TK)

Atomically removes the entry for a key only if currently mapped to some value.

Declaration

CacheResult<TV> GetAndRemove(TK key)

Parameters

Type	Name	Description
TK	key	Key with which the specified value is associated.

Returns

Type	Description
CacheResult<TV>	The value if one existed.

GetAndRemoveAsync(TK)

Atomically removes the entry for a key only if currently mapped to some value.

Declaration

Task<CacheResult<TV>> GetAndRemoveAsync(TK key)

Parameters

Type	Name	Description
TK	key	Key with which the specified value is associated.

Returns

Type	Description
Task<CacheResult<TV>>	The value if one existed.

GetAndReplace(TK, TV)

Atomically replaces the value for a given key if and only if there is a value currently mapped by the key.

Declaration

CacheResult<TV> GetAndReplace(TK key, TV val)

Parameters

Type	Name	Description
TK	key	Key with which the specified value is to be associated.
TV	val	Value to be associated with the specified key.

Returns

Type	Description
CacheResult<TV>	The previous value associated with the specified key.

GetAndReplaceAsync(TK, TV)

Atomically replaces the value for a given key if and only if there is a value currently mapped by the key.

Declaration

Task<CacheResult<TV>> GetAndReplaceAsync(TK key, TV val)

Parameters

Type	Name	Description
TK	key	Key with which the specified value is to be associated.
TV	val	Value to be associated with the specified key.

Returns

Type	Description
Task<CacheResult<TV>>	The previous value associated with the specified key.

GetAsync(TK)

Retrieves value mapped to the specified key from cache.

If the value is not present in cache, then it will be looked up from swap storage. If it's not present in swap, or if swap is disable, and if read-through is allowed, value will be loaded from persistent store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Declaration

Task<TV> GetAsync(TK key)

Parameters

Type	Name	Description
TK	key	Key.

Returns

Type	Description
Task<TV>	Value.

GetConfiguration()

Gets the cache configuration.

Declaration

CacheConfiguration GetConfiguration()

Returns

Type	Description
CacheConfiguration

GetLocalEntries(CachePeekMode[])

Get local cache entries.

Declaration

IEnumerable<ICacheEntry<TK, TV>> GetLocalEntries(params CachePeekMode[] peekModes)

Parameters

Type	Name	Description
CachePeekMode[]	peekModes	Peek modes.

Returns

Type	Description
IEnumerable<ICacheEntry<TK, TV>>	Enumerable instance.

GetLocalMetrics()

Gets local snapshot metrics (statistics) for this cache.

Declaration

ICacheMetrics GetLocalMetrics()

Returns

Type	Description
ICacheMetrics	Cache metrics.

GetLocalSize(CachePeekMode[])

Gets the number of all entries cached on this node.

Declaration

int GetLocalSize(params CachePeekMode[] modes)

Parameters

Type	Name	Description
CachePeekMode[]	modes	Optional peek modes. If not provided, then total cache size is returned.

Returns

Type	Description
System.Int32	Cache size on this node.

GetLocalSizeLong(CachePeekMode[])

Gets the number of all entries cached on this node as long value.

Declaration

long GetLocalSizeLong(params CachePeekMode[] modes)

Parameters

Type	Name	Description
CachePeekMode[]	modes	Optional peek modes. If not provided, then total cache size is returned.

Returns

Type	Description
System.Int64	Cache size on this node.

GetLocalSizeLong(Int32, CachePeekMode[])

Gets the number of all entries in a partition cached on this node as long value.

Declaration

long GetLocalSizeLong(int partition, params CachePeekMode[] modes)

Parameters

Type	Name	Description
System.Int32	partition	Cache partition.
CachePeekMode[]	modes	Optional peek modes. If not provided, then total cache size is returned.

Returns

Type	Description
System.Int64	Partition cache size on this node.

GetLostPartitions()

Gets lost partitions IDs.

See also PartitionLossPolicy and ResetLostPartitions(IEnumerable<String>).

Declaration

ICollection<int> GetLostPartitions()

Returns

Type	Description
ICollection<System.Int32>

GetMetrics()

Gets global (whole cluster) snapshot metrics (statistics) for this cache.

Declaration

ICacheMetrics GetMetrics()

Returns

Type	Description
ICacheMetrics	Cache metrics.

GetMetrics(IClusterGroup)

Gets global (whole cluster group) snapshot metrics (statistics) for this cache.

Declaration

ICacheMetrics GetMetrics(IClusterGroup clusterGroup)

Parameters

Type	Name	Description
IClusterGroup	clusterGroup	The cluster group to get metrics for.

Returns

Type	Description
ICacheMetrics

GetQueryMetrics()

Gets query metrics.

Declaration

IQueryMetrics GetQueryMetrics()

Returns

Type	Description
IQueryMetrics	Query metrics.

GetSize(CachePeekMode[])

Gets the number of all entries cached across all nodes.

NOTE: this operation is distributed and will query all participating nodes for their cache sizes.

Declaration

int GetSize(params CachePeekMode[] modes)

Parameters

Type	Name	Description
CachePeekMode[]	modes	Optional peek modes. If not provided, then total cache size is returned.

Returns

Type	Description
System.Int32	Cache size across all nodes.

GetSizeAsync(CachePeekMode[])

Gets the number of all entries cached across all nodes.

NOTE: this operation is distributed and will query all participating nodes for their cache sizes.

Declaration

Task<int> GetSizeAsync(params CachePeekMode[] modes)

Parameters

Type	Name	Description
CachePeekMode[]	modes	Optional peek modes. If not provided, then total cache size is returned.

Returns

Type	Description
Task<System.Int32>	Cache size across all nodes.

GetSizeLong(CachePeekMode[])

Gets the number of all entries cached across all nodes as long value.

NOTE: this operation is distributed and will query all participating nodes for their cache sizes.

Declaration

long GetSizeLong(params CachePeekMode[] modes)

Parameters

Type	Name	Description
CachePeekMode[]	modes	Optional peek modes. If not provided, then total cache size is returned.

Returns

Type	Description
System.Int64	Cache size across all nodes.

GetSizeLong(Int32, CachePeekMode[])

Gets the number of all entries in partition cached across all nodes as long value.

NOTE: this operation is distributed and will query all participating nodes for their cache sizes.

Declaration

long GetSizeLong(int partition, params CachePeekMode[] modes)

Parameters

Type	Name	Description
System.Int32	partition	Cache partition.
CachePeekMode[]	modes	Optional peek modes. If not provided, then total cache size is returned.

Returns

Type	Description
System.Int64	Partition cache size across all nodes.

GetSizeLongAsync(CachePeekMode[])

Gets the number of all entries cached across all nodes as long value.

NOTE: this operation is distributed and will query all participating nodes for their cache sizes.

Declaration

Task<long> GetSizeLongAsync(params CachePeekMode[] modes)

Parameters

Type	Name	Description
CachePeekMode[]	modes	Optional peek modes. If not provided, then total cache size is returned.

Returns

Type	Description
Task<System.Int64>	Cache size across all nodes.

GetSizeLongAsync(Int32, CachePeekMode[])

Gets the number of all entries in a partition cached across all nodes as long value.

NOTE: this operation is distributed and will query all participating nodes for their cache sizes.

Declaration

Task<long> GetSizeLongAsync(int partition, params CachePeekMode[] modes)

Parameters

Type	Name	Description
System.Int32	partition	Cache partition.
CachePeekMode[]	modes	Optional peek modes. If not provided, then total cache size is returned.

Returns

Type	Description
Task<System.Int64>	Partition cache size across all nodes.

Invoke<TArg, TRes>(TK, ICacheEntryProcessor<TK, TV, TArg, TRes>, TArg)

Invokes an ICacheEntryProcessor<TK, TV, TArg, TRes> against the IMutableCacheEntry<TK, TV> specified by the provided key. If an entry does not exist for the specified key, an attempt is made to load it (if a loader is configured) or a surrogate entry, consisting of the key with a null value is used instead.

Declaration

TRes Invoke<TArg, TRes>(TK key, ICacheEntryProcessor<TK, TV, TArg, TRes> processor, TArg arg)

Parameters

Type	Name	Description
TK	key	The key.
ICacheEntryProcessor<TK, TV, TArg, TRes>	processor	The processor.
TArg	arg	The argument.

Returns

Type	Description
TRes	Result of the processing.

Type Parameters

Name	Description
TArg	The type of the argument.
TRes	The type of the result.

Exceptions

Type	Condition
CacheEntryProcessorException	If an exception has occured during processing.

InvokeAll<TArg, TRes>(IEnumerable<TK>, ICacheEntryProcessor<TK, TV, TArg, TRes>, TArg)

Invokes an ICacheEntryProcessor<TK, TV, TArg, TRes> against a set of keys. If an entry does not exist for the specified key, an attempt is made to load it (if a loader is configured) or a surrogate entry, consisting of the key with a null value is used instead.

The order that the entries for the keys are processed is undefined. Implementations may choose to process the entries in any order, including concurrently. Furthermore there is no guarantee implementations will use the same processor instance to process each entry, as the case may be in a non-local cache topology.

Keys are locked in the order in which they are enumerated. It is caller's responsibility to make sure keys always follow same order, such as by using . Using unordered collection, such as , while calling this method in parallel will lead to deadlock.

Declaration

ICollection<ICacheEntryProcessorResult<TK, TRes>> InvokeAll<TArg, TRes>(IEnumerable<TK> keys, ICacheEntryProcessor<TK, TV, TArg, TRes> processor, TArg arg)

Parameters

Type	Name	Description
IEnumerable<TK>	keys	The keys.
ICacheEntryProcessor<TK, TV, TArg, TRes>	processor	The processor.
TArg	arg	The argument.

Returns

Type	Description
ICollection<ICacheEntryProcessorResult<TK, TRes>>	Map of ICacheEntryProcessorResult<TK, T> of the processing per key, if any, defined by the ICacheEntryProcessor<TK, TV, TArg, TRes> implementation. No mappings will be returned for processors that return a null value for a key.

Type Parameters

Name	Description
TArg	The type of the argument.
TRes	The type of the result.

Exceptions

Type	Condition
CacheEntryProcessorException	If an exception has occured during processing.

InvokeAllAsync<TArg, TRes>(IEnumerable<TK>, ICacheEntryProcessor<TK, TV, TArg, TRes>, TArg)

Invokes an ICacheEntryProcessor<TK, TV, TArg, TRes> against a set of keys. If an entry does not exist for the specified key, an attempt is made to load it (if a loader is configured) or a surrogate entry, consisting of the key with a null value is used instead.

The order that the entries for the keys are processed is undefined. Implementations may choose to process the entries in any order, including concurrently. Furthermore there is no guarantee implementations will use the same processor instance to process each entry, as the case may be in a non-local cache topology.

Keys are locked in the order in which they are enumerated. It is caller's responsibility to make sure keys always follow same order, such as by using . Using unordered collection, such as , while calling this method in parallel will lead to deadlock.

Declaration

Task<ICollection<ICacheEntryProcessorResult<TK, TRes>>> InvokeAllAsync<TArg, TRes>(IEnumerable<TK> keys, ICacheEntryProcessor<TK, TV, TArg, TRes> processor, TArg arg)

Parameters

Type	Name	Description
IEnumerable<TK>	keys	The keys.
ICacheEntryProcessor<TK, TV, TArg, TRes>	processor	The processor.
TArg	arg	The argument.

Returns

Type	Description
Task<ICollection<ICacheEntryProcessorResult<TK, TRes>>>	Map of ICacheEntryProcessorResult<TK, T> of the processing per key, if any, defined by the ICacheEntryProcessor<TK, TV, TArg, TRes> implementation. No mappings will be returned for processors that return a null value for a key.

Type Parameters

Name	Description
TArg	The type of the argument.
TRes	The type of the result.

Exceptions

Type	Condition
CacheEntryProcessorException	If an exception has occured during processing.

InvokeAsync<TArg, TRes>(TK, ICacheEntryProcessor<TK, TV, TArg, TRes>, TArg)

Invokes an ICacheEntryProcessor<TK, TV, TArg, TRes> against the IMutableCacheEntry<TK, TV> specified by the provided key. If an entry does not exist for the specified key, an attempt is made to load it (if a loader is configured) or a surrogate entry, consisting of the key with a null value is used instead.

Declaration

Task<TRes> InvokeAsync<TArg, TRes>(TK key, ICacheEntryProcessor<TK, TV, TArg, TRes> processor, TArg arg)

Parameters

Type	Name	Description
TK	key	The key.
ICacheEntryProcessor<TK, TV, TArg, TRes>	processor	The processor.
TArg	arg	The argument.

Returns

Type	Description
Task<TRes>	Result of the processing.

Type Parameters

Name	Description
TArg	The type of the argument.
TRes	The type of the result.

Exceptions

Type	Condition
CacheEntryProcessorException	If an exception has occured during processing.

IsEmpty()

Checks whether this cache contains no key-value mappings.

Semantically equals to ICache.Size(CachePeekMode.PRIMARY) == 0.

Declaration

bool IsEmpty()

Returns

Type	Description
System.Boolean

IsLocalLocked(TK, Boolean)

Checks if specified key is locked.

This is a local operation and does not involve any network trips or access to persistent storage in any way.

Declaration

bool IsLocalLocked(TK key, bool byCurrentThread)

Parameters

Type	Name	Description
TK	key	Key to check.
System.Boolean	byCurrentThread	If true, checks that current thread owns a lock on this key; otherwise, checks that any thread on any node owns a lock on this key.

Returns

Type	Description
System.Boolean	True if specified key is locked; otherwise, false.

LoadAll(IEnumerable<TK>, Boolean)

Loads the specified entries into the cache using the configured ICacheStore> for the given keys.

If an entry for a key already exists in the cache, a value will be loaded if and only if replaceExistingValues is true. If no loader is configured for the cache, no objects will be loaded.

Declaration

void LoadAll(IEnumerable<TK> keys, bool replaceExistingValues)

Parameters

Type	Name	Description
IEnumerable<TK>	keys	The keys to load.
System.Boolean	replaceExistingValues	if set to true, existing cache values will be replaced by those loaded from a cache store.

LoadAllAsync(IEnumerable<TK>, Boolean)

Asynchronously loads the specified entries into the cache using the configured ICacheStore> for the given keys.

If an entry for a key already exists in the cache, a value will be loaded if and only if replaceExistingValues is true. If no loader is configured for the cache, no objects will be loaded.

Declaration

Task LoadAllAsync(IEnumerable<TK> keys, bool replaceExistingValues)

Parameters

Type	Name	Description
IEnumerable<TK>	keys	The keys to load.
System.Boolean	replaceExistingValues	if set to true, existing cache values will be replaced by those loaded from a cache store.

Returns

Type	Description
Task

LoadCache(ICacheEntryFilter<TK, TV>, Object[])

Executes LocalLoadCache(ICacheEntryFilter<TK, TV>, Object[]) on all cache nodes.

Declaration

void LoadCache(ICacheEntryFilter<TK, TV> p, params object[] args)

Parameters

Type	Name	Description
ICacheEntryFilter<TK, TV>	p	Optional predicate. If provided, will be used to filter values to be put into cache.
System.Object[]	args	Optional user arguments to be passed into LoadCache(Action<TK, TV>, Object[]).

LoadCacheAsync(ICacheEntryFilter<TK, TV>, Object[])

Executes LocalLoadCache(ICacheEntryFilter<TK, TV>, Object[]) on all cache nodes.

Declaration

Task LoadCacheAsync(ICacheEntryFilter<TK, TV> p, params object[] args)

Parameters

Type	Name	Description
ICacheEntryFilter<TK, TV>	p	Optional predicate. If provided, will be used to filter values to be put into cache.
System.Object[]	args	Optional user arguments to be passed into LoadCache(Action<TK, TV>, Object[]).

Returns

Type	Description
Task

LocalClear(TK)

Clear entry from the cache and swap storage, without notifying listeners or CacheWriters. Entry is cleared only if it is not currently locked, and is not participating in a transaction.

Note that this operation is local as it merely clears an entry from local cache, it does not remove entries from remote caches.

Declaration

void LocalClear(TK key)

Parameters

Type	Name	Description
TK	key	Key to clear.

LocalClearAll(IEnumerable<TK>)

Clear entries from the cache and swap storage, without notifying listeners or CacheWriters. Entry is cleared only if it is not currently locked, and is not participating in a transaction.

Note that this operation is local as it merely clears entries from local cache, it does not remove entries from remote caches.

Declaration

void LocalClearAll(IEnumerable<TK> keys)

Parameters

Type	Name	Description
IEnumerable<TK>	keys	Keys to clear.

LocalEvict(IEnumerable<TK>)

Attempts to evict all entries associated with keys. Note, that entry will be evicted only if it's not used (not participating in any locks or transactions).

Declaration

void LocalEvict(IEnumerable<TK> keys)

Parameters

Type	Name	Description
IEnumerable<TK>	keys	Keys to evict from cache.

LocalLoadCache(ICacheEntryFilter<TK, TV>, Object[])

Delegates to LoadCache(Action<TK, TV>, Object[]) method to load state from the underlying persistent storage. The loaded values will then be given to the optionally passed in predicate, and, if the predicate returns true, will be stored in cache. If predicate is null, then all loaded values will be stored in cache.

Declaration

void LocalLoadCache(ICacheEntryFilter<TK, TV> p, params object[] args)

Parameters

Type	Name	Description
ICacheEntryFilter<TK, TV>	p	Optional predicate. If provided, will be used to filter values to be put into cache.
System.Object[]	args	Optional user arguments to be passed into LoadCache(Action<TK, TV>, Object[]).

LocalLoadCacheAsync(ICacheEntryFilter<TK, TV>, Object[])

Delegates to LoadCache(Action<TK, TV>, Object[]) method to load state from the underlying persistent storage. The loaded values will then be given to the optionally passed in predicate, and, if the predicate returns true, will be stored in cache. If predicate is null, then all loaded values will be stored in cache.

Declaration

Task LocalLoadCacheAsync(ICacheEntryFilter<TK, TV> p, params object[] args)

Parameters

Type	Name	Description
ICacheEntryFilter<TK, TV>	p	Optional predicate. If provided, will be used to filter values to be put into cache.
System.Object[]	args	Optional user arguments to be passed into LoadCache(Action<TK, TV>, Object[]).

Returns

Type	Description
Task

LocalPeek(TK, CachePeekMode[])

Peeks at cached value using optional set of peek modes. This method will sequentially iterate over given peek modes, and try to peek at value using each peek mode. Once a non-null value is found, it will be immediately returned. This method does not participate in any transactions, however, it may peek at transactional value depending on the peek modes used. If key is not present in cache, KeyNotFoundException will be thrown.

Declaration

TV LocalPeek(TK key, params CachePeekMode[] modes)

Parameters

Type	Name	Description
TK	key	Key.
CachePeekMode[]	modes	Peek modes.

Returns

Type	Description
TV	Peeked value.

LocalPreloadPartition(Int32)

Efficiently preloads cache partition into page memory if it exists on the local node.

This is useful for fast iteration over cache partition data if persistence is enabled and the data is "cold".

Preload will reduce available amount of page memory for subsequent operations and may lead to earlier page replacement.

This method is irrelevant for in-memory caches.

Declaration

bool LocalPreloadPartition(int partition)

Parameters

Type	Name	Description
System.Int32	partition	Partition number.

Returns

Type	Description
System.Boolean	True if partition was preloaded, False if it doesn't belong to local node.

Lock(TK)

Creates an ICacheLock instance associated with passed key. This method does not acquire lock immediately, you have to call appropriate method on returned instance.

Declaration

ICacheLock Lock(TK key)

Parameters

Type	Name	Description
TK	key	Key for lock.

Returns

Type	Description
ICacheLock	New ICacheLock instance associated with passed key.

LockAll(IEnumerable<TK>)

Creates an ICacheLock instance associated with passed keys. This method does not acquire lock immediately, you have to call appropriate method on returned instance.

Declaration

ICacheLock LockAll(IEnumerable<TK> keys)

Parameters

Type	Name	Description
IEnumerable<TK>	keys	Keys for lock.

Returns

Type	Description
ICacheLock	New ICacheLock instance associated with passed keys.

PreloadPartition(Int32)

Efficiently preloads cache partition into page memory.

This is useful for fast iteration over cache partition data if persistence is enabled and the data is "cold".

Preload will reduce available amount of page memory for subsequent operations and may lead to earlier page replacement.

This method is irrelevant for in-memory caches. Calling this method on an in-memory cache will result in exception.

Declaration

void PreloadPartition(int partition)

Parameters

Type	Name	Description
System.Int32	partition	Partition number.

PreloadPartitionAsync(Int32)

Efficiently preloads cache partition into page memory asynchronously.

This is useful for fast iteration over cache partition data if persistence is enabled and the data is "cold".

Preload will reduce available amount of page memory for subsequent operations and may lead to earlier page replacement.

This method is irrelevant for in-memory caches. Calling this method on an in-memory cache will result in exception.

Declaration

Task PreloadPartitionAsync(int partition)

Parameters

Type	Name	Description
System.Int32	partition	Partition number.

Returns

Type	Description
Task	Task.

Put(TK, TV)

Associates the specified value with the specified key in the cache.

If the cache previously contained a mapping for the key, the old value is replaced by the specified value.

Declaration

void Put(TK key, TV val)

Parameters

Type	Name	Description
TK	key	Key with which the specified value is to be associated.
TV	val	Value to be associated with the specified key.

PutAll(IEnumerable<KeyValuePair<TK, TV>>)

Stores given key-value pairs in cache. If write-through is enabled, the stored values will be persisted to store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Keys are locked in the order in which they are enumerated. It is caller's responsibility to make sure keys always follow same order, such as by using . Using unordered dictionary, such as , while calling this method in parallel will lead to deadlock.

Declaration

void PutAll(IEnumerable<KeyValuePair<TK, TV>> vals)

Parameters

Type	Name	Description
IEnumerable<KeyValuePair<TK, TV>>	vals	Key-value pairs to store in cache.

PutAllAsync(IEnumerable<KeyValuePair<TK, TV>>)

Stores given key-value pairs in cache. If write-through is enabled, the stored values will be persisted to store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Keys are locked in the order in which they are enumerated. It is caller's responsibility to make sure keys always follow same order, such as by using . Using unordered dictionary, such as , while calling this method in parallel will lead to deadlock.

Declaration

Task PutAllAsync(IEnumerable<KeyValuePair<TK, TV>> vals)

Parameters

Type	Name	Description
IEnumerable<KeyValuePair<TK, TV>>	vals	Key-value pairs to store in cache.

Returns

Type	Description
Task

PutAsync(TK, TV)

Associates the specified value with the specified key in the cache.

If the cache previously contained a mapping for the key, the old value is replaced by the specified value.

Declaration

Task PutAsync(TK key, TV val)

Parameters

Type	Name	Description
TK	key	Key with which the specified value is to be associated.
TV	val	Value to be associated with the specified key.

Returns

Type	Description
Task

PutIfAbsent(TK, TV)

Atomically associates the specified key with the given value if it is not already associated with a value.

Declaration

bool PutIfAbsent(TK key, TV val)

Parameters

Type	Name	Description
TK	key	Key with which the specified value is to be associated.
TV	val	Value to be associated with the specified key.

Returns

Type	Description
System.Boolean	True if a value was set.

PutIfAbsentAsync(TK, TV)

Atomically associates the specified key with the given value if it is not already associated with a value.

Declaration

Task<bool> PutIfAbsentAsync(TK key, TV val)

Parameters

Type	Name	Description
TK	key	Key with which the specified value is to be associated.
TV	val	Value to be associated with the specified key.

Returns

Type	Description
Task<System.Boolean>	True if a value was set.

Query(QueryBase)

Queries cache.

Declaration

IQueryCursor<ICacheEntry<TK, TV>> Query(QueryBase qry)

Parameters

Type	Name	Description
QueryBase	qry	Query.

Returns

Type	Description
IQueryCursor<ICacheEntry<TK, TV>>	Cursor.

Query(SqlFieldsQuery)

Queries separate entry fields.

Declaration

IFieldsQueryCursor Query(SqlFieldsQuery qry)

Parameters

Type	Name	Description
SqlFieldsQuery	qry	SQL fields query.

Returns

Type	Description
IFieldsQueryCursor	Cursor.

QueryContinuous(ContinuousQuery<TK, TV>)

Start continuous query execution.

Declaration

IContinuousQueryHandle QueryContinuous(ContinuousQuery<TK, TV> qry)

Parameters

Type	Name	Description
ContinuousQuery<TK, TV>	qry	Continuous query.

Returns

Type	Description
IContinuousQueryHandle	Handle to stop query execution.

QueryContinuous(ContinuousQuery<TK, TV>, QueryBase)

Start continuous query execution.

Declaration

IContinuousQueryHandle<ICacheEntry<TK, TV>> QueryContinuous(ContinuousQuery<TK, TV> qry, QueryBase initialQry)

Parameters

Type	Name	Description
ContinuousQuery<TK, TV>	qry	Continuous query.
QueryBase	initialQry	The initial query. This query will be executed before continuous listener is registered which allows to iterate through entries which have already existed at the time continuous query is executed.

Returns

Type	Description
IContinuousQueryHandle<ICacheEntry<TK, TV>>	Handle to get initial query cursor or stop query execution.

QueryContinuous(ContinuousQuery<TK, TV>, SqlFieldsQuery)

Start continuous query execution.

Declaration

IContinuousQueryHandleFields QueryContinuous(ContinuousQuery<TK, TV> qry, SqlFieldsQuery initialQry)

Parameters

Type	Name	Description
ContinuousQuery<TK, TV>	qry	Continuous query.
SqlFieldsQuery	initialQry	The initial fields query. This query will be executed before continuous listener is registered which allows to iterate through entries which have already existed at the time continuous query is executed.

Returns

Type	Description
IContinuousQueryHandleFields	Handle to get initial query cursor or stop query execution.

QueryFields(SqlFieldsQuery)

Queries separate entry fields.

Declaration

IQueryCursor<IList> QueryFields(SqlFieldsQuery qry)

Parameters

Type	Name	Description
SqlFieldsQuery	qry	SQL fields query.

Returns

Type	Description
IQueryCursor<IList>	Cursor.

Rebalance()

Rebalances cache partitions. This method is usually used when rebalanceDelay configuration parameter has non-zero value. When many nodes are started or stopped almost concurrently, it is more efficient to delay rebalancing until the node topology is stable to make sure that no redundant re-partitioning happens.

In case of partitioned caches, for better efficiency user should usually make sure that new nodes get placed on the same place of consistent hash ring as the left nodes, and that nodes are restarted before rebalanceDelay expires.

Declaration

Task Rebalance()

Returns

Type	Description
Task	Task that will be completed when rebalancing is finished.

Remove(TK)

Removes given key mapping from cache. If cache previously contained value for the given key, then this value is returned. In case of PARTITIONED or REPLICATED caches, the value will be loaded from the primary node, which in its turn may load the value from the disk-based swap storage, and consecutively, if it's not in swap, from the underlying persistent storage. If the returned value is not needed, method removex() should always be used instead of this one to avoid the overhead associated with returning of the previous value. If write-through is enabled, the value will be removed from store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Declaration

bool Remove(TK key)

Parameters

Type	Name	Description
TK	key	Key whose mapping is to be removed from cache.

Returns

Type	Description
System.Boolean	False if there was no matching key.

Remove(TK, TV)

Removes given key mapping from cache if one exists and value is equal to the passed in value. If write-through is enabled, the value will be removed from store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Declaration

bool Remove(TK key, TV val)

Parameters

Type	Name	Description
TK	key	Key whose mapping is to be removed from cache.
TV	val	Value to match against currently cached value.

Returns

Type	Description
System.Boolean	True if entry was removed, false otherwise.

RemoveAll()

Removes all mappings from cache. If write-through is enabled, the value will be removed from store. This method is not transactional.

Declaration

void RemoveAll()

RemoveAll(IEnumerable<TK>)

Removes given key mappings from cache. If write-through is enabled, the value will be removed from store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Keys are locked in the order in which they are enumerated. It is caller's responsibility to make sure keys always follow same order, such as by using . Using unordered collection, such as , while calling this method in parallel will lead to deadlock.

Declaration

void RemoveAll(IEnumerable<TK> keys)

Parameters

Type	Name	Description
IEnumerable<TK>	keys	Keys whose mappings are to be removed from cache.

RemoveAllAsync()

Removes all mappings from cache. If write-through is enabled, the value will be removed from store. This method is not transactional.

Declaration

Task RemoveAllAsync()

Returns

Type	Description
Task

RemoveAllAsync(IEnumerable<TK>)

Removes given key mappings from cache. If write-through is enabled, the value will be removed from store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Keys are locked in the order in which they are enumerated. It is caller's responsibility to make sure keys always follow same order, such as by using . Using unordered collection, such as , while calling this method in parallel will lead to deadlock.

Declaration

Task RemoveAllAsync(IEnumerable<TK> keys)

Parameters

Type	Name	Description
IEnumerable<TK>	keys	Keys whose mappings are to be removed from cache.

Returns

Type	Description
Task

RemoveAsync(TK)

Removes given key mapping from cache. If cache previously contained value for the given key, then this value is returned. In case of PARTITIONED or REPLICATED caches, the value will be loaded from the primary node, which in its turn may load the value from the disk-based swap storage, and consecutively, if it's not in swap, from the underlying persistent storage. If the returned value is not needed, method removex() should always be used instead of this one to avoid the overhead associated with returning of the previous value. If write-through is enabled, the value will be removed from store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Declaration

Task<bool> RemoveAsync(TK key)

Parameters

Type	Name	Description
TK	key	Key whose mapping is to be removed from cache.

Returns

Type	Description
Task<System.Boolean>	False if there was no matching key.

RemoveAsync(TK, TV)

Removes given key mapping from cache if one exists and value is equal to the passed in value. If write-through is enabled, the value will be removed from store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Declaration

Task<bool> RemoveAsync(TK key, TV val)

Parameters

Type	Name	Description
TK	key	Key whose mapping is to be removed from cache.
TV	val	Value to match against currently cached value.

Returns

Type	Description
Task<System.Boolean>	True if entry was removed, false otherwise.

Replace(TK, TV)

Stores given key-value pair in cache only if there is a previous mapping for it. If cache previously contained value for the given key, then this value is returned. In case of PARTITIONED or REPLICATED caches, the value will be loaded from the primary node, which in its turn may load the value from the swap storage, and consecutively, if it's not in swap, rom the underlying persistent storage. If write-through is enabled, the stored value will be persisted to store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Declaration

bool Replace(TK key, TV val)

Parameters

Type	Name	Description
TK	key	Key to store in cache.
TV	val	Value to be associated with the given key.

Returns

Type	Description
System.Boolean	True if the value was replaced.

Replace(TK, TV, TV)

Stores given key-value pair in cache only if only if the previous value is equal to the old value passed as argument. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Declaration

bool Replace(TK key, TV oldVal, TV newVal)

Parameters

Type	Name	Description
TK	key	Key to store in cache.
TV	oldVal	Old value to match.
TV	newVal	Value to be associated with the given key.

Returns

Type	Description
System.Boolean	True if replace happened, false otherwise.

ReplaceAsync(TK, TV)

Stores given key-value pair in cache only if there is a previous mapping for it. If cache previously contained value for the given key, then this value is returned. In case of PARTITIONED or REPLICATED caches, the value will be loaded from the primary node, which in its turn may load the value from the swap storage, and consecutively, if it's not in swap, rom the underlying persistent storage. If write-through is enabled, the stored value will be persisted to store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Declaration

Task<bool> ReplaceAsync(TK key, TV val)

Parameters

Type	Name	Description
TK	key	Key to store in cache.
TV	val	Value to be associated with the given key.

Returns

Type	Description
Task<System.Boolean>	True if the value was replaced.

ReplaceAsync(TK, TV, TV)

Stores given key-value pair in cache only if only if the previous value is equal to the old value passed as argument. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Declaration

Task<bool> ReplaceAsync(TK key, TV oldVal, TV newVal)

Parameters

Type	Name	Description
TK	key	Key to store in cache.
TV	oldVal	Old value to match.
TV	newVal	Value to be associated with the given key.

Returns

Type	Description
Task<System.Boolean>	True if replace happened, false otherwise.

ResetQueryMetrics()

Reset query metrics.

Declaration

void ResetQueryMetrics()

TryGet(TK, out TV)

Retrieves value mapped to the specified key from cache. If the value is not present in cache, then it will be looked up from swap storage. If it's not present in swap, or if swap is disable, and if read-through is allowed, value will be loaded from persistent store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Declaration

bool TryGet(TK key, out TV value)

Parameters

Type	Name	Description
TK	key	Key.
TV	value	When this method returns, the value associated with the specified key, if the key is found; otherwise, the default value for the type of the value parameter. This parameter is passed uninitialized.

Returns

Type	Description
System.Boolean	true if the cache contains an element with the specified key; otherwise, false.

TryGetAsync(TK)

Retrieves value mapped to the specified key from cache. If the value is not present in cache, then it will be looked up from swap storage. If it's not present in swap, or if swap is disable, and if read-through is allowed, value will be loaded from persistent store. This method is transactional and will enlist the entry into ongoing transaction if there is one.

Declaration

Task<CacheResult<TV>> TryGetAsync(TK key)

Parameters

Type	Name	Description
TK	key	Key.

Returns

Type	Description
Task<CacheResult<TV>>	CacheResult<T> containing a bool success flag and a value.

TryLocalPeek(TK, out TV, CachePeekMode[])

Peeks at cached value using optional set of peek modes. This method will sequentially iterate over given peek modes, and try to peek at value using each peek mode. Once a non-null value is found, it will be immediately returned. This method does not participate in any transactions, however, it may peek at transactional value depending on the peek modes used.

Declaration

bool TryLocalPeek(TK key, out TV value, params CachePeekMode[] modes)

Parameters

Type	Name	Description
TK	key	Key.
TV	value	When this method returns, the value associated with the specified key, if the key is found; otherwise, the default value for the type of the value parameter. This parameter is passed uninitialized.
CachePeekMode[]	modes	Peek modes.

Returns

Type	Description
System.Boolean	true if the cache contains an element with the specified key; otherwise, false.

WithAllowAtomicOpsInTx()

Get another cache instance with operations allowed in transactions. Only atomic caches need this. Transactional caches already available for transactions.

Declaration

ICache<TK, TV> WithAllowAtomicOpsInTx()

Returns

Type	Description
ICache<TK, TV>	Cache allowed to use in transactions.

WithExpiryPolicy(IExpiryPolicy)

Returns cache with the specified expired policy set. This policy will be used for each operation invoked on the returned cache.

Expiry durations for each operation are calculated only once and then used as constants. Please consider this when implementing custom expiry policy implementations.

Declaration

ICache<TK, TV> WithExpiryPolicy(IExpiryPolicy plc)

Parameters

Type	Name	Description
IExpiryPolicy	plc	Expiry policy to use.

Returns

Type	Description
ICache<TK, TV>	Cache instance with the specified expiry policy set.

WithKeepBinary<TK1, TV1>()

Gets cache with KeepBinary mode enabled, changing key and/or value types if necessary. You can only change key/value types when transitioning from non-binary to binary cache; Changing type of binary cache is not allowed and will throw an

Declaration

ICache<TK1, TV1> WithKeepBinary<TK1, TV1>()

Returns

Type	Description
ICache<TK1, TV1>	Cache instance with binary mode enabled.

Type Parameters

Name	Description
TK1	Key type in binary mode.
TV1	Value type in binary mode.

WithNoRetries()

Get another cache instance with no-retries behavior enabled.

Declaration

ICache<TK, TV> WithNoRetries()

Returns

Type	Description
ICache<TK, TV>	Cache with no-retries behavior enabled.

WithPartitionRecover()

Gets an instance of cache that will be allowed to execute cache operations (read, write) regardless of partition loss policy.

Declaration

ICache<TK, TV> WithPartitionRecover()

Returns

Type	Description
ICache<TK, TV>	Cache without partition loss protection.

WithSkipStore()

Get another cache instance with read-through and write-through behavior disabled.

Declaration

ICache<TK, TV> WithSkipStore()

Returns

Type	Description
ICache<TK, TV>	Cache with read-through and write-through behavior disabled.

Extension Methods

CacheLinqExtensions.AsCacheQueryable<TKey, TValue>(ICache<TKey, TValue>)

CacheLinqExtensions.AsCacheQueryable<TKey, TValue>(ICache<TKey, TValue>, Boolean)

CacheLinqExtensions.AsCacheQueryable<TKey, TValue>(ICache<TKey, TValue>, Boolean, String)

CacheLinqExtensions.AsCacheQueryable<TKey, TValue>(ICache<TKey, TValue>, QueryOptions)