From f479e745d5bdc1a00fbdfa1dd13d718ed4a20912 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Delaporte?= <12201973+fredericdelaporte@users.noreply.github.com> Date: Mon, 23 Dec 2019 00:53:05 +0100 Subject: [PATCH 1/4] Add StackExchangeRedis cache provider documentation --- doc/reference/modules/nhibernate_caches.xml | 58 +++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/doc/reference/modules/nhibernate_caches.xml b/doc/reference/modules/nhibernate_caches.xml index f7304d94c2f..0a3ad41cec4 100644 --- a/doc/reference/modules/nhibernate_caches.xml +++ b/doc/reference/modules/nhibernate_caches.xml @@ -112,6 +112,16 @@ + + NHibernate.Caches.StackExchangeRedis + + + Uses StackExchange.Redis. This provider is available as a .Net Standard + NuGet package. It can batch together puts and reads, reducing incurred IOs. + See . + + + NHibernate.Caches.CoreMemoryCache @@ -666,6 +676,54 @@ +
+ NHibernate.Caches.StackExchangeRedis Configuration + + NHibernate.Caches.StackExchangeRedis relies on StackExchange.Redis for the + underlying implementation. + The following NHibernate configuration settings are available: + + + + + cache.default_expiration + + Number of seconds to wait before expiring each item. + Defaults to 300. It can also be set programmatically on the NHibernate + configuration object under the name expiration, which then takes precedence + over cache.default_expiration. + + + + cache.use_sliding_expiration + + Should the expiration be sliding? A sliding expiration is reinitialized at each get. + Defaults to false. + + + + + + NHibernate.Caches.StackExchangeRedis has a config file section handler to allow configuring different expirations for + different regions. Here is an example: + + + + + + +
+ + + + + + +]]> + +
+
CoreMemoryCache Configuration From 25eb7d384fdea56a53d791b5a1ade3ffdcd7aa32 Mon Sep 17 00:00:00 2001 From: maca88 Date: Mon, 23 Dec 2019 17:10:12 +0100 Subject: [PATCH 2/4] Add extended documentation --- doc/reference/modules/nhibernate_caches.xml | 272 +++++++++++++++++++- 1 file changed, 268 insertions(+), 4 deletions(-) diff --git a/doc/reference/modules/nhibernate_caches.xml b/doc/reference/modules/nhibernate_caches.xml index 0a3ad41cec4..c7c8aafaec4 100644 --- a/doc/reference/modules/nhibernate_caches.xml +++ b/doc/reference/modules/nhibernate_caches.xml @@ -681,7 +681,7 @@ NHibernate.Caches.StackExchangeRedis relies on StackExchange.Redis for the underlying implementation. - The following NHibernate configuration settings are available: + The following NHibernate configuration settings are available (also defined in NHibernate.Caches.StackExchangeRedis.RedisEnvironment): @@ -697,10 +697,272 @@ cache.use_sliding_expiration - Should the expiration be sliding? A sliding expiration is reinitialized at each get. + Should the expiration be sliding? A sliding expiration is reinitialized at each get. Can be overriden for each region by using + sliding attribute. + Defaults to false. + + + + cache.database + + The default Redis database index, that can be overriden for each region by using database attribute. + Defaults to -1. + + + + cache.strategy + + The assembly qualified name of the region strategy, that can be overriden for each region by using strategy attribute. + NHibernate.Caches.StackExchangeRedis provides the following strategies: + + + NHibernate.Caches.StackExchangeRedis.DefaultRegionStrategy + + 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: + + cache.region_strategy.default.max_allowed_version + + The max allowed version number. When the max value is reached, the next value will be reset to zero. + Defaults to 10000. + + + + cache.region_strategy.default.use_pubsub + + Whether to use Redis pub/sub mechanism in order to notify other cache instances when the clear operation was performed. + Defaults to true. + + + + cache.region_strategy.default.retry_times + + Total retry times for read and lock operations, when concurrent clear operations are performed. + Defaults to 1. + + + + + + NHibernate.Caches.StackExchangeRedis.FastRegionStrategy + + Uses very simple read/write operations but does not support ICache.Clear operation. + + + + NHibernate.Caches.StackExchangeRedis.TwoLayerCacheRegionStrategy + + A strategy that extends NHibernate.Caches.StackExchangeRedis.DefaultRegionStrategy and uses + an additional local memory cache for faster readings. The local caches are invalidated by using Redis pubsub mechanism. + This strategy should be used only for regions that have few write operations and a high expiration time. + This strategy has additional settings: + + cache.region_strategy.two_layer_cache.use_pipelining + + Whether to use StackExchange.Redis pipelining feature. + Defaults to false. + + + + cache.region_strategy.two_layer_cache.client_id + + The client id used for cache invalidation. + Defaults to a random number. + + + + cache.region_strategy.two_layer_cache.max_synchronization_time + + The max synchronization time between caches in seconds. + Defaults to 10. + + + + + + NHibernate.Caches.StackExchangeRedis.FastTwoLayerCacheRegionStrategy + + A strategy that extends NHibernate.Caches.StackExchangeRedis.FastRegionStrategy and uses + an additional local memory cache for faster readings. The local caches are invalidated by using Redis pubsub mechanism. + This strategy does not support ICache.Clear operation and should be used only for regions that have + few write operations and a high expiration time. This strategy has additional settings: + + cache.region_strategy.fast_two_layer_cache.use_pipelining + + Whether to use StackExchange.Redis pipelining feature. + Defaults to false. + + + + cache.region_strategy.fast_two_layer_cache.client_id + + The client id used for cache invalidation. + Defaults to a random number. + + + + cache.region_strategy.fast_two_layer_cache.max_synchronization_time + + The max synchronization time between caches in seconds. + Defaults to 10. + + + + + + NHibernate.Caches.StackExchangeRedis.DistributedLocalCacheRegionStrategy + + Uses only a memory cache to store the values and uses Redis pubsub mechanism to synchronize data between other local caches. + The synchronization between caches is done by comparing the UTC DateTime.Ticks, which represent when the + operation was performed. When two operations have the same DateTime.Ticks, 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 NHibernate.Caches.StackExchangeRedis.TwoLayerCacheRegionStrategy, when the instances where the strategy + would run are ofter restarted/recycled. In order to use this strategy a custom ICacheRegionStrategyFactory + has to be provided (see cache.region_strategy_factory setting), where the strategy is created with a custom + RegionMemoryCacheBase implementation. This strategy has additional settings: + + cache.region_strategy.distributed_local_cache.use_pipelining + + Whether to use StackExchange.Redis pipelining feature. + Defaults to false. + + + + cache.region_strategy.distributed_local_cache.client_id + + The client id used for cache invalidation. + Defaults to a random number. + + + + cache.region_strategy.distributed_local_cache.max_synchronization_time + + The max synchronization time between caches in seconds. + Defaults to 10. + + + + + + Defaults to NHibernate.Caches.StackExchangeRedis.DefaultRegionStrategy. + + + + cache.append_hashcode + + Whether the hash code of the key should be added to the cache key. Can be overriden for each region by using append-hashcode attribute. Defaults to false. + + cache.key_prefix + + 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 NHibernate-Cache:. + + + + cache.environment_name + + 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 null. + + + + cache.serializer + + 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 NHibernate.Caches.Util.JsonSerializer package and setting + NHibernate.Caches.Util.JsonSerializer.JsonCacheSerializer, NHibernate.Caches.Util.JsonSerializer value instead. + Defaults to NHibernate.Caches.Common.BinaryCacheSerializer, NHibernate.Caches.Common. + + + + cache.region_strategy_factory + + The assembly qualified name of the region strategy factory. + Defaults to NHibernate.Caches.StackExchangeRedis.DefaultCacheRegionStrategyFactory. + + + + cache.connection_multiplexer_provider + + The assembly qualified name of the connection multiplexer provider. + Defaults to NHibernate.Caches.StackExchangeRedis.DefaultConnectionMultiplexerProvider. + + + + cache.connection_multiplexer_provider + + The assembly qualified name of the connection multiplexer provider. + Defaults to NHibernate.Caches.StackExchangeRedis.DefaultConnectionMultiplexerProvider. + + + + cache.database_provider + + The assembly qualified name of the database provider. + Defaults to NHibernate.Caches.StackExchangeRedis.DefaultDatabaseProvider. + + + + cache.lock.key_timeout + + The timeout for a lock key to expire in seconds. + Defaults to 5. + + + + cache.lock.acquire_timeout + + The time limit to acquire the lock in seconds. + Defaults to 5. + + + + cache.lock.retry_times + + The number of retries for acquiring the lock. + Defaults to 3. + + + + cache.lock.max_retry_delay + + The maximum delay before retrying to acquire the lock in milliseconds. + Defaults to 400. + + + + cache.lock.min_retry_delay + + The minimum delay before retrying to acquire the lock in milliseconds. + Defaults to 10. + + + + cache.lock.value_provider + + The assembly qualified name of the lock value provider. + Defaults to NHibernate.Caches.StackExchangeRedis.DefaultCacheLockValueProvider. + + + + cache.lock.retry_delay_provider + + The assembly qualified name of the lock retry delay provider. + Defaults to NHibernate.Caches.StackExchangeRedis.DefaultCacheLockRetryDelayProvider. + + + + cache.lock.key_suffix + + The suffix for the lock key. + Defaults to :lock. + + @@ -717,8 +979,10 @@ - - + + + ]]> From bd62a9b8426db24e4f4e65065bd11cf846599d2a Mon Sep 17 00:00:00 2001 From: maca88 Date: Mon, 23 Dec 2019 17:49:02 +0100 Subject: [PATCH 3/4] Minor corrections --- doc/reference/modules/nhibernate_caches.xml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/reference/modules/nhibernate_caches.xml b/doc/reference/modules/nhibernate_caches.xml index c7c8aafaec4..cd3027052f9 100644 --- a/doc/reference/modules/nhibernate_caches.xml +++ b/doc/reference/modules/nhibernate_caches.xml @@ -754,10 +754,10 @@ NHibernate.Caches.StackExchangeRedis.TwoLayerCacheRegionStrategy - A strategy that extends NHibernate.Caches.StackExchangeRedis.DefaultRegionStrategy and uses - an additional local memory cache for faster readings. The local caches are invalidated by using Redis pubsub mechanism. + Extends NHibernate.Caches.StackExchangeRedis.DefaultRegionStrategy 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 has additional settings: + This strategy inherits additional settings from DefaultRegionStrategy and also has its own settings: cache.region_strategy.two_layer_cache.use_pipelining @@ -784,8 +784,8 @@ NHibernate.Caches.StackExchangeRedis.FastTwoLayerCacheRegionStrategy - A strategy that extends NHibernate.Caches.StackExchangeRedis.FastRegionStrategy and uses - an additional local memory cache for faster readings. The local caches are invalidated by using Redis pubsub mechanism. + Extends NHibernate.Caches.StackExchangeRedis.FastRegionStrategy 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 ICache.Clear operation and should be used only for regions that have few write operations and a high expiration time. This strategy has additional settings: @@ -814,7 +814,7 @@ NHibernate.Caches.StackExchangeRedis.DistributedLocalCacheRegionStrategy - Uses only a memory cache to store the values and uses Redis pubsub mechanism to synchronize data between other local caches. + 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 DateTime.Ticks, which represent when the operation was performed. When two operations have the same DateTime.Ticks, 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 From c50b3913f11b9f3eecbe9ad8c567133c29566e45 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Delaporte?= <12201973+fredericdelaporte@users.noreply.github.com> Date: Tue, 24 Dec 2019 00:32:29 +0100 Subject: [PATCH 4/4] Fix some typo --- doc/reference/modules/nhibernate_caches.xml | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/doc/reference/modules/nhibernate_caches.xml b/doc/reference/modules/nhibernate_caches.xml index cd3027052f9..8425c1dd302 100644 --- a/doc/reference/modules/nhibernate_caches.xml +++ b/doc/reference/modules/nhibernate_caches.xml @@ -819,7 +819,7 @@ operation was performed. When two operations have the same DateTime.Ticks, 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 NHibernate.Caches.StackExchangeRedis.TwoLayerCacheRegionStrategy, when the instances where the strategy - would run are ofter restarted/recycled. In order to use this strategy a custom ICacheRegionStrategyFactory + would run are often restarted/recycled. In order to use this strategy a custom ICacheRegionStrategyFactory has to be provided (see cache.region_strategy_factory setting), where the strategy is created with a custom RegionMemoryCacheBase implementation. This strategy has additional settings: @@ -893,13 +893,6 @@ Defaults to NHibernate.Caches.StackExchangeRedis.DefaultConnectionMultiplexerProvider. - - cache.connection_multiplexer_provider - - The assembly qualified name of the connection multiplexer provider. - Defaults to NHibernate.Caches.StackExchangeRedis.DefaultConnectionMultiplexerProvider. - - cache.database_provider