Skip to content

Commit 1920603

Browse files
fredericDelaportemaca88
fredericDelaporte
and
maca88
authored
Add StackExchangeRedis cache provider documentation (#2294)
Co-authored-by: maca88 <bostjan.markezic@siol.net>
1 parent 42c2f9b commit 1920603

File tree

1 file changed

+315
-0
lines changed

1 file changed

+315
-0
lines changed

‎doc/reference/modules/nhibernate_caches.xml

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,16 @@
112112
</para>
113113
</listitem>
114114
</varlistentry>
115+
<varlistentry>
116+
<term><classname>NHibernate.Caches.StackExchangeRedis</classname></term>
117+
<listitem>
118+
<para>
119+
Uses <classname>StackExchange.Redis</classname>. This provider is available as a .Net Standard
120+
NuGet package. It can batch together puts and reads, reducing incurred IOs.
121+
See <xref linkend="NHibernate.Caches.StackExchangeRedis" />.
122+
</para>
123+
</listitem>
124+
</varlistentry>
115125
<varlistentry>
116126
<term><classname>NHibernate.Caches.CoreMemoryCache</classname></term>
117127
<listitem>
@@ -666,6 +676,311 @@
666676
</example>
667677
</section>
668678

679+
<section id="NHibernate.Caches.StackExchangeRedis">
680+
<title>NHibernate.Caches.StackExchangeRedis Configuration</title>
681+
<para>
682+
NHibernate.Caches.StackExchangeRedis relies on <classname>StackExchange.Redis</classname> for the
683+
underlying implementation.
684+
The following NHibernate configuration settings are available (also defined in <literal>NHibernate.Caches.StackExchangeRedis.RedisEnvironment</literal>):
685+
</para>
686+
687+
<variablelist>
688+
<varlistentry>
689+
<term><literal>cache.default_expiration</literal></term>
690+
<listitem>
691+
Number of seconds to wait before expiring each item.
692+
Defaults to <literal>300</literal>. It can also be set programmatically on the NHibernate
693+
configuration object under the name <literal>expiration</literal>, which then takes precedence
694+
over <literal>cache.default_expiration</literal>.
695+
</listitem>
696+
</varlistentry>
697+
<varlistentry>
698+
<term><literal>cache.use_sliding_expiration</literal></term>
699+
<listitem>
700+
Should the expiration be sliding? A sliding expiration is reinitialized at each get. Can be overriden for each region by using
701+
<literal>sliding</literal> attribute.
702+
Defaults to <literal>false</literal>.
703+
</listitem>
704+
</varlistentry>
705+
<varlistentry>
706+
<term><literal>cache.database</literal></term>
707+
<listitem>
708+
The default Redis database index, that can be overriden for each region by using <literal>database</literal> attribute.
709+
Defaults to <literal>-1</literal>.
710+
</listitem>
711+
</varlistentry>
712+
<varlistentry>
713+
<term><literal>cache.strategy</literal></term>
714+
<listitem>
715+
The assembly qualified name of the region strategy, that can be overriden for each region by using <literal>strategy</literal> attribute.
716+
<literal>NHibernate.Caches.StackExchangeRedis</literal> provides the following strategies:
717+
<itemizedlist>
718+
<listitem>
719+
<literal>NHibernate.Caches.StackExchangeRedis.DefaultRegionStrategy</literal>
720+
<para>
721+
Uses a special key that contains the region current version number which is appended after the region prefix.
722+
Each time a clear operation is performed the version number is increased and an event is send to all clients
723+
so that they can update their local versions. Even if the event was not sent to all clients, each operation has a
724+
version check in order to prevent working with stale data. This strategy has additional settings:
725+
<varlistentry>
726+
<term><literal>cache.region_strategy.default.max_allowed_version</literal></term>
727+
<listitem>
728+
The max allowed version number. When the max value is reached, the next value will be reset to zero.
729+
Defaults to <literal>10000</literal>.
730+
</listitem>
731+
</varlistentry>
732+
<varlistentry>
733+
<term><literal>cache.region_strategy.default.use_pubsub</literal></term>
734+
<listitem>
735+
Whether to use Redis pub/sub mechanism in order to notify other cache instances when the clear operation was performed.
736+
Defaults to <literal>true</literal>.
737+
</listitem>
738+
</varlistentry>
739+
<varlistentry>
740+
<term><literal>cache.region_strategy.default.retry_times</literal></term>
741+
<listitem>
742+
Total retry times for read and lock operations, when concurrent clear operations are performed.
743+
Defaults to <literal>1</literal>.
744+
</listitem>
745+
</varlistentry>
746+
</para>
747+
</listitem>
748+
<listitem>
749+
<literal>NHibernate.Caches.StackExchangeRedis.FastRegionStrategy</literal>
750+
<para>
751+
Uses very simple read/write operations but does not support <literal>ICache.Clear</literal> operation.
752+
</para>
753+
</listitem>
754+
<listitem>
755+
<literal>NHibernate.Caches.StackExchangeRedis.TwoLayerCacheRegionStrategy</literal>
756+
<para>
757+
Extends <literal>NHibernate.Caches.StackExchangeRedis.DefaultRegionStrategy</literal> and uses
758+
an additional local memory cache for faster readings. The local caches are invalidated by using Redis pub/sub mechanism.
759+
This strategy should be used only for regions that have few write operations and a high expiration time.
760+
This strategy inherits additional settings from <literal>DefaultRegionStrategy</literal> and also has its own settings:
761+
<varlistentry>
762+
<term><literal>cache.region_strategy.two_layer_cache.use_pipelining</literal></term>
763+
<listitem>
764+
Whether to use <literal>StackExchange.Redis</literal> pipelining feature.
765+
Defaults to <literal>false</literal>.
766+
</listitem>
767+
</varlistentry>
768+
<varlistentry>
769+
<term><literal>cache.region_strategy.two_layer_cache.client_id</literal></term>
770+
<listitem>
771+
The client id used for cache invalidation.
772+
Defaults to a random number.
773+
</listitem>
774+
</varlistentry>
775+
<varlistentry>
776+
<term><literal>cache.region_strategy.two_layer_cache.max_synchronization_time</literal></term>
777+
<listitem>
778+
The max synchronization time between caches in seconds.
779+
Defaults to <literal>10</literal>.
780+
</listitem>
781+
</varlistentry>
782+
</para>
783+
</listitem>
784+
<listitem>
785+
<literal>NHibernate.Caches.StackExchangeRedis.FastTwoLayerCacheRegionStrategy</literal>
786+
<para>
787+
Extends <literal>NHibernate.Caches.StackExchangeRedis.FastRegionStrategy</literal> and uses
788+
an additional local memory cache for faster readings. The local caches are invalidated by using Redis pub/sub mechanism.
789+
This strategy does not support <literal>ICache.Clear</literal> operation and should be used only for regions that have
790+
few write operations and a high expiration time. This strategy has additional settings:
791+
<varlistentry>
792+
<term><literal>cache.region_strategy.fast_two_layer_cache.use_pipelining</literal></term>
793+
<listitem>
794+
Whether to use <literal>StackExchange.Redis</literal> pipelining feature.
795+
Defaults to <literal>false</literal>.
796+
</listitem>
797+
</varlistentry>
798+
<varlistentry>
799+
<term><literal>cache.region_strategy.fast_two_layer_cache.client_id</literal></term>
800+
<listitem>
801+
The client id used for cache invalidation.
802+
Defaults to a random number.
803+
</listitem>
804+
</varlistentry>
805+
<varlistentry>
806+
<term><literal>cache.region_strategy.fast_two_layer_cache.max_synchronization_time</literal></term>
807+
<listitem>
808+
The max synchronization time between caches in seconds.
809+
Defaults to <literal>10</literal>.
810+
</listitem>
811+
</varlistentry>
812+
</para>
813+
</listitem>
814+
<listitem>
815+
<literal>NHibernate.Caches.StackExchangeRedis.DistributedLocalCacheRegionStrategy</literal>
816+
<para>
817+
Uses only a memory cache to store the values and uses Redis pub/sub mechanism to synchronize data between other local caches.
818+
The synchronization between caches is done by comparing the UTC <literal>DateTime.Ticks</literal>, which represent when the
819+
operation was performed. When two operations have the same <literal>DateTime.Ticks</literal>, then the client with the highest
820+
id wins. This strategy should be used only for regions that have few write operations and a high expiration time. It is recommended
821+
to use <literal>NHibernate.Caches.StackExchangeRedis.TwoLayerCacheRegionStrategy</literal>, when the instances where the strategy
822+
would run are often restarted/recycled. In order to use this strategy a custom <literal>ICacheRegionStrategyFactory</literal>
823+
has to be provided (see <literal>cache.region_strategy_factory</literal> setting), where the strategy is created with a custom
824+
<literal>RegionMemoryCacheBase</literal> implementation. This strategy has additional settings:
825+
<varlistentry>
826+
<term><literal>cache.region_strategy.distributed_local_cache.use_pipelining</literal></term>
827+
<listitem>
828+
Whether to use <literal>StackExchange.Redis</literal> pipelining feature.
829+
Defaults to <literal>false</literal>.
830+
</listitem>
831+
</varlistentry>
832+
<varlistentry>
833+
<term><literal>cache.region_strategy.distributed_local_cache.client_id</literal></term>
834+
<listitem>
835+
The client id used for cache invalidation.
836+
Defaults to a random number.
837+
</listitem>
838+
</varlistentry>
839+
<varlistentry>
840+
<term><literal>cache.region_strategy.distributed_local_cache.max_synchronization_time</literal></term>
841+
<listitem>
842+
The max synchronization time between caches in seconds.
843+
Defaults to <literal>10</literal>.
844+
</listitem>
845+
</varlistentry>
846+
</para>
847+
</listitem>
848+
</itemizedlist>
849+
Defaults to <literal>NHibernate.Caches.StackExchangeRedis.DefaultRegionStrategy</literal>.
850+
</listitem>
851+
</varlistentry>
852+
<varlistentry>
853+
<term><literal>cache.append_hashcode</literal></term>
854+
<listitem>
855+
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.
856+
Defaults to <literal>false</literal>.
857+
</listitem>
858+
</varlistentry>
859+
<varlistentry>
860+
<term><literal>cache.key_prefix</literal></term>
861+
<listitem>
862+
The prefix that will be prepended before each cache key in order to avoid having collisions when multiple clients uses the same Redis database.
863+
Defaults to <literal>NHibernate-Cache:</literal>.
864+
</listitem>
865+
</varlistentry>
866+
<varlistentry>
867+
<term><literal>cache.environment_name</literal></term>
868+
<listitem>
869+
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.
870+
Defaults to <literal>null</literal>.
871+
</listitem>
872+
</varlistentry>
873+
<varlistentry>
874+
<term><literal>cache.serializer</literal></term>
875+
<listitem>
876+
The assembly qualified name of the serializer that is used to serialize/deserialize the key values. Optionally, a faster json serializer can be
877+
used by installing <literal>NHibernate.Caches.Util.JsonSerializer</literal> package and setting
878+
<literal>NHibernate.Caches.Util.JsonSerializer.JsonCacheSerializer, NHibernate.Caches.Util.JsonSerializer</literal> value instead.
879+
Defaults to <literal>NHibernate.Caches.Common.BinaryCacheSerializer, NHibernate.Caches.Common</literal>.
880+
</listitem>
881+
</varlistentry>
882+
<varlistentry>
883+
<term><literal>cache.region_strategy_factory</literal></term>
884+
<listitem>
885+
The assembly qualified name of the region strategy factory.
886+
Defaults to <literal>NHibernate.Caches.StackExchangeRedis.DefaultCacheRegionStrategyFactory</literal>.
887+
</listitem>
888+
</varlistentry>
889+
<varlistentry>
890+
<term><literal>cache.connection_multiplexer_provider</literal></term>
891+
<listitem>
892+
The assembly qualified name of the connection multiplexer provider.
893+
Defaults to <literal>NHibernate.Caches.StackExchangeRedis.DefaultConnectionMultiplexerProvider</literal>.
894+
</listitem>
895+
</varlistentry>
896+
<varlistentry>
897+
<term><literal>cache.database_provider</literal></term>
898+
<listitem>
899+
The assembly qualified name of the database provider.
900+
Defaults to <literal>NHibernate.Caches.StackExchangeRedis.DefaultDatabaseProvider</literal>.
901+
</listitem>
902+
</varlistentry>
903+
<varlistentry>
904+
<term><literal>cache.lock.key_timeout</literal></term>
905+
<listitem>
906+
The timeout for a lock key to expire in seconds.
907+
Defaults to <literal>5</literal>.
908+
</listitem>
909+
</varlistentry>
910+
<varlistentry>
911+
<term><literal>cache.lock.acquire_timeout</literal></term>
912+
<listitem>
913+
The time limit to acquire the lock in seconds.
914+
Defaults to <literal>5</literal>.
915+
</listitem>
916+
</varlistentry>
917+
<varlistentry>
918+
<term><literal>cache.lock.retry_times</literal></term>
919+
<listitem>
920+
The number of retries for acquiring the lock.
921+
Defaults to <literal>3</literal>.
922+
</listitem>
923+
</varlistentry>
924+
<varlistentry>
925+
<term><literal>cache.lock.max_retry_delay</literal></term>
926+
<listitem>
927+
The maximum delay before retrying to acquire the lock in milliseconds.
928+
Defaults to <literal>400</literal>.
929+
</listitem>
930+
</varlistentry>
931+
<varlistentry>
932+
<term><literal>cache.lock.min_retry_delay</literal></term>
933+
<listitem>
934+
The minimum delay before retrying to acquire the lock in milliseconds.
935+
Defaults to <literal>10</literal>.
936+
</listitem>
937+
</varlistentry>
938+
<varlistentry>
939+
<term><literal>cache.lock.value_provider</literal></term>
940+
<listitem>
941+
The assembly qualified name of the lock value provider.
942+
Defaults to <literal>NHibernate.Caches.StackExchangeRedis.DefaultCacheLockValueProvider</literal>.
943+
</listitem>
944+
</varlistentry>
945+
<varlistentry>
946+
<term><literal>cache.lock.retry_delay_provider</literal></term>
947+
<listitem>
948+
The assembly qualified name of the lock retry delay provider.
949+
Defaults to <literal>NHibernate.Caches.StackExchangeRedis.DefaultCacheLockRetryDelayProvider</literal>.
950+
</listitem>
951+
</varlistentry>
952+
<varlistentry>
953+
<term><literal>cache.lock.key_suffix</literal></term>
954+
<listitem>
955+
The suffix for the lock key.
956+
Defaults to <literal>:lock</literal>.
957+
</listitem>
958+
</varlistentry>
959+
</variablelist>
960+
961+
<para>
962+
NHibernate.Caches.StackExchangeRedis has a config file section handler to allow configuring different expirations for
963+
different regions. Here is an example:
964+
</para>
965+
966+
<example>
967+
<programlisting><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
968+
<configuration>
969+
<configSections>
970+
<section name="redis"
971+
type="NHibernate.Caches.StackExchangeRedis.RedisSectionHandler, NHibernate.Caches.StackExchangeRedis" />
972+
</configSections>
973+
974+
<redis>
975+
<cache region="foo" expiration="500" database="1" />
976+
<cache region="bar" sliding="true" append-hashcode="true" />
977+
<cache region="baz"
978+
strategy="NHibernate.Caches.StackExchangeRedis.FastRegionStrategy, NHibernate.Caches" />
979+
</redis>
980+
</configuration>]]></programlisting>
981+
</example>
982+
</section>
983+
669984
<section id="NHibernate.Caches.CoreMemoryCache">
670985
<title>CoreMemoryCache Configuration</title>
671986
<para>

0 commit comments

Comments
 (0)