// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements.  See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to You under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License.  You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
= .NET Platform Cache

CAUTION: Experimental API

Ignite.NET provides an additional layer of caching in the link:https://docs.microsoft.com/en-us/dotnet/standard/clr[CLR] heap. The platform cache keeps a deserialized copy of every cache entry that is present on the current node, thus greatly improving cache read performance at the cost of increased memory usage.

[NOTE]
====
Platform caches are bypassed within transactions: when a transaction is active, `cache.Get` and the other APIs listed below do not use the platform cache. Transaction support is coming soon.
====


== Configuring Platform Cache

:dotnetCodeFile: code-snippets/dotnet/PlatformCache.cs


=== 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 in real time and they are guaranteed to be up to date at any given moment, even before user code accesses them.

CAUTION: Platform cache effectively doubles memory usage on server nodes, every cache entry is stored twice: serialized in unmanaged (offheap) memory, and deserialized in CLR heap.

[tabs]
--
tab:C#/.NET[]
[source,csharp]
----
include::{dotnetCodeFile}[tag=platformCacheConf,indent=0]
----
--


=== Client Nodes

Platform caches on client nodes require a link:configuring-caches/near-cache[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. the near cache eviction policy effectively applies to the platform cache.

[tabs]
--
tab:C#/.NET[]
[source,csharp]
----
include::{dotnetCodeFile}[tag=platformCacheConfClient,indent=0]
----
--


== Supported APIs

The following `ICache<K, V>` APIs use a platform cache (including the corresponding async versions):

* `Get`, `TryGet`, indexer (`ICache[k]`)
* `GetAll` (reads from the platform cache first and falls back to the distributed cache when necessary)
* `ContainsKey`, `ContainsKeys`
* `LocalPeek`, `TryLocalPeek`
* `GetLocalEntries`
* `GetLocalSize`
* `Query` with `ScanQuery`
** Uses the platform cache to pass values to `ScanQuery.Filter`
** Iterates over the 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 a Platform Cache. Existing calls to `ICache.Get` and other APIs listed above will be served from the platform cache when possible, improving performance. When a given entry is not present in the platform cache, Ignite falls back to a normal path and retrieves the value from the cluster.

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

[tabs]
--
tab:C#/.NET[]
[source,csharp]
----
include::{dotnetCodeFile}[tag=platformCacheAccess,indent=0]
----
--


== Advanced Configuration

=== Binary Mode

In order to use link:key-value-api/binary-objects[Binary Objects] together with platform cache, set `PlatformCacheConfiguration.KeepBinary` to `true`:

[tabs]
--
tab:C#/.NET[]
[source,csharp]
----
include::{dotnetCodeFile}[tag=advancedConfigBinaryMode,indent=0]
----
--


=== Key and Value Types

When using Ignite cache with link:https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/value-types[Value Types], you should set `PlatformCacheConfiguration.KeyTypeName` and `ValueTypeName` accordingly to achieve maximum performance and reduce GC pressure:

[tabs]
--
tab:C#/.NET[]
[source,csharp]
----
include::{dotnetCodeFile}[tag=advancedConfigKeyValTypes,indent=0]
----
--

Ignite uses `ConcurrentDictionary<object, object>` by default to store platform cache data, because the actual types are  unknown beforehand. This results in link:https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/types/boxing-and-unboxing[boxing and unboxing] for value types, reducing performance and allocating more memory. When `KeyTypeName` and `ValueTypeName` are set in `PlatformCacheConfiguration`, Ignite uses those types to create an internal `ConcurrentDictionary` instead of the default `object`.

CAUTION: Incorrect `KeyTypeName` and/or `ValueTypeName` settings can cause runtime cast exceptions.