Table of Contents

Configuring Cache Policies

The ScaleOut client library can use settings in a configuration file to set policies on objects stored in a Cache.

When a CacheBuilder is used to create a Cache instance, an IConfiguration instance can be passed to the constructor. If no IConfiguration object is supplied then default policies will be used.

Values specified in a config file can be overridden at runtime using methods on the CacheBuilder instance. Some policies, such as timeouts and dependencies, can be also be overridden on an object-by-object basis at runtime using the CreatePolicy class.

Example

{
  "Scaleout.Client": {

    "customerCacheConfig": {
      "ExclusiveLockRetryIntervalMS": 5,
      "Timeout": "00:45:00",
      "ClientCacheEviction": "LRU",
      "ClientCacheCapacity": 1000,
      "CoherencyInterval": "00:00:00"
    },

    "productCacheConfig": {
      "ExclusiveLockRetryIntervalMS": 5,
      "Timeout": "2.00:00:00",
      "ClientCacheEviction": "LRU",
      "ClientCacheCapacity": 250,
      "CoherencyInterval": "00:01:00"
    }
  }
}

The following parameters can be configured under each cache entry in a config file. They are presented here in lower camel case because the traditional .NET Framework's XML configuration API is case-sensitive. However, .NET Core's configuration API is case-insensitive, so in .NET Core the keys may follow the JSON convention of beginning with an upper-case letter (as in the example above).

  • cacheConfigName - Required for .NET Framework XML configuration. The name identifying the cache configuration. Matches the value passed into the LegacyXmlConfiguration constructor.

  • timeout - The lifetime of objects in this cache, with a minimum granularity of one second. Use 00:00:00 for an infinite timeout. The default is 00:00:00 (infinite).

    The timeout value is a string that is parsed using the same rules as TimeSpan.Parse.

    If the value is not infinite, the maximum allowed timeout is 48.13:05:03 (48 days, 13 hours, 5 minutes, 3 seconds).

    Timeouts for individual objects can override this setting when they are added to the cache using the CreatePolicy.Timeout property.

  • timeoutType - The conditions under which an object's timeout will be reset. The value must be one of the following:

    • "Absolute" - Default. An object's timeout is never reset.
    • "Sliding" - An object's timeout is reset every time an object is accessed (either updated or read).
    • "ResetOnUpdate" - An object's timeout is reset when the object is updated, but it is not reset if the object is read.

  • clientCacheCapacity - Specifies the capacity of the in-process client cache.

    If the clientCacheEviction strategy is set to "lru" or "random", this value specifies the number of deserialized objects that can be held.

    If the clientCacheEviction strategy is set to "lru-maxmemory" or "random-maxmemory", this value specifies the amount of memory (in megabytes) of object data that can be held.

    The default value is 1000. Set to zero to disable the client cache.

  • clientCacheEviction - The eviction strategy used by the in-process client cache when it reaches capacity. The value must be one of the following:

    • "lru" - Default. Removes the least-recently-used object once the client cache's object count exceeds the specified threshold.
    • "random" - Removes a random object once the client cache's object count exceeds the specified threshold.
    • "lru-maxmemory" - Removes the least-recently-used object(s) based on the estimated memory usage of the client cache.
    • "random-maxmemory" - Removes a random object(s) based on the estimated memory usage of the client cache.

  • clientCachePartitions - Specifies the number of internal partitions in the in-process client cache.

    The default value is 1. Set to zero to use the number of logical processors on the machine.

    Increasing the client cache's partition count will reduce lock contention and improve scalability in the client cache when operating under heavy load with a large number of threads. However, more partitions will decrease the accuracy of LRU eviction--each partition maintains its own independent LRU list, so an evicted object may not be the least-recently accessed objects across all the partitions.

  • coherencyInterval - The maximum amount of time that can elapse before the client library performs a round-trip to the authoritative ScaleOut service. During this interval, a requested object can be returned directly from the in-process cache (which results in very good performance, but the returned value could be stale). The default value is "00:00:00" (the cache is fully coherent).

    The value is a string that is parsed using the same rules as TimeSpan.Parse.

  • exclusiveLockRetryIntervalMS - Specifies the number of milliseconds between lock retries when attempting to lock an object in the ScaleOut data grid that is already locked by another client. The default is 5 milliseconds, with a minimum allowed value of 1.

    A Cache will repeatedly attempt to acquire a lock in situations where another client already has a lock on the object. The exclusiveLockRetryIntervalMS value sets the amount of time between attempts to acquire an exclusive lock on the cached object when using exclusive locking calls (such as ReadExclusiveAsync).

  • networkCacheSizeBytes - The size (in bytes) of the in-process network cache that is used to improve performance when retrieving deep copies of objects or when the deserialized client cache is disabled. The default value is 0 bytes.

  • keystringCacheSize - The size of the in-process cache of keys that is maintained when a cache uses arbitrary-length strings as its key type. The default is 10,000 keys, and the setting is ignored if a cache does not use string keys.

    Consider using a large keystring cache in PMI invocation handler applications or other applications that process a high number of events from the ServiceEvents class. A keystring cache that is large enough to hold all object keys involved in repeated Invoke operations will reduce round trips to the ScaleOut service.

    Applications that perform query operations that return large numbers of string keys may also benefit from a large keystring cache.

  • preemptionPriority - The preemption priority for objects in the cache, which specifies whether the least recently accessed objects may be evicted when the ScaleOut service runs low on memory. The value must be one of the following:

    • "Normal" - Default. Objects may be removed from the cache if needed by the ScaleOut service when running under low-memory conditions.
    • "NotRemovable" - Objects must remain in the ScaleOut service until its expiration is reached or the object is explicitly removed.

  • backingStoreMode - Specifies the type of backing store event that should fire for objects in the cache. The value must be one of the following:

    • "None" - Default. Objects do not participate in backing store integration.
    • "WriteBehind" - A write-behind event should be periodically fired.
    • "RefreshAhead" - A refresh-ahead event should be periodically fired.

  • backingStoreEventInterval - The interval between backing store events (read-ahead, write-behind) for objects in the cache. The default is 00:04:00 (four minutes).

    This value is a string that is parsed using the same rules as TimeSpan.Parse.

    The maximum allowed backing store interval is 48.13:05:03 (48 days, 13 hours, 5 minutes, 3 seconds).

  • geoServerPushPolicy - Specifies whether the cache participates in GeoServer Push replication. (GeoServer DR must be licensed and the ScaleOut service must be configured for GeoServer Push replication, otherwise this parameter is ignored). The value must be one of the following:

    • "AllowReplication" - Default. The cache will participate in GeoServer replication (if enabled), replicating objects to a remote ScaleOut cluster.
    • "Disabled" - GeoServer replication will not be performed for this cache.

  • geoServerPullPolicy - Specifies whether the cache participates in GeoServer Pull replication. (GeoServer Pro must be licensed and the ScaleOut service must be configured for GeoServer Pull replication, otherwise this parameter is ignored). The value must be one of the following:

    • "Disabled" - Default. Remote stores will not be allowed to access objects in this cache via GeoServer Pull replication.
    • "AllowRemoteAccess" - Remote access will be allowed.

  • geoServerCoherencyPolicy - Sets the policy for how GeoServer remote stores should refresh their proxies to objects in the cache when GeoServer Pull replication is being used. (GeoServer Pro must be licensed and the ScaleOut service must be configured for GeoServer Pull replication, otherwise this parameter is ignored). The value must be one of the following:

    • "NoAutoRefresh" - Default. Proxy objects in other stores should not be refreshed automatically.
    • "Poll" - Proxy objects will be periodically refreshed in remote stores. Use the geoServerCoherencyInterval value to specify the frequency.
    • "Notify" - Remote stores will be notified of changes to the object so they can refresh their proxy object.

  • geoServerCoherencyInterval - Specifies how often GeoServer remote stores will refresh their proxies to objects in the cache if the Poll policy is used with GeoServer pull replication. The default value is four minutes.

  • remoteStores - A comma-separated list of GeoServer remote store names that this cache should use to look for objects that are not found in the local store. Read calls will check remote stores in the order that they are listed. If a missing object is found in one of the specified remote stores then it will be replicated to the local store using GeoServer Pro replication. The specified name(s) must exactly match the names of remote stores that are configured for GeoServer pull replication.