Skip to content

Add StackExchangeRedis cache provider documentation #2294

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Dec 27, 2019
Merged

Add StackExchangeRedis cache provider documentation #2294

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f479e74
Add StackExchangeRedis cache provider documentation
fredericDelaporte Dec 22, 2019
25eb7d3
Add extended documentation
maca88 Dec 23, 2019
bd62a9b
Minor corrections
maca88 Dec 23, 2019
c50b391
Fix some typo
fredericDelaporte Dec 23, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
315 changes: 315 additions & 0 deletions doc/reference/modules/nhibernate_caches.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,16 @@
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><classname>NHibernate.Caches.StackExchangeRedis</classname></term>
<listitem>
<para>
Uses <classname>StackExchange.Redis</classname>. This provider is available as a .Net Standard
NuGet package. It can batch together puts and reads, reducing incurred IOs.
See <xref linkend="NHibernate.Caches.StackExchangeRedis" />.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><classname>NHibernate.Caches.CoreMemoryCache</classname></term>
<listitem>
Expand Down Expand Up @@ -666,6 +676,311 @@
</example>
</section>

<section id="NHibernate.Caches.StackExchangeRedis">
<title>NHibernate.Caches.StackExchangeRedis Configuration</title>
<para>
NHibernate.Caches.StackExchangeRedis relies on <classname>StackExchange.Redis</classname> for the
underlying implementation.
The following NHibernate configuration settings are available (also defined in <literal>NHibernate.Caches.StackExchangeRedis.RedisEnvironment</literal>):
</para>

<variablelist>
<varlistentry>
<term><literal>cache.default_expiration</literal></term>
<listitem>
Number of seconds to wait before expiring each item.
Defaults to <literal>300</literal>. It can also be set programmatically on the NHibernate
configuration object under the name <literal>expiration</literal>, which then takes precedence
over <literal>cache.default_expiration</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.use_sliding_expiration</literal></term>
<listitem>
Should the expiration be sliding? A sliding expiration is reinitialized at each get. Can be overriden for each region by using
<literal>sliding</literal> attribute.
Defaults to <literal>false</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.database</literal></term>
<listitem>
The default Redis database index, that can be overriden for each region by using <literal>database</literal> attribute.
Defaults to <literal>-1</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.strategy</literal></term>
<listitem>
The assembly qualified name of the region strategy, that can be overriden for each region by using <literal>strategy</literal> attribute.
<literal>NHibernate.Caches.StackExchangeRedis</literal> provides the following strategies:
<itemizedlist>
<listitem>
<literal>NHibernate.Caches.StackExchangeRedis.DefaultRegionStrategy</literal>
<para>
Uses a special key that contains the region current version number which is appended after the region prefix.
Each time a clear operation is performed the version number is increased and an event is send to all clients
so that they can update their local versions. Even if the event was not sent to all clients, each operation has a
version check in order to prevent working with stale data. This strategy has additional settings:
<varlistentry>
<term><literal>cache.region_strategy.default.max_allowed_version</literal></term>
<listitem>
The max allowed version number. When the max value is reached, the next value will be reset to zero.
Defaults to <literal>10000</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.region_strategy.default.use_pubsub</literal></term>
<listitem>
Whether to use Redis pub/sub mechanism in order to notify other cache instances when the clear operation was performed.
Defaults to <literal>true</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.region_strategy.default.retry_times</literal></term>
<listitem>
Total retry times for read and lock operations, when concurrent clear operations are performed.
Defaults to <literal>1</literal>.
</listitem>
</varlistentry>
</para>
</listitem>
<listitem>
<literal>NHibernate.Caches.StackExchangeRedis.FastRegionStrategy</literal>
<para>
Uses very simple read/write operations but does not support <literal>ICache.Clear</literal> operation.
</para>
</listitem>
<listitem>
<literal>NHibernate.Caches.StackExchangeRedis.TwoLayerCacheRegionStrategy</literal>
<para>
Extends <literal>NHibernate.Caches.StackExchangeRedis.DefaultRegionStrategy</literal> and uses
an additional local memory cache for faster readings. The local caches are invalidated by using Redis pub/sub mechanism.
This strategy should be used only for regions that have few write operations and a high expiration time.
This strategy inherits additional settings from <literal>DefaultRegionStrategy</literal> and also has its own settings:
<varlistentry>
<term><literal>cache.region_strategy.two_layer_cache.use_pipelining</literal></term>
<listitem>
Whether to use <literal>StackExchange.Redis</literal> pipelining feature.
Defaults to <literal>false</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.region_strategy.two_layer_cache.client_id</literal></term>
<listitem>
The client id used for cache invalidation.
Defaults to a random number.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.region_strategy.two_layer_cache.max_synchronization_time</literal></term>
<listitem>
The max synchronization time between caches in seconds.
Defaults to <literal>10</literal>.
</listitem>
</varlistentry>
</para>
</listitem>
<listitem>
<literal>NHibernate.Caches.StackExchangeRedis.FastTwoLayerCacheRegionStrategy</literal>
<para>
Extends <literal>NHibernate.Caches.StackExchangeRedis.FastRegionStrategy</literal> and uses
an additional local memory cache for faster readings. The local caches are invalidated by using Redis pub/sub mechanism.
This strategy does not support <literal>ICache.Clear</literal> operation and should be used only for regions that have
few write operations and a high expiration time. This strategy has additional settings:
<varlistentry>
<term><literal>cache.region_strategy.fast_two_layer_cache.use_pipelining</literal></term>
<listitem>
Whether to use <literal>StackExchange.Redis</literal> pipelining feature.
Defaults to <literal>false</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.region_strategy.fast_two_layer_cache.client_id</literal></term>
<listitem>
The client id used for cache invalidation.
Defaults to a random number.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.region_strategy.fast_two_layer_cache.max_synchronization_time</literal></term>
<listitem>
The max synchronization time between caches in seconds.
Defaults to <literal>10</literal>.
</listitem>
</varlistentry>
</para>
</listitem>
<listitem>
<literal>NHibernate.Caches.StackExchangeRedis.DistributedLocalCacheRegionStrategy</literal>
<para>
Uses only a memory cache to store the values and uses Redis pub/sub mechanism to synchronize data between other local caches.
The synchronization between caches is done by comparing the UTC <literal>DateTime.Ticks</literal>, which represent when the
operation was performed. When two operations have the same <literal>DateTime.Ticks</literal>, then the client with the highest
id wins. This strategy should be used only for regions that have few write operations and a high expiration time. It is recommended
to use <literal>NHibernate.Caches.StackExchangeRedis.TwoLayerCacheRegionStrategy</literal>, when the instances where the strategy
would run are often restarted/recycled. In order to use this strategy a custom <literal>ICacheRegionStrategyFactory</literal>
has to be provided (see <literal>cache.region_strategy_factory</literal> setting), where the strategy is created with a custom
<literal>RegionMemoryCacheBase</literal> implementation. This strategy has additional settings:
<varlistentry>
<term><literal>cache.region_strategy.distributed_local_cache.use_pipelining</literal></term>
<listitem>
Whether to use <literal>StackExchange.Redis</literal> pipelining feature.
Defaults to <literal>false</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.region_strategy.distributed_local_cache.client_id</literal></term>
<listitem>
The client id used for cache invalidation.
Defaults to a random number.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.region_strategy.distributed_local_cache.max_synchronization_time</literal></term>
<listitem>
The max synchronization time between caches in seconds.
Defaults to <literal>10</literal>.
</listitem>
</varlistentry>
</para>
</listitem>
</itemizedlist>
Defaults to <literal>NHibernate.Caches.StackExchangeRedis.DefaultRegionStrategy</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.append_hashcode</literal></term>
<listitem>
Whether the hash code of the key should be added to the cache key. Can be overriden for each region by using <literal>append-hashcode</literal> attribute.
Defaults to <literal>false</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.key_prefix</literal></term>
<listitem>
The prefix that will be prepended before each cache key in order to avoid having collisions when multiple clients uses the same Redis database.
Defaults to <literal>NHibernate-Cache:</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.environment_name</literal></term>
<listitem>
The name of the environment that will be prepended before each cache key in order to allow having multiple environments on the same Redis database.
Defaults to <literal>null</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.serializer</literal></term>
<listitem>
The assembly qualified name of the serializer that is used to serialize/deserialize the key values. Optionally, a faster json serializer can be
used by installing <literal>NHibernate.Caches.Util.JsonSerializer</literal> package and setting
<literal>NHibernate.Caches.Util.JsonSerializer.JsonCacheSerializer, NHibernate.Caches.Util.JsonSerializer</literal> value instead.
Defaults to <literal>NHibernate.Caches.Common.BinaryCacheSerializer, NHibernate.Caches.Common</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.region_strategy_factory</literal></term>
<listitem>
The assembly qualified name of the region strategy factory.
Defaults to <literal>NHibernate.Caches.StackExchangeRedis.DefaultCacheRegionStrategyFactory</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.connection_multiplexer_provider</literal></term>
<listitem>
The assembly qualified name of the connection multiplexer provider.
Defaults to <literal>NHibernate.Caches.StackExchangeRedis.DefaultConnectionMultiplexerProvider</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.database_provider</literal></term>
<listitem>
The assembly qualified name of the database provider.
Defaults to <literal>NHibernate.Caches.StackExchangeRedis.DefaultDatabaseProvider</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.lock.key_timeout</literal></term>
<listitem>
The timeout for a lock key to expire in seconds.
Defaults to <literal>5</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.lock.acquire_timeout</literal></term>
<listitem>
The time limit to acquire the lock in seconds.
Defaults to <literal>5</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.lock.retry_times</literal></term>
<listitem>
The number of retries for acquiring the lock.
Defaults to <literal>3</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.lock.max_retry_delay</literal></term>
<listitem>
The maximum delay before retrying to acquire the lock in milliseconds.
Defaults to <literal>400</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.lock.min_retry_delay</literal></term>
<listitem>
The minimum delay before retrying to acquire the lock in milliseconds.
Defaults to <literal>10</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.lock.value_provider</literal></term>
<listitem>
The assembly qualified name of the lock value provider.
Defaults to <literal>NHibernate.Caches.StackExchangeRedis.DefaultCacheLockValueProvider</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.lock.retry_delay_provider</literal></term>
<listitem>
The assembly qualified name of the lock retry delay provider.
Defaults to <literal>NHibernate.Caches.StackExchangeRedis.DefaultCacheLockRetryDelayProvider</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>cache.lock.key_suffix</literal></term>
<listitem>
The suffix for the lock key.
Defaults to <literal>:lock</literal>.
</listitem>
</varlistentry>
</variablelist>

<para>
NHibernate.Caches.StackExchangeRedis has a config file section handler to allow configuring different expirations for
different regions. Here is an example:
</para>

<example>
<programlisting><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<configSections>
<section name="redis"
type="NHibernate.Caches.StackExchangeRedis.RedisSectionHandler, NHibernate.Caches.StackExchangeRedis" />
</configSections>

<redis>
<cache region="foo" expiration="500" database="1" />
<cache region="bar" sliding="true" append-hashcode="true" />
<cache region="baz"
strategy="NHibernate.Caches.StackExchangeRedis.FastRegionStrategy, NHibernate.Caches" />
</redis>
</configuration>]]></programlisting>
</example>
</section>

<section id="NHibernate.Caches.CoreMemoryCache">
<title>CoreMemoryCache Configuration</title>
<para>
Expand Down