Base class for named cache implementations. More...

#include <named_cache.h>

Inheritance diagram for sosscli::NamedCache:

Classes
class	DefaultCachePolicy
	The DefaultCachePolicy class provides defines default behaviors and policies for named cache operations. More...

Public Member Functions
virtual	~NamedCache ()
	Destructor.

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
	NamedCache ()
	Constructor. 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.

Detailed Description

Base class for named cache implementations.

Named caches provide access to a named collection of objects that can be shared across multiple clients.

Constructor & Destructor Documentation

sosscli::NamedCache::NamedCache ( )

inlineprotected

Constructor.

Currently protected to prevent instantiation of this base class (intent is for derived classes to implement public constructors that call one of init() routines below).

Member Function Documentation

uint32_t sosscli::NamedCache::app_id ( ) const

inline

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)

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

inline

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.

const std::wstring& sosscli::NamedCache::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).

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.

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

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)

protected

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)

protected

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.

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

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

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

inline

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

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

boost::shared_ptr<QueryResult> sosscli::NamedCache::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.

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)

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

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

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.

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

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.

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

include/soss_client/named_cache.h

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation