sosscli::GetOptions< T > Class Template Reference

The GetOptions class contains options that control locking and client cache behavior of get operations. More...

#include <get_options.h>

Public Member Functions
	GetOptions ()
	Default constructor. More...
	GetOptions (bool use_client_cache, bool throw_on_error, int32_t max_lock_retry_count, int32_t lock_retry_interval_ms)
	Constructor. More...
	GetOptions (const GetOptions &other)
	Copy constructor.
GetOptions &	operator= (const GetOptions &rhs)
	Assignment operator.
virtual	~GetOptions ()
	Destructor.
bool	use_client_cache () const
	Returns a boolean indicating whether the get operation will check for, and possibly return, an up-to-date instance of the object if it resides in the API's client cache. More...
GetOptions &	set_use_client_cache (bool use_client_cache)
	Sets whether the get operation should check for, and possibly return, an up-to-date instance of the object if it resides in the API's client cache. More...
bool	throw_on_error () const
	Returns a boolean indicating whether a method will throw an exception derived from sosscli::exceptions::StateServerException if the ScaleOut StateServer service returns an error. More...
GetOptions &	set_throw_on_error (bool throw_on_error)
	Sets whether a method will throw an exception derived from sosscli::exceptions::StateServerException if the ScaleOut StateServer service returns an error. More...
int32_t	max_lock_retry_count () const
	Gets the number of retries that a TypedNamedCache::get_and_lock call should perform when polling to acquire an exclusive lock on an object.
GetOptions &	set_max_lock_retry_count (int32_t max_lock_retry_count)
	Sets the number of retries that a TypedNamedCache::get_and_lock call should perform when polling to acquire an exclusive lock on an object. More...
int32_t	lock_retry_interval_ms () const
	Gets the amount of time (in milliseconds) between polling attempts to acquire an exclusive lock on a cached object.
GetOptions &	set_lock_retry_interval_ms (int32_t lock_retry_interval_ms)
	Sets the amount of time (in milliseconds) between polling attempts to acquire an exclusive lock on a cached object. More...
GetOptions &	set_missed_object_callback (boost::function< boost::shared_ptr< T >(const SossKey &key)> callback)
	Sets the method that is called by the API when the 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 callback that is used by the API when the requested object is not in the cache.
ObjectPolicy *	missing_object_policy () const
	Gets the cache policy object to be used when a get operation is configured to transparently insert a missing object into the named cache using the callback registered via using set_missed_object_callback. More...
GetOptions &	set_missing_object_policy (std::unique_ptr< ObjectPolicy > policy)
	Sets the cache policy object to be used when a get operation is configured to transparently insert a missing object into the named cache. More...

Static Public Attributes
static const GetOptions< T >	CACHE_DEFAULTS = GetOptions<T>()
	GetOptions constant that indicates that the object should be retrieved using the cache's default options. More...

Detailed Description

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

The GetOptions class contains options that control locking and client cache behavior of get operations.

Template Parameters

T	Type to be retrieved from the named cache.

Constructor & Destructor Documentation

template<typename T >

sosscli::GetOptions< T >::GetOptions ( )

inline

Default constructor.

Creates a GetOptions object that throws exceptions on error if the ScaleOut StateServer service returns an error, allows client cache usage, and performs up 20000 lock retries, 5 milliseconds apart.

template<typename T >

sosscli::GetOptions< T >::GetOptions ( bool  use_client_cache, bool  throw_on_error, int32_t  max_lock_retry_count, int32_t  lock_retry_interval_ms  )

inline

Constructor.

Parameters

use_client_cache	Whether the get operation will check for, and possibly return, an up-to-date instance of the object if it resides in the API's client cache.
throw_on_error	Determines whether a 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 GetResult.
max_lock_retry_count	Number of retries that the lock call should perform when polling to acquire an exclusive lock on an object.
lock_retry_interval_ms	Amount of time (in milliseconds) between polling attempts to acquire an exclusive lock on a cached object.

Member Function Documentation

template<typename T >

ObjectPolicy* sosscli::GetOptions< T >::missing_object_policy ( ) const

inline

Gets the cache policy object to be used when a get operation is configured to transparently insert a missing object into the named cache using the callback registered via using set_missed_object_callback.

template<typename T >

GetOptions& sosscli::GetOptions< T >::set_lock_retry_interval_ms ( int32_t  lock_retry_interval_ms)

inline

Sets the amount of time (in milliseconds) between polling attempts to acquire an exclusive lock on a cached object.

Parameters

lock_retry_interval_ms

Amount of time (in milliseconds) between polling attempts to acquire an exclusive lock on a cached object.

Returns

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

template<typename T >

GetOptions& sosscli::GetOptions< T >::set_max_lock_retry_count ( int32_t  max_lock_retry_count)

inline

Sets the number of retries that a TypedNamedCache::get_and_lock call should perform when polling to acquire an exclusive lock on an object.

Parameters

max_lock_retry_count

Number of retries that the lock call should perform when polling to acquire an exclusive lock on an object.

Returns

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

template<typename T >

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

inline

Sets the method that is called by the API when the 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.

This setter allows callers to control the callback behavior for individual get operations. If you would rather set this callback once for all get operations performed by a named cache instance then use the TypedNamedCache.set_missed_object_callback() method instead. Note that if a GetOptions with a callback is passed as an argument into a get call then it will override a default callback that is registered with the TypedNamedCache.

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.

template<typename T >

GetOptions& sosscli::GetOptions< T >::set_missing_object_policy ( std::unique_ptr< ObjectPolicy >  policy)

inline

Sets the cache policy object to be used when a get operation is configured to transparently insert a missing object into the named cache.

If null or unset, the NamedCache::default_cache_policy will be used for the object.

To minimize memory used by each GetOptions instance, the GetOptions class only stores a std::unique_ptr to an ObjectPolicy that has been allocated by the caller–use std::move to transfer ownership of an ObjectPolicy to a GetOptions object through this method's option parameter.

sosscli::GetOptions<MyClass> get_opt;

auto obj_pol_ptr = std::unique_ptr<sosscli::ObjectPolicy>(new sosscli::ObjectPolicy());
obj_pol_ptr->set_timeout(boost::posix_time::minutes(30));

// transfer ownership of the allocated policy to the GetOptions object:
get_opt.set_missing_object_policy(std::move(obj_pol_ptr));

template<typename T>

GetOptions& sosscli::GetOptions< T >::set_throw_on_error ( bool  throw_on_error)

inline

Sets whether a 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 GetResult.

Parameters

throw_on_error

Determines whether a 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 GetResult.

Returns

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

template<typename T>

GetOptions& sosscli::GetOptions< T >::set_use_client_cache ( bool  use_client_cache)

inline

Sets whether the get operation should check for, and possibly return, an up-to-date instance of the object if it resides in the API's client cache.

Parameters

use_client_cache

Whether the get operation will check for, and possibly return, an up-to-date instance of the object if it resides in the API's client cache.

Returns

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

template<typename T>

bool sosscli::GetOptions< T >::throw_on_error ( ) const

inline

Returns a boolean indicating whether a 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 GetResult.

template<typename T>

bool sosscli::GetOptions< T >::use_client_cache ( ) const

inline

Returns a boolean indicating whether the get operation will check for, and possibly return, an up-to-date instance of the object if it resides in the API's client cache.

Member Data Documentation

template<typename T>

const GetOptions< T > sosscli::GetOptions< T >::CACHE_DEFAULTS = GetOptions<T>()

static

GetOptions constant that indicates that the object should be retrieved using the cache's default options.

---

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

• include/soss_client/get_options.h