ScaleOut C++ Native Client API
5.1
|
The abstract TypedNamedCache template provides access to a strongly-typed named collection of objects that can be shared across multiple clients. More...
#include <typed_named_cache.h>
Public Member Functions | |
virtual | ~TypedNamedCache () |
Destructor. | |
PutResult | put (SossKey key, const boost::shared_ptr< T > obj_ptr, const ObjectPolicy &obj_policy=ObjectPolicy::CACHE_DEFAULTS, const PutOptions &options=PutOptions::CACHE_DEFAULTS) |
Inserts or updates an object in the named cache. More... | |
PutResult | insert (SossKey key, const boost::shared_ptr< T > obj_ptr, const ObjectPolicy &obj_policy=ObjectPolicy::CACHE_DEFAULTS, const PutOptions &options=PutOptions::CACHE_DEFAULTS) |
Inserts an object into the named cache. More... | |
PutResult | insert_and_lock (SossKey key, const boost::shared_ptr< T > obj_ptr, const ObjectPolicy &obj_policy=ObjectPolicy::CACHE_DEFAULTS, const PutOptions &options=PutOptions::CACHE_DEFAULTS) |
Inserts an object into the named cache and locks it, returning a PutResult that contains a LockTicket. More... | |
PutResult | update (SossKey key, const boost::shared_ptr< T > obj_ptr, const PutOptions &options=PutOptions::CACHE_DEFAULTS) |
Updates an existing object in the named cache. More... | |
PutResult | update_locked_and_retain (SossKey key, const boost::shared_ptr< T > obj_ptr, LockTicket lock_ticket, const PutOptions &options=PutOptions::CACHE_DEFAULTS) |
Updates an existing object in the named cache that is already locked by the caller, retaining the lock for subsequent locking operations. More... | |
PutResult | update_locked_and_release (SossKey key, const boost::shared_ptr< T > obj_ptr, LockTicket lock_ticket, const PutOptions &options=PutOptions::CACHE_DEFAULTS) |
Updates an existing object in the named cache that is already locked by the caller and releases the lock on the object. More... | |
PutResult | update_optimistic (SossKey key, const boost::shared_ptr< T > obj_ptr, int32_t version, const PutOptions &options=PutOptions::CACHE_DEFAULTS) |
Updates an existing object in the named cache and performs a version check to verify that the object being updated has not been changed since it was retrieved by the caller. More... | |
GetResult< T > | get (SossKey key, const GetOptions< T > &options=GetOptions< T >::CACHE_DEFAULTS) |
Retrieves an existing object from the named cache. More... | |
GetResult< T > | get_and_lock (SossKey key, const GetOptions< T > &options=GetOptions< T >::CACHE_DEFAULTS) |
Retrieves and acquires an exclusive lock on an existing object in the named cache. More... | |
GetResult< T > | get_locked (SossKey key, LockTicket lock_ticket, const GetOptions< T > &options=GetOptions< T >::CACHE_DEFAULTS) |
Retrieves an existing object in the named cache that is already locked by the caller, retaining the lock for subsequent locking operations. More... | |
void | set_missed_object_callback (boost::function< boost::shared_ptr< T >(const SossKey &key)> callback) |
Sets the method that is called by this named when a requested object is not in the cache, allowing an object to be transparently inserted into the cache. More... | |
boost::function < boost::shared_ptr< T >const SossKey &key)> | missed_object_callback () const |
Gets the method that is called by this named cache when a requested object is not in the cache. | |
RemoveResult | remove (SossKey key, bool object_may_not_exist=true, bool throw_on_error=true) |
Removes an object from the named cache. More... | |
RemoveResult | remove_locked (SossKey key, LockTicket lock_ticket, bool object_may_not_exist=true, bool throw_on_error=true) |
Removes a locked object from the named cache. More... | |
LockResult | lock (SossKey key, const LockOptions &options=LockOptions::CACHE_DEFAULTS) |
Acquires an exclusive lock on an object in the named cache. More... | |
LockResult | lock_refresh (SossKey key, LockTicket lock_ticket, bool throw_on_error=true) |
Refreshes a lock that is already held by the caller on an existing object in the named cache. More... | |
LockResult | unlock (SossKey key, LockTicket lock_ticket, bool throw_on_error=true) |
Unlocks an object in the named cache. More... | |
int32_t | clear (bool throw_on_error=true) |
Removes all objects from the named cache. More... | |
GetMetadataResult | get_metadata (SossKey key, const GetMetadataOptions &options=GetMetadataOptions::CACHE_DEFAULTS) |
Retrieves an existing object's metadata from the named cache. More... | |
const std::wstring & | get_key_string (SossKey &key, bool force_refresh=false) const |
Gets a copy of the original string key that was used to construct this SossKey (if any). More... | |
int64_t | query_obj_count (bool throw_on_error=true) |
Retrieves a count of objects in the named cache. More... | |
boost::shared_ptr< QueryResult > | query (const Filter &filter, bool throw_on_error=true) |
Queries the named cache for objects whose indexed properties match the specified filter expression, returning a collection of keys to objects that satisfy the filter. More... | |
boost::shared_ptr < PmicliInvokeResult > | pmicli_invoke (const Filter &filter, int eval_id, int merge_id, const std::vector< uint8_t > ¶m, const PmicliInvokeOptions &options=PmicliInvokeOptions::CACHE_DEFAULTS) |
Starts an invocation on the named cache for objects whose indexed properties match the specified filter expression, returning the invocation result in a serialized format. More... | |
uint32_t | app_id () const |
Gets the StateServer application ID associated with this named cache. More... | |
std::string | name () const |
Gets the name associated with this named cache, or an empty string if a name is not available. More... | |
DefaultCachePolicy & | default_cache_policy () |
Returns a reference to the DefaultCachePolicy associated with this named cache, which contains object policies that are to be used when policies are not explicitly provided to individual named cache operations. More... | |
void | set_default_cache_policy (DefaultCachePolicy default_cache_policy) |
Sets a new DefaultCachePolicy for this named cache. | |
Static Public Member Functions | |
static internal::ClientCache & | client_cache () |
Returns a reference to the ClientCache. The client cache is shared across all NamedCache instances. | |
Static Public Attributes | |
static const size_t | MAX_CACHE_NAME_LENGTH = SOSSLIB_DEF_MAX_APPNM_LEN |
Maximum number of characters allowed in a cache name (currently 280). | |
Protected Member Functions | |
virtual boost::shared_ptr< T > | deserialize (const std::vector< uint8_t > &bytes)=0 |
A virtual method that derived classes must override as a callback to perform deserialization of raw object data that is returned from StateServer service. More... | |
virtual void | serialize (const T &object, std::vector< uint8_t > &bytes_out, std::vector< uint8_t > &prop_spec_out)=0 |
A virtual method that derived classes must override as a callback to perform serialization of objects to raw byte vectors prior to sending the data to the StateServer service. More... | |
void | init (const uint32_t app_id) |
Protected intialization routing for NamedCache subclasses, associating the collection with the provided application identifier. More... | |
void | init (const std::string &name) |
Protected intialization routing for NamedCache subclasses, associating the collection with the provided string identifier. More... | |
virtual void | serialize_filter (const Filter &filter, std::vector< uint8_t > &bytes_out, size_t bytes_to_reserve_for_header) |
Converts a query filter to a serialized blob. Intended to be overridden in concrete subclasses. | |
Static Protected Attributes | |
static internal::ClientCache | client_cache_ |
Client side cache providing a near cache for SOSS objects to reduce the number of round trips to the server cluster. | |
static boost::mutex | init_mutex_ |
Mutex which controls one-time initialization of client cache. | |
static bool | is_init_ |
Flag which marks one-time initialization of client cache as complete. | |
The abstract TypedNamedCache template provides access to a strongly-typed named collection of objects that can be shared across multiple clients.
T | Type to be stored in the named cache. |
|
inlineinherited |
Gets the StateServer application ID associated with this named cache.
|
inherited |
Removes all objects from the named cache.
This method bypasses all locks held on objects. Expiration events are not fired for cleared objects.
throw_on_error | Determines whether the method will throw an exception derived from sosscli::exceptions::StateServerException if the ScaleOut StateServer service returns an error. If false, the error code will be returned by the method. |
|
inlineinherited |
Returns a reference to the DefaultCachePolicy associated with this named cache, which contains object policies that are to be used when policies are not explicitly provided to individual named cache operations.
|
protectedpure virtual |
A virtual method that derived classes must override as a callback to perform deserialization of raw object data that is returned from StateServer service.
This virtual method is called during get operations when an requested object is not in the local client cache and must be retrieved from the service and deserialized.
bytes | Reference to a byte vector containing the serialized bytes returned from the ScaleOut service. |
Implemented in sosscli::NamedProtobufCache< T >, and sosscli::NamedPrimitiveCache< T >.
GetResult<T> sosscli::TypedNamedCache< T >::get | ( | SossKey | key, |
const GetOptions< T > & | options = GetOptions< T >::CACHE_DEFAULTS |
||
) |
Retrieves an existing object from the named cache.
This operation does not use locking and will not block if another client/thread holds an exclusive lock on the object–use TypedNamedCache::get_and_lock or TypedNamedCache::get_locked to perform a synchronized get operation.
key | The SossKey of the object to be retrieved. |
options | A GetOptions object containing additional options for the get operation, or pass GetOptions<T>::CACHE_DEFAULTS to use this named cache's default behavior. |
GetResult<T> sosscli::TypedNamedCache< T >::get_and_lock | ( | SossKey | key, |
const GetOptions< T > & | options = GetOptions< T >::CACHE_DEFAULTS |
||
) |
Retrieves and acquires an exclusive lock on an existing object in the named cache.
The call will block until the exclusive lock can be acquired. If the lock is held by another client thread then the get_and_lock method will poll the StateServer service every 5 milliseconds to retry lock acquisition, for up to 20000 retries. If the lock cannot be acquired after the retries have been exhausted then a sosscli::exceptions::ObjectLockedException will be thrown (or a negative GetResult::return_code of -112 will be returned to indicate the failure if the throw_on_error argument is false). The frequecy and number of retries can be adjusted for the named cache via the DefaultCachePolicy or for individual get_and_lock calls via the GetOptions class (see GetOptions::set_max_lock_retry_count and GetOptions::set_lock_retry_interval_ms).
If no subsequent call is made to unlock the object or to refresh the owner's lock then the lock will automatically expire after approximately 90 seconds. The StateServer's 90 second lock timeout can be reset through a call to NamedCache::lock_refresh, TypedNamedCache::get_locked, or TypedNamedCache::update_locked_and_retain.
key | The SossKey of the object to be retrieved. |
options | A GetOptions object containing additional options for the get operation, or pass GetOptions<T>::CACHE_DEFAULTS to use this named cache's default behavior. |
|
inherited |
Gets a copy of the original string key that was used to construct this SossKey (if any).
If a retrieval from the server is performed, the original string will be cached in this instance for future use.
key | The SossKey of the object to be retrieved. |
force_refresh | If true, forces a retrieval from the server instead of using the locally cached copy (if present). |
GetResult<T> sosscli::TypedNamedCache< T >::get_locked | ( | SossKey | key, |
LockTicket | lock_ticket, | ||
const GetOptions< T > & | options = GetOptions< T >::CACHE_DEFAULTS |
||
) |
Retrieves an existing object in the named cache that is already locked by the caller, retaining the lock for subsequent locking operations.
key | The SossKey of the object to be retrieved. |
lock_ticket | A valid LockTicket that was acquired from an earlier locking call. |
options | A GetOptions object containing additional options for the get operation, or pass GetOptions<T>::CACHE_DEFAULTS to use this named cache's default behavior. |
|
inherited |
Retrieves an existing object's metadata from the named cache.
This operation does not use locking and will not block if another client/thread holds an exclusive lock on the object–use TypedNamedCache::get_and_lock or TypedNamedCache::get_locked prior to NamedCache::get_metadata to perform a synchronized get operation.
key | The SossKey of the object to be retrieved. |
options | Pointer to a GetMetadataOptions instance containing additional options for the get operation, or NULL to use the named cache's default behavior. |
|
protectedinherited |
Protected intialization routing for NamedCache subclasses, associating the collection with the provided application identifier.
app_id | Integer identifier of the named cache. |
|
protectedinherited |
Protected intialization routing for NamedCache subclasses, associating the collection with the provided string identifier.
The name of the cache must be between 1 and MAX_CACHE_NAME_LENGTH characters in length (currently 280).
name | Name of the cache. |
PutResult sosscli::TypedNamedCache< T >::insert | ( | SossKey | key, |
const boost::shared_ptr< T > | obj_ptr, | ||
const ObjectPolicy & | obj_policy = ObjectPolicy::CACHE_DEFAULTS , |
||
const PutOptions & | options = PutOptions::CACHE_DEFAULTS |
||
) |
Inserts an object into the named cache.
key | The SossKey with which the provided object value is to be associated. |
obj_ptr | A Boost shared_ptr to the object to be stored in the named cache. |
obj_policy | The policy to be associated with the object in the data grid. Pass ObjectPolicy::CACHE_DEFAULTS to use the default policies associated with this named cache object (see NamedCache::default_cache_policy). |
options | A PutOptions object containing additional options for the put operation, or pass PutOptions::CACHE_DEFAULTS to use this named cache's default behavior. |
PutResult sosscli::TypedNamedCache< T >::insert_and_lock | ( | SossKey | key, |
const boost::shared_ptr< T > | obj_ptr, | ||
const ObjectPolicy & | obj_policy = ObjectPolicy::CACHE_DEFAULTS , |
||
const PutOptions & | options = PutOptions::CACHE_DEFAULTS |
||
) |
Inserts an object into the named cache and locks it, returning a PutResult that contains a LockTicket.
key | The SossKey with which the provided object value is to be associated. |
obj_ptr | A Boost shared_ptr to the object to be stored in the named cache. |
obj_policy | The policy to be associated with the object in the data grid. Pass ObjectPolicy::CACHE_DEFAULTS to use the default policies associated with this named cache object (see NamedCache::default_cache_policy). |
options | A PutOptions object containing additional options for the put operation, or pass PutOptions::CACHE_DEFAULTS to use this named cache's default behavior. |
|
inherited |
Acquires an exclusive lock on an object in the named cache.
The call will block until the exclusive lock can be acquired. If the lock is held by another client thread then the lock method will poll the StateServer service every 5 milliseconds to retry lock acquisition, for up to 20000 retries. If the lock cannot be acquired after the retries have been exhausted then a sosscli::exceptions::ObjectLockedException will be thrown (or a negative GetResult::return_code of -112 will be returned to indicate the failure if the throw_on_error argument is false). The frequecy and number of retries can be adjusted for the named cache via the DefaultCachePolicy or for individual lock calls via the LockOptions class (see LockOptions::set_max_lock_retry_count and LockOptions::set_lock_retry_interval_ms).
If no subsequent call is made to unlock the object or to refresh the owner's lock then the lock will automatically expire after approximately 90 seconds. The StateServer's 90 second lock timeout can be reset through a call to NamedCache::lock_refresh, TypedNamedCache::get_locked, or TypedNamedCache::update_locked_and_retain.
key | The SossKey of the object to be locked. |
options | A LockOptions object containing additional options for the lock operation, or pass LockOptions::CACHE_DEFAULTS to use this named cache's default behavior. |
|
inherited |
Refreshes a lock that is already held by the caller on an existing object in the named cache.
Locks on objects in the StateServer will automatically expire after approximately 90 seconds if no subsequent locking operation is performed. This method can be used to reset the 90 second lock timeout.
key | The SossKey of the object. |
lock_ticket | A valid LockTicket that was acquired from an earlier locking call. |
throw_on_error | Determines whether the method will throw an exception derived from sosscli::exceptions::StateServerException if the ScaleOut StateServer service returns an error. If false, error code information will be available in the returned RemoveResult. |
|
inlineinherited |
Gets the name associated with this named cache, or an empty string if a name is not available.
|
inherited |
Starts an invocation on the named cache for objects whose indexed properties match the specified filter expression, returning the invocation result in a serialized format.
filter | A filter expression indicating which objects should be selected for invocation. |
eval_id | ID of the user code eval() function registered by Sosspmi_worker_register_eval_func(). |
merge_id | ID of the user code eval() function registered by Sosspmi_worker_register_eval_func(). |
param | A vector containing the serialized parameters object used during invocation. |
options | A PmicliInvokeOptions object containing additional options for the invoke operation, or pass PmicliInvokeOptions::CACHE_DEFAULTS to use this named cache's default behavior. |
PutResult sosscli::TypedNamedCache< T >::put | ( | SossKey | key, |
const boost::shared_ptr< T > | obj_ptr, | ||
const ObjectPolicy & | obj_policy = ObjectPolicy::CACHE_DEFAULTS , |
||
const PutOptions & | options = PutOptions::CACHE_DEFAULTS |
||
) |
Inserts or updates an object in the named cache.
This operation does not use locking and will bypass locks on objects held by other clients/threads.
key | The SossKey with which the provided object value is to be associated. |
obj_ptr | A Boost shared_ptr to the object to be stored in the named cache. |
obj_policy | The policy to be associated with the object in the data grid if the put operation results in the insertion of a new object into the named cache. Pass ObjectPolicy::CACHE_DEFAULTS to use the default policies associated with this named cache object (see NamedCache::default_cache_policy). Policies for existing objects will not be changed if a put operation results in an update (with the exception of an object's timeout, which will be changed if a sliding timeout is used). |
options | A PutOptions object containing additional options for the put operation, or pass PutOptions::CACHE_DEFAULTS to use this named cache's default behavior. |
|
inherited |
Queries the named cache for objects whose indexed properties match the specified filter expression, returning a collection of keys to objects that satisfy the filter.
filter | A filter expression indicating which objects should be returned from the query. |
throw_on_error | Determines whether the method will throw an exception derived from sosscli::exceptions::StateServerException if the ScaleOut StateServer service returns an error. If false, the error code will be returned by the method. |
|
inherited |
Retrieves a count of objects in the named cache.
This method will cause a round trip to the ScaleOut service and invoke a parallel query on the distributed cache, which involves all hosts in the store. Client applications should not use this property frequently or for trivial purposes.
throw_on_error | Determines whether the method will throw an exception derived from sosscli::exceptions::StateServerException if the ScaleOut StateServer service returns an error. If false, the error code will be returned by the method. |
|
inherited |
Removes an object from the named cache.
This operation does not use locking and will bypass locks on objects held by other clients/threads–use NamedCache::remove_locked to perform a synchronized remove operation.
key | The SossKey of the object to be removed. |
object_may_not_exist | Indicates whether performing a remove operation on a non-existent object should be considered an error. |
throw_on_error | Determines whether the method will throw an exception derived from sosscli::exceptions::StateServerException if the ScaleOut StateServer service returns an error. If false, error code information will be available in the returned RemoveResult. |
|
inherited |
Removes a locked object from the named cache.
key | The SossKey of the object to be removed. |
lock_ticket | A valid LockTicket that was acquired from an earlier locking call. |
object_may_not_exist | Indicates whether performing a remove operation on a non-existent object should be considered an error. |
throw_on_error | Determines whether the method will throw an exception derived from sosscli::exceptions::StateServerException if the ScaleOut StateServer service returns an error. If false, error code information will be available in the returned RemoveResult. |
|
protectedpure virtual |
A virtual method that derived classes must override as a callback to perform serialization of objects to raw byte vectors prior to sending the data to the StateServer service.
object | Reference to the object that must be serialized. | |
[out] | bytes_out | An empty vector of bytes that will receive the serialized object. |
[out] | prop_spec_out | An empty vector of bytes that will receive structured property information used by the ScaleOut StateServer service to index properties of the object being serialized. Leave empty if no indexing is needed. |
Implemented in sosscli::NamedProtobufCache< T >, and sosscli::NamedPrimitiveCache< T >.
|
inline |
Sets the method that is called by this named when a requested object is not in the cache, allowing an object to be transparently inserted into the cache.
The assigned method must return the object that is to be added to the cache.
If setting a callback for all get operations performed on this named cache instance is not desirable, the method used can be overridden for individual get operations by using the GetOptions.set_missed_object_callback() method, allowing you to assign a handler for an individual call.
If multiple clients and/or threads simultaneously attempt to read the missing object, only one thread in one client will be permitted to execute the callback method so as to prevent multiple clients/thread from simultaneously inserting the object into the cache–this behavior is valuable when creating the cached object involves expensive calls to a database or when it is otherwise undesirable for an object to be repeatedly created in the cache. Other clients/threads that try to retrieve the object while the callback is executing will be blocked while the object is being created, and, once the object has been added to the cache, those other threads will be unblocked and the newly-cached object will be returned to all of them.
callback | A function that returns a shared pointer to an object of type T. The method is called when there is a cache miss, and the returned object will be inserted into the cache. |
|
inherited |
Unlocks an object in the named cache.
key | The SossKey of the object. |
lock_ticket | A valid LockTicket that was acquired from an earlier locking call. |
throw_on_error | Determines whether the method will throw an exception derived from sosscli::exceptions::StateServerException if the ScaleOut StateServer service returns an error. If false, error code information will be available in the returned RemoveResult. |
PutResult sosscli::TypedNamedCache< T >::update | ( | SossKey | key, |
const boost::shared_ptr< T > | obj_ptr, | ||
const PutOptions & | options = PutOptions::CACHE_DEFAULTS |
||
) |
Updates an existing object in the named cache.
This operation does not use locking and will bypass locks on objects held by other clients/threads–use TypedNamedCache::update_locked_and_release, TypedNamedCache::update_locked_and_retain, or TypedNamedCache::update_optimistic to perform a synchronized update operation.
key | The SossKey with which the provided object value is to be associated. |
obj_ptr | A Boost shared_ptr to the object to be stored in the named cache. |
options | A PutOptions object containing additional options for the put operation, or pass PutOptions::CACHE_DEFAULTS to use this named cache's default behavior. |
PutResult sosscli::TypedNamedCache< T >::update_locked_and_release | ( | SossKey | key, |
const boost::shared_ptr< T > | obj_ptr, | ||
LockTicket | lock_ticket, | ||
const PutOptions & | options = PutOptions::CACHE_DEFAULTS |
||
) |
Updates an existing object in the named cache that is already locked by the caller and releases the lock on the object.
key | The SossKey with which the provided object value is to be associated. |
obj_ptr | A Boost shared_ptr to the object to be stored in the named cache. |
lock_ticket | A valid LockTicket that was acquired from an earlier locking call. |
options | A PutOptions object containing additional options for the put operation, or pass PutOptions::CACHE_DEFAULTS to use this named cache's default behavior. |
PutResult sosscli::TypedNamedCache< T >::update_locked_and_retain | ( | SossKey | key, |
const boost::shared_ptr< T > | obj_ptr, | ||
LockTicket | lock_ticket, | ||
const PutOptions & | options = PutOptions::CACHE_DEFAULTS |
||
) |
Updates an existing object in the named cache that is already locked by the caller, retaining the lock for subsequent locking operations.
key | The SossKey with which the provided object value is to be associated. |
obj_ptr | A Boost shared_ptr to the object to be stored in the named cache. |
lock_ticket | A valid LockTicket that was acquired from an earlier locking call. |
options | A PutOptions object containing additional options for the put operation, or pass PutOptions::CACHE_DEFAULTS to use this named cache's default behavior. |
PutResult sosscli::TypedNamedCache< T >::update_optimistic | ( | SossKey | key, |
const boost::shared_ptr< T > | obj_ptr, | ||
int32_t | version, | ||
const PutOptions & | options = PutOptions::CACHE_DEFAULTS |
||
) |
Updates an existing object in the named cache and performs a version check to verify that the object being updated has not been changed since it was retrieved by the caller.
Optimistic locking is a practical option when the chances of an update collision are low (for example, in applications that rarely perform updates in the distributed cache, or in applications that rarely update the same objects at the same time). Instead of preventing other clients from accessing the object, the optimistic strategy returns an error only if a collision is detected, allowing the client application to resolve the collision (typically by retrying the operation). If the odds of an update collision are too high then optimistic updates should be avoided, since resolving the collision could become expensive if done frequently.
ScaleOut StateServer supports optimistic locking by performing a version check when an object is updated in the named cache. If the version in the StateServer is newer than the instance being used in the update then a sosscli::exceptions::VersionMismatchException will be thrown (or a negative PutResult::return_code of -120 will be returned to indicate failure if the throw_on_error argument is false), indicating that another client/thread performed an update in the interval between the object's retrieval and the update.
If the odds of an update collision are high then consider using a pessimistic locking strategy instead: the NamedCache::lock, TypedNamedCache::insert_and_lock, and TypedNamedCache::get_and_lock methods can be used to acquire an exclusive lock on an object.
key | The SossKey with which the provided object value is to be associated. |
obj_ptr | A Boost shared_ptr to the object to be stored in the named cache. |
version | The version of the object that the caller currently has and intends to update. |
options | A PutOptions object containing additional options for the put operation, or pass PutOptions::CACHE_DEFAULTS to use this named cache's default behavior. |