The SossEvents class manages the registration and unregistration of handlers for asynchronous StateServer object events. More...

#include <soss_events.h>

Classes
class	EventDetails
	A class holding information about the StateServer event that is passed to registered callbacks. More...

Public Types
enum	EventCode { ObjectTimeout = SOSSLIB_EVT_TIMEOUT, LowMemory = SOSSLIB_EVT_LOW_MEM, Dependency = SOSSLIB_EVT_DEPEND, LoadFromBackingStore = SOSSLIB_EVT_LOAD, StoreInBackingStore = SOSSLIB_EVT_STORE, EraseFromBackingStore = SOSSLIB_EVT_ERASE }
	An enumeration containing the event codes provided to StateServer event callback handlers describing the event that StateServer is reporting. More...

enum	ObjectDisposition { Save = SOSSLIB_EVTRET_SAVE, Remove = SOSSLIB_EVTRET_REMOVE, NotHandled = SOSSLIB_EVTRET_NOT_HANDLED }
	An enumeration that communicates to StateServer the disposition of an object upon return from an event callback. More...

typedef boost::function < ObjectDisposition(EventDetails const &details)>	Callback
	A typedef describing a callback function for handling an asynchronous object events. More...

typedef uint32_t	CallbackHandle
	A typedef identifiying a registered Callback allowing a specific Callback's registration to be removed. More...

Static Public Member Functions
static CallbackHandle	register_callback (NamedCache const &cache, Callback const &callback)
	Register the given callback for StateServer events within cache's application ID. More...

static CallbackHandle	register_callback (uint32_t app_id, Callback const &callback)
	Register the given callback for the specified application ID. More...

static void	clear_callbacks (NamedCache const &cache)
	Clear all Callback registrations for the StateServer application ID equivalent to cache's application ID. More...

static void	clear_callbacks (uint32_t app_id)
	Clear all Callback registrations for the StateServer application ID app_id. More...

static void	erase_callback (NamedCache const &cache, CallbackHandle callback_handle)
	Remove a specific Callback registration for the StateServer application ID equivalent to cache's application ID. More...

static void	erase_callback (uint32_t app_id, CallbackHandle callback_handle)
	Remove a specific Callback registration for the StateServer application ID app_id. More...

Detailed Description

The SossEvents class manages the registration and unregistration of handlers for asynchronous StateServer object events.

Member Typedef Documentation

typedef boost::function<ObjectDisposition(EventDetails const & details)> sosscli::SossEvents::Callback

A typedef describing a callback function for handling an asynchronous object events.

One or more callback functions matching Callback may be registered on a given StateServer application namespace via the static register_callback() member functions. When a StateServer object event (e.g. object lifetime timeout has expired) occurs on an object in the specified NamedCache, callback functions will be called one at a time in the order they were registered until a callback indicates that it has "handled" the event by returning a result other than NotHandled.

Note that is some cases, the event handler could be signaled more than once (usually on different hosts). Therefore, the event handler's actions must be idempotent so that repeated execution is valid.

Parameters

details An EventDetails object providing the SossKey for the affected object and an EventCode describing the StateServer event.

Returns: An ObjectDisposition value indicating whether the object should be removed from the store or not. If multiple callbacks are defined and a callback returns NotHandled, the next callback in the callback list will be given the opportunity to handle the event. If no callback returns a value other than NotHandled, then the default action (normally to remove the object) is taken.

See Also: register_callback; clear_callbacks; erase_callback

typedef uint32_t sosscli::SossEvents::CallbackHandle

A typedef identifiying a registered Callback allowing a specific Callback's registration to be removed.

Since boost::function objects do not implement an == operator, we return CallbackHandle values as a way of identifying a specific Callback. If you subsequently want to remove a single Callback, you may pass this handle value to SossEvents::erase_callback.

See Also: erase_callback; clear_callbacks

Member Enumeration Documentation

enum sosscli::SossEvents::EventCode

An enumeration containing the event codes provided to StateServer event callback handlers describing the event that StateServer is reporting.

Enumerator
ObjectTimeout	An object's timeout expired.
LowMemory	A preemptable object was removed from memory due to a low memory condition.
Dependency	An object is being removed due to a dependency change.
LoadFromBackingStore	An object should be loaded from the backing store.
StoreInBackingStore	An object should be stored to the backing store.
EraseFromBackingStore	An object should be removed from the backing store.

enum sosscli::SossEvents::ObjectDisposition

An enumeration that communicates to StateServer the disposition of an object upon return from an event callback.

Enumerator

Save

The callback would like to keep the object in the store.

Remove

The callback would like the object removed from the store.

NotHandled

The callback has not handled the event; if there are additional callbacks they will be given the opportunity to handle the event.

If not, the default action (e.g. Remove) will be taken.

Member Function Documentation

static void sosscli::SossEvents::clear_callbacks ( NamedCache const & cache)

static

Clear all Callback registrations for the StateServer application ID equivalent to cache's application ID.

Note: This method is equivalent to
SossEvents::clear_callback(cache.app_id());

Parameters

cache A NamedCache instance that identifies the application ID of registrations to be cleared.

static void sosscli::SossEvents::clear_callbacks ( uint32_t app_id)

static

Clear all Callback registrations for the StateServer application ID app_id.

Parameters

app_id The StateServer application ID whose Callback registrations are to be cleared.

See Also: NamedCache::app_id()

static void sosscli::SossEvents::erase_callback	(	NamedCache const &	cache,
		CallbackHandle	callback_handle
	)

static

Remove a specific Callback registration for the StateServer application ID equivalent to cache's application ID.

Parameters

cache	A NamedCache instance that identifies the application ID of registrations to be cleared.
callback_handle	The CallbackHandle returned from SossEvents::register_callback when the Callback was registered.

static void sosscli::SossEvents::erase_callback	(	uint32_t	app_id,
		CallbackHandle	callback_handle
	)

static

Remove a specific Callback registration for the StateServer application ID app_id.

Parameters

app_id	The StateServer application ID
callback_handle	The CallbackHandle returned from SossEvents::register_callback when the Callback was registered.

static CallbackHandle sosscli::SossEvents::register_callback	(	NamedCache const &	cache,
		Callback const &	callback
	)

static

Register the given callback for StateServer events within cache's application ID.

Note: This method is equivalent to
SossEvents::register_callback(cache.app_id(), callback);

Parameters

cache	A NamedCache instance from which the StateServer application ID can be determined. Callback registrations are global to the StateServer application namespace represented in the NamedCache by its NamedCache::app_id(). Multiple registrations of a given Callback against the the same app_id result in duplicate registrations. Callback registrations are unrelated to NamedCache instance lifetimes.
callback	The callback to be registered. Callbacks are typically created using the boost::bind method and, therefore, can include extra (private) information for the callback such as a TypedNamedCache object to use if access to the affected object is required.

Returns: A CallbackHandle for this registration that can be used with the SossEvents::erase_callback methods.

static CallbackHandle sosscli::SossEvents::register_callback	(	uint32_t	app_id,
		Callback const &	callback
	)

static

Register the given callback for the specified application ID.

Parameters

app_id	The StateServer application ID associated with the NamedCache for which this registration applies.
callback	The callback to be registered. Callbacks are typically created using the boost::bind method and, therefore, can include extra (private) information for the callback such as a TypedNamedCache object to use if access to the affected object is required.

Returns: A CallbackHandle for this registration that can be used with the SossEvents::erase_callback methods.

See Also: NamedCache::app_id()

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

include/soss_client/soss_events.h

Classes

Public Types

Static Public Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Member Function Documentation