NamedCacheAllowClientCaching Property

ScaleOut Software NamedCache API
Gets/sets an flag indicating whether (deserialized) objects accessed by this cache should be kept in a client-side cache when they are written to StateServer. Default is true.

Namespace:  Soss.Client
Assembly:  soss_namedcache (in soss_namedcache.dll) Version:

public bool AllowClientCaching { get; set; }

Property Value

Type: Boolean

To maximize access performance, SOSS adds an internal cache for deserialized data objects within its .NET client libraries. When reading objects, this client-side cache reduces access response time by eliminating data motion and deserialization overhead for objects that have not been updated in the SOSS distributed store. The AllowClientCaching property controls whether the NamedCache will take advantage of this behavior.

The contents of the deserialized cache will automatically be invalidated if the object is changed or removed by any of the servers in the farm, so it will never return a stale version of the shared object. The client libraries always check with the SOSS service prior to returning the object in order to make sure that the deserialized version is up-to-date. While this check does involve a round-trip to the service, it is still much faster than retrieving and deserializing the entire object.

By default, AllowClientCaching is set to true. Set this property to false prior to adding or updating an object in the cache to prevent a deserialized copy of the object from being stored in the .NET client library. Setting AllowClientCaching to false also ensures that any deserialized copies that were previously held by this client will no longer be used.

The size of the deserialized cache is determined by the max_client_cache parameter in the soss_params.txt file (located in the ScaleOut StateServer program directory). By default, the cache can consume up to 100000 KB (100 MB) of memory. Once the limit has been met, the least recently used items will be purged from the cache to make way for new items. Setting the max_client_cache parameter to 0 will disable the deserialized cache entirely, even if AllowClientCaching is true.

Guidelines for Using the Deserialized Cache

The deserialized client cache, which is enabled by default, is a collection of object references retained by the SOSS client library to accelerate multiple retrieve accesses to an object stored in the SOSS service. Changes made by client code to an object held in the deserialized cache may cause the deserialized cache to return the changed object on a subsequent retrieve instead of the version that is stored in the SOSS service.

The deserialized cache is only intended to be used with either read-only access or in a locked retrieve/update usage pattern. In the retrieve/update usage pattern, an object stored in the SOSS service is retrieved and locked, optionally updated, and then unlocked (either by the update or by an explicit unlock access). This pattern enables multiple processes on the same or different servers to reliably update a shared object. No changes should be made to the retrieved object outside of the retrieve/update pair because these changes would not be propagated to the distributed cache.

Sometimes a client application may want to retrieve an object from SOSS, make some changes to the object, and then discard it after using it without persisting the changes to the SOSS service. This usage model can cause the deserialized cache to get out of sync with SOSS. If an application requires that changes be made to a retrieved object outside of the above read/update usage pattern, steps should be taken to avoid corrupting the deserialized cache. Either the cache should be disabled by setting the AllowClientCaching property to false, or a deep copy of the retrieved object should be made with changes made only to this copy. Doing this will keep the locally cached object from getting out of sync with the authoritative object that is kept in the SOSS service.


NamedCache cache = CacheFactory.GetCache("myCache");

// Setting the AllowClientCaching property to false before updating/adding it 
// will ensure that the object will not be stored in the client-side cache:
cache.AllowClientCaching = false;
cache.Add("myObjId", "This is an object in the named cache.");
See Also