GridGain Developers Hub
GitHub logo GridGain iso GridGain.com
GridGain Software Documentation

.NET Platform Cache

GridGain.NET provides additional layer of caching in the CLR heap. Platform cache keeps a deserialized copy of every cache entry that is present on the current node, greatly improving cache read performance in exchange for increased memory usage.

Configuring Platform Cache

Server Nodes

Platform cache is configured once for all server nodes by setting CacheConfiguration.PlatformCacheConfiguration to a non-null value. Platform cache on server nodes stores all primary and backup cache entries assigned to the given node in .NET memory. Entries are updated synchronously - they are guaranteed to be up to date at any moment, even before user code accesses them.

var cacheCfg = new CacheConfiguration("my-cache")
{
    PlatformCacheConfiguration = new PlatformCacheConfiguration()
};

var cache = ignite.CreateCache<int, string>(cacheCfg);

Client Nodes

Platform cache on client nodes requires a Near Cache to be configured, since client nodes do not store data otherwise. The platform cache on a client node keeps the same set of entries as the near cache on that node. Near cache eviction policy effectively applies to platform cache.

var nearCacheCfg = new NearCacheConfiguration
{
    // Keep up to 1000 most recently used entries in Near and Platform caches.
    EvictionPolicy = new LruEvictionPolicy
    {
        MaxSize = 1000
    }
};

var cache = ignite.CreateNearCache<int, string>("my-cache",
    nearCacheCfg,
    new PlatformCacheConfiguration());

Supported APIs

The following ICache<K, V> APIs use platform cache (including corresponding async variants):

  • Get, TryGet, indexer (ICache[k])

  • GetAll (reads from platform cache first, falls back to distributed cache when necessary)

  • ContainsKey, ContainsKeys

  • LocalPeek, TryLocalPeek

  • GetLocalEntries

  • GetLocalSize

  • Query with ScanQuery

    • Uses platform cache to pass values to ScanQuery.Filter

    • Iterates over platform cache directly when ScanQuery.Local is true and ScanQuery.Partition is not null

Access Platform Cache Data Directly

You don’t need to change your code to take advantage of Platform Cache. Existing calls to ICache.Get and other APIs listed above will be served from platform cache when possible, improving performance. When a given entry is not present in the platform cache, GridGain falls back to a normal path and retrieves the value from the cluster.

However, in some cases we may want to access platform cache only, avoiding Java and network calls. Local APIs in combination with CachePeekMode.Platform allow us to do just that:

var cache = ignite.GetCache<int, string>("my-cache");

// Get value from platform cache.
bool hasKey = cache.TryLocalPeek(1, out var val, CachePeekMode.Platform);

// Get platform cache size (current number of entries on local node).
int size = cache.GetLocalSize(CachePeekMode.Platform);

// Get all values from platform cache.
IEnumerable<ICacheEntry<int, string>> entries = cache.GetLocalEntries(CachePeekMode.Platform);

Advanced Configuration

Binary Mode

In order to use Binary Objects together with platform cache, set PlatformCacheConfiguration.KeepBinary to true:

var cacheCfg = new CacheConfiguration("people")
{
    PlatformCacheConfiguration = new PlatformCacheConfiguration
    {
        KeepBinary = true
    }
};

var cache = ignite.CreateCache<int, Person>(cacheCfg)
    .WithKeepBinary<int, IBinaryObject>();

IBinaryObject binaryPerson = cache.Get(1);

Key and Value Types

When using GridGain cache with Value Types, it is important to set PlatformCacheConfiguration.KeyTypeName and ValueTypeName accordingly to achieve maximum performance and reduce GC pressure:

var cacheCfg = new CacheConfiguration("people")
{
    PlatformCacheConfiguration = new PlatformCacheConfiguration
    {
        KeyTypeName = typeof(long).FullName,
        ValueTypeName = typeof(Guid).FullName
    }
};

var cache = ignite.CreateCache<long, Guid>(cacheCfg);

GridGain uses ConcurrentDictionary<object, object> by default to store platform cache data, because actual types are not known beforehand. This causes boxing and unboxing for value types, reducing performance and allocating more memory. When KeyTypeName and ValueTypeName are set in PlatformCacheConfiguration, GridGain uses those types to create internal ConcurrentDictionary instead of default object.