Skip to content

Commit 25eb7d3

Browse files
maca88maca88
committed
Add extended documentation
1 parent f479e74 commit 25eb7d3

File tree

1 file changed

+268
-4
lines changed

1 file changed

+268
-4
lines changed

‎doc/reference/modules/nhibernate_caches.xml

Lines changed: 268 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -681,7 +681,7 @@
681681
<para>
682682
NHibernate.Caches.StackExchangeRedis relies on <classname>StackExchange.Redis</classname> for the
683683
underlying implementation.
684-
The following NHibernate configuration settings are available:
684+
The following NHibernate configuration settings are available (also defined in <literal>NHibernate.Caches.StackExchangeRedis.RedisEnvironment</literal>):
685685
</para>
686686

687687
<variablelist>
@@ -697,10 +697,272 @@
697697
<varlistentry>
698698
<term><literal>cache.use_sliding_expiration</literal></term>
699699
<listitem>
700-
Should the expiration be sliding? A sliding expiration is reinitialized at each get.
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+
A strategy that 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 pubsub mechanism.
759+
This strategy should be used only for regions that have few write operations and a high expiration time.
760+
This strategy has additional 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+
A strategy that 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 pubsub 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 pubsub 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 ofter 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.
701856
Defaults to <literal>false</literal>.
702857
</listitem>
703858
</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.connection_multiplexer_provider</literal></term>
898+
<listitem>
899+
The assembly qualified name of the connection multiplexer provider.
900+
Defaults to <literal>NHibernate.Caches.StackExchangeRedis.DefaultConnectionMultiplexerProvider</literal>.
901+
</listitem>
902+
</varlistentry>
903+
<varlistentry>
904+
<term><literal>cache.database_provider</literal></term>
905+
<listitem>
906+
The assembly qualified name of the database provider.
907+
Defaults to <literal>NHibernate.Caches.StackExchangeRedis.DefaultDatabaseProvider</literal>.
908+
</listitem>
909+
</varlistentry>
910+
<varlistentry>
911+
<term><literal>cache.lock.key_timeout</literal></term>
912+
<listitem>
913+
The timeout for a lock key to expire in seconds.
914+
Defaults to <literal>5</literal>.
915+
</listitem>
916+
</varlistentry>
917+
<varlistentry>
918+
<term><literal>cache.lock.acquire_timeout</literal></term>
919+
<listitem>
920+
The time limit to acquire the lock in seconds.
921+
Defaults to <literal>5</literal>.
922+
</listitem>
923+
</varlistentry>
924+
<varlistentry>
925+
<term><literal>cache.lock.retry_times</literal></term>
926+
<listitem>
927+
The number of retries for acquiring the lock.
928+
Defaults to <literal>3</literal>.
929+
</listitem>
930+
</varlistentry>
931+
<varlistentry>
932+
<term><literal>cache.lock.max_retry_delay</literal></term>
933+
<listitem>
934+
The maximum delay before retrying to acquire the lock in milliseconds.
935+
Defaults to <literal>400</literal>.
936+
</listitem>
937+
</varlistentry>
938+
<varlistentry>
939+
<term><literal>cache.lock.min_retry_delay</literal></term>
940+
<listitem>
941+
The minimum delay before retrying to acquire the lock in milliseconds.
942+
Defaults to <literal>10</literal>.
943+
</listitem>
944+
</varlistentry>
945+
<varlistentry>
946+
<term><literal>cache.lock.value_provider</literal></term>
947+
<listitem>
948+
The assembly qualified name of the lock value provider.
949+
Defaults to <literal>NHibernate.Caches.StackExchangeRedis.DefaultCacheLockValueProvider</literal>.
950+
</listitem>
951+
</varlistentry>
952+
<varlistentry>
953+
<term><literal>cache.lock.retry_delay_provider</literal></term>
954+
<listitem>
955+
The assembly qualified name of the lock retry delay provider.
956+
Defaults to <literal>NHibernate.Caches.StackExchangeRedis.DefaultCacheLockRetryDelayProvider</literal>.
957+
</listitem>
958+
</varlistentry>
959+
<varlistentry>
960+
<term><literal>cache.lock.key_suffix</literal></term>
961+
<listitem>
962+
The suffix for the lock key.
963+
Defaults to <literal>:lock</literal>.
964+
</listitem>
965+
</varlistentry>
704966
</variablelist>
705967

706968
<para>
@@ -717,8 +979,10 @@
717979
</configSections>
718980
719981
<redis>
720-
<cache region="foo" expiration="500" />
721-
<cache region="bar" expiration="300" sliding="true" />
982+
<cache region="foo" expiration="500" database="1" />
983+
<cache region="bar" sliding="true" append-hashcode="true" />
984+
<cache region="baz"
985+
strategy="NHibernate.Caches.StackExchangeRedis.FastRegionStrategy, NHibernate.Caches" />
722986
</redis>
723987
</configuration>]]></programlisting>
724988
</example>

0 commit comments

Comments
 (0)