A concrete TypedNamedCache<T> implementation that expects Google Protocol Buffers Message instances as the objects stored in the StateServer cache. More...

#include <named_protobuf_cache.h>

Inheritance diagram for sosscli::NamedProtobufCache< T >:

Public Member Functions
	NamedProtobufCache (const std::string &name)
	Constructor. More...

	NamedProtobufCache (const uint32_t app_id)
	Constructor. More...

virtual	~NamedProtobufCache ()
	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 > &param, 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)
	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 (T const &message, std::vector< uint8_t > &bytes_out, std::vector< uint8_t > &prop_spec_out)
	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...

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.

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...

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.

Detailed Description

template<typename T>
class sosscli::NamedProtobufCache< T >

A concrete TypedNamedCache<T> implementation that expects Google Protocol Buffers Message instances as the objects stored in the StateServer cache.

Constructor & Destructor Documentation

template<typename T >

sosscli::NamedProtobufCache< T >::NamedProtobufCache ( const std::string & name)

inline

Constructor.

Associates 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).

Parameters

name	Name of the cache.

template<typename T >

sosscli::NamedProtobufCache< T >::NamedProtobufCache ( const uint32_t app_id)

inline

Constructor.

Associates the collection with the provided application identifier.

Parameters

app_id Integer identifier of the named cache.

Member Function Documentation

uint32_t sosscli::NamedCache::app_id ( ) const

inlineinherited

Gets the StateServer application ID associated with this named cache.

Returns: Integer identifier of the named cache.

int32_t sosscli::NamedCache::clear ( bool throw_on_error = true)

inherited

Removes all objects from the named cache.

This method bypasses all locks held on objects. Expiration events are not fired for cleared objects.

Parameters

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.

Returns: 1 if successful, or a negative error code if an error occurs and throw_on_error is false.

DefaultCachePolicy& sosscli::NamedCache::default_cache_policy ( )

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.

template<typename T >

virtual boost::shared_ptr<T> sosscli::NamedProtobufCache< T >::deserialize ( const std::vector< uint8_t > & bytes)

inlineprotectedvirtual

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.

Parameters

bytes Reference to a byte vector containing the serialized bytes returned from the ScaleOut service.

Returns: A shared pointer to the object that has been deserialized by this method.

Implements sosscli::TypedNamedCache< T >.

template<typename T >

GetResult<T> sosscli::TypedNamedCache< T >::get	(	SossKey	key,
		const GetOptions< T > &	options = `GetOptions< T >::CACHE_DEFAULTS`
	)

inherited

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.

Precondition: The object already exists in the named cache. If the object does not exist, a sosscli::exceptions::ObjectNotFoundException will be thrown (or a negative GetResult::return_code of -109 will be returned to indicate failure if throw_on_error is false).

Postcondition: If successful, the object is returned to the caller. There is no effect on locking: the object will be left in the same locked state that it was in prior to the retrieval.

Parameters

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.

Returns: A GetResult containing a shared pointer to the retrieved object and information about the outcome of the get operation.

template<typename T >

GetResult<T> sosscli::TypedNamedCache< T >::get_and_lock	(	SossKey	key,
		const GetOptions< T > &	options = `GetOptions< T >::CACHE_DEFAULTS`
	)

inherited

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.

Precondition: The object already exists in the named cache. If the object does not exist, a sosscli::exceptions::ObjectNotFoundException will be thrown (or a negative GetResult::return_code of -109 will be returned to indicate failure if throw_on_error is false).

Postcondition: If successful, the object is returned to the caller and is locked in the server on the caller's behalf. Use the returned GetResult::lock_ticket for subsequent locking operations against the object.

Parameters

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.

Returns: A GetResult containing a shared pointer to the retrieved object and a LockTicket that can be used for subsequent locking operations against the retrieved object.

const std::wstring& sosscli::NamedCache::get_key_string	(	SossKey &	key,
		bool	force_refresh = `false`
	)		const

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.

Parameters

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).

Returns: The original string key, or an empty string if this SossKey was not created using a string type.

template<typename T >

GetResult<T> sosscli::TypedNamedCache< T >::get_locked	(	SossKey	key,
		LockTicket	lock_ticket,
		const GetOptions< T > &	options = `GetOptions< T >::CACHE_DEFAULTS`
	)

inherited

Retrieves an existing object in the named cache that is already locked by the caller, retaining the lock for subsequent locking operations.

Precondition: The object already exists in the named cache and is locked by the caller. If the object does not exist, a sosscli::exceptions::ObjectNotFoundException will be thrown (or a negative GetResult::return_code of -109 will be returned to indicate failure if throw_on_error is false), and if the object is not already locked by the caller then an sosscli::exceptions::ObjectLockedException is thrown (or -112 is returned).

Postcondition: If successful, the object is returned to the caller and remains locked in the server on the caller's behalf. Use the returned GetResult::lock_ticket for subsequent locking operations against the object.

Parameters

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.

Returns: A GetResult containing a shared pointer to the retrieved object and a LockTicket that can be used for subsequent locking operations against the retrieved object.

GetMetadataResult sosscli::NamedCache::get_metadata	(	SossKey	key,
		const GetMetadataOptions &	options = `GetMetadataOptions::CACHE_DEFAULTS`
	)

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.

Precondition: The object already exists in the named cache. If the object does not exist, a sosscli::exceptions::ObjectNotFoundException will be thrown (or a negative GetMetadataResult::return_code of -109 will be returned to indicate failure if throw_on_error is false).

Postcondition: If successful, the object's metadata is returned to the caller. There is no effect on locking: the object will be left in the same locked state that it was in prior to the retrieval.

Parameters

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.

Returns: A GetMetadataResult containing a shared pointer to the retrieved object's metadata and information about the outcome of the get operation.

void sosscli::NamedCache::init ( const uint32_t app_id)

protectedinherited

Protected intialization routing for NamedCache subclasses, associating the collection with the provided application identifier.

Parameters

app_id Integer identifier of the named cache.

void sosscli::NamedCache::init ( const std::string & name)

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).

Parameters

name	Name of the cache.

template<typename T >

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`
	)

inherited

Inserts an object into the named cache.

Precondition: The object does not already exist in the named cache. If the object already exists, a sosscli::exceptions::ObjectExistsException will be thrown (or a negative PutResult::return_code will be returned to indicate failure if throw_on_error is false).

Postcondition: If successful, the object is inserted into the named cache and left in an unlocked state.

Parameters

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.

Returns: A PutResult containing information about the outcome of the insert operation.

template<typename T >

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`
	)

inherited

Inserts an object into the named cache and locks it, returning a PutResult that contains a LockTicket.

Precondition: The object does not already exist in the named cache. If the object already exists, a sosscli::exceptions::ObjectExistsException will be thrown (or a negative PutResult::return_code of -108 will be returned to indicate failure if throw_on_error is false).

Postcondition: If successful, the object is inserted into the named cache and is locked on the caller's behalf. Use the returned PutResult::lock_ticket for subsequent locking operations against the object.

Parameters

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.

Returns: A PutResult containing information about the outcome of the insert operation and a LockTicket that can be used for subsequent locking operations against the inserted object.

LockResult sosscli::NamedCache::lock	(	SossKey	key,
		const LockOptions &	options = `LockOptions::CACHE_DEFAULTS`
	)

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.

Precondition: The object already exists in the named cache. If the object does not exist, a sosscli::exceptions::ObjectNotFoundException will be thrown (or a negative LockResult::return_code of -109 will be returned to indicate failure if throw_on_error is false).

Postcondition: If successful, the object is locked in the server on the caller's behalf. Use the returned LockResult::lock_ticket for subsequent locking operations against the object.

Parameters

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.

Returns: A LockResult containing information about the outcome of the lock operation.

LockResult sosscli::NamedCache::lock_refresh	(	SossKey	key,
		LockTicket	lock_ticket,
		bool	throw_on_error = `true`
	)

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.

Precondition: The object already exists in the named cache and is locked by the caller. If the object does not exist, a sosscli::exceptions::ObjectNotFoundException can be thrown (or a negative LockResult::return_code of -109 will be returned to indicate failure if throw_on_error is false), and if the object is not already locked by the caller then an sosscli::exceptions::ObjectLockedException is thrown (or -112 is returned).

Postcondition: If successful, the lock on the object is refreshed.

Parameters

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.

Returns: A LockResult containing information about the outcome of the lock operation.

std::string sosscli::NamedCache::name ( ) const

inlineinherited

Gets the name associated with this named cache, or an empty string if a name is not available.

Returns: Copy of the string identifier of the named cache. If the named cache was constructed with a numeric application ID instead of a string then an empty string will be returned.

boost::shared_ptr<PmicliInvokeResult> sosscli::NamedCache::pmicli_invoke	(	const Filter &	filter,
		int	eval_id,
		int	merge_id,
		const std::vector< uint8_t > &	param,
		const PmicliInvokeOptions &	options = `PmicliInvokeOptions::CACHE_DEFAULTS`
	)

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.

Parameters

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.

Returns: A boost::shared_ptr to an PmicliInvokeResult, which contains the result object and exception details (if any).

template<typename T >

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`
	)

inherited

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.

Precondition: None.

Postcondition: No effect on locking: If the put results in the object being created, it will be in an unlocked state in the server when the operation completes. If the put results in an update, the object will be left in the same locked state that it was in prior to the put.

Parameters

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.

Returns: A PutResult containing information about the outcome of the put operation.

boost::shared_ptr<QueryResult> sosscli::NamedCache::query	(	const Filter &	filter,
		bool	throw_on_error = `true`
	)

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.

Parameters

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.

Returns: A boost::shared_ptr to a QueryResult, which contains the result set of keys.

int64_t sosscli::NamedCache::query_obj_count ( bool throw_on_error = true)

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.

Parameters

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.

Returns: The number of objects in the named cache, or a negative error code if an error occurs and throw_on_error is false.

RemoveResult sosscli::NamedCache::remove	(	SossKey	key,
		bool	object_may_not_exist = `true`,
		bool	throw_on_error = `true`
	)

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.

Precondition: The object already exists in the named cache.

Postcondition: If successful, the object is removed from the named cache.

Parameters

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.

Returns: A RemoveResult containing information about the outcome of the remove operation.

RemoveResult sosscli::NamedCache::remove_locked	(	SossKey	key,
		LockTicket	lock_ticket,
		bool	object_may_not_exist = `true`,
		bool	throw_on_error = `true`
	)

inherited

Removes a locked object from the named cache.

Precondition: The object already exists in the named cache and is locked by the caller. If the object does not exist, a sosscli::exceptions::ObjectNotFoundException can be thrown (or a negative RemoveResult::return_code of -109 will be returned to indicate failure if throw_on_error is false), and if the object is not already locked by the caller then an sosscli::exceptions::ObjectLockedException is thrown (or -112 is returned).

Postcondition: If successful, the object is removed from the named cache.

Parameters

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.

Returns: A RemoveResult containing information about the outcome of the remove operation.

template<typename T >

virtual void sosscli::NamedProtobufCache< T >::serialize	(	T const &	object,
		std::vector< uint8_t > &	bytes_out,
		std::vector< uint8_t > &	prop_spec_out
	)

inlineprotectedvirtual

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.

Parameters

	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.

Implements sosscli::TypedNamedCache< T >.

template<typename T >

void sosscli::TypedNamedCache< T >::set_missed_object_callback ( boost::function< boost::shared_ptr< T >(const SossKey &key)> callback)

inlineinherited

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.

Parameters

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.

Returns: *this by reference to allow for chained setter method calls.

LockResult sosscli::NamedCache::unlock	(	SossKey	key,
		LockTicket	lock_ticket,
		bool	throw_on_error = `true`
	)

inherited

Unlocks an object in the named cache.

Precondition: The object already exists in the named cache and is locked by the caller. If the object does not exist, a sosscli::exceptions::ObjectNotFoundException can be thrown (or a negative LockResult::return_code of -109 will be returned to indicate failure if throw_on_error is false), and if the object is not already locked by the caller then an sosscli::exceptions::ObjectLockedException is thrown (or -112 is returned).

Postcondition: If successful, the lock on the object released.

Parameters

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.

Returns: A LockResult containing information about the outcome of the unlock operation.

template<typename T >

PutResult sosscli::TypedNamedCache< T >::update	(	SossKey	key,
		const boost::shared_ptr< T >	obj_ptr,
		const PutOptions &	options = `PutOptions::CACHE_DEFAULTS`
	)

inherited

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.

Precondition: The object already exists in the named cache. If the object does not exist, a sosscli::exceptions::ObjectNotFoundException will be thrown (or a negative PutResult::return_code of -109 will be returned to indicate failure if throw_on_error is false).

Postcondition: If successful, the object is updated in the named cache. There is no effect on locking: the object will be left in the same locked state that it was in prior to the update.

Parameters

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.

Returns: A PutResult containing information about the outcome of the update operation.

template<typename T >

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`
	)

inherited

Updates an existing object in the named cache that is already locked by the caller and releases the lock on the object.

Precondition: The object already exists in the named cache and is locked by the caller. If the object does not exist, a sosscli::exceptions::ObjectNotFoundException will be thrown (or a negative PutResult::return_code of -109 will be returned to indicate failure if throw_on_error is false), and if the object is not already locked by the caller then an sosscli::exceptions::ObjectLockedException is thrown (or -112 is returned).

Postcondition: If successful, the object is updated in the named cache and becomes unlocked.

Parameters

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.

Returns: A PutResult containing information about the outcome of the update operation.

template<typename T >

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`
	)

inherited

Updates an existing object in the named cache that is already locked by the caller, retaining the lock for subsequent locking operations.

Precondition: The object already exists in the named cache and is locked by the caller. If the object does not exist, a sosscli::exceptions::ObjectNotFoundException will be thrown (or a negative PutResult::return_code of -109 will be returned to indicate failure if throw_on_error is false), and if the object is not already locked by the caller then an sosscli::exceptions::ObjectLockedException is thrown (or -112 is returned).

Postcondition: If successful, the object is updated in the named cache and remains in a locked state. Use the returned PutResult::lock_ticket for subsequent locking operations against the object.

Parameters

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.

Returns: A PutResult containing information about the outcome of the update operation and a LockTicket that can be used for subsequent locking operations against the updated object.

template<typename T >

PutResult sosscli::TypedNamedCache< T >::update_optimistic	(	SossKey	key,
		const boost::shared_ptr< T >	obj_ptr,
		int32_t	version,
		const PutOptions &	options = `PutOptions::CACHE_DEFAULTS`
	)

inherited

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.

Optimistic Locking and the Client Cache: The named cache may return the same instance of an object to two different threads that retrieve the object from the distributed cache. This can occur because the SOSS C++ API maintains a near cache of recently-accessed objects in order to cut down on network and serialization overhead.

: This client-side caching can have repercussions for applications that use optimistic locking–one thread's changes to an object that was retrieved from the client cache will be visible to all other threads referencing that same client cache instance, even if the changes have not yet been pushed to the authoritative SOSS server. This can cause problems if an optimistic update fails because the copy of the object in the client cache will be out of sync with the authoritative version in the server–all threads in the client would continue to see the changed object, even after the update failure.

One of three approaches should be taken to avoid the risk of putting the client cache in a state that is inconsistent with the server:

Make changes to a deep copy of the object before changing its state and attempting an optimistic update.
Disable use of the client cache for the object in question (see GetOptions::set_use_client_cache and DefaultCachePolicy::set_use_client_cache).
If an OptimisticLockException is thrown from the Update operation, immediately re-retrieve the object from the SOSS server so as to re-synchronize the client cache with the latest version of the object.

Precondition: The object already exists in the named cache and its version information has been acquired by the caller during a previous call. An object's version is available from the results of cache operations–see PutResult::version and GetResult::version.

Postcondition: If successful, the object is updated in the named cache. Its version number is updated in the server and the new version info is returned to the caller.

Parameters

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.

Returns: A PutResult containing information about the outcome of the update operation and the object's latest version information.

See Also: GetResult::version; PutResult::version

The documentation for this class was generated from the following file:

include/soss_client/named_protobuf_cache.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Attributes

Detailed Description

template<typename T> class sosscli::NamedProtobufCache< T >

Constructor & Destructor Documentation

Member Function Documentation

template<typename T>
class sosscli::NamedProtobufCache< T >