fatalmind::ResourcePoolEventObserver Class Reference

#include <ResourcePoolEventObserver.hh>

Inherited by fatalmind::ResourcePoolStreamLogger.

List of all members.

---

Detailed Description

A ResourcePool Event Observer is a class which get's notified about certain events which happen in the pool.

A classical implementation of an Event Observer is to implement a logging. On construction of a ResourcePool you can pass a custom derivation of the Event Observer and implement whatever functionality you need.

This interface was not designed to interfere with the pool itself, to control the error behaviour of the Pool use the ResourcePoolOptions. The default Observer impelmentation loggs to stderr if enabled. The default is to log NONE events, but the default can be controlled by the FATALMIND_DEFAULT_LOGEVENTS environment variable.

e.g. setting

FATALMIND_DEFAULT_LOGEVENTS = FAIL_RESOURCE | EXECUTE_FAIL | EXECUTE_NFE 

would log any of the named failure events.

Once you registered your custom implementation you must also call ResourcePool::setLogEvents() and supply the bitmask of events you want to get notifications for.

The instance you pass to the ResourcePool constructor is cloned, the clone is then kept with the ResourcePool. You may destroy the instance you passed to the constructor.

A very simple, yet useful implementation is the ResourcePoolStreamLogger which is also used in the select.cc example .

The following lists the Events available for all ResourcePool's, irregadless of their ResourceType:

• INCREMENT_POOL - Indicates that the pool is beeing incremented. That means that new Resources are constructed and put into the pool of available resources.
• DOWNSIZE_POOL - Indicates that the pool is being shruk. All currently unused resources will be closed.
• FAIL_RESOURCE - Indicates that a resource will be fail-closed. Somebody has returned a resource by passing it to ResourcePool::fail instead of ResourcePool::free.
• GET_RESOURCE_FAIL - Indicates that a call to ResourcePool::get failed (did not find a resource).
• EXECUTE_NFE - Indicates that a Command execution failed with a NoFailoverException.
• EXECUTE_FAIL - Indicates that a Command execution failed with an Exception which is not a NoFailoverException.

The following is not really an event, it's used to swtich the timestamp logged to sub-second resolution for logged events:

• TIME_HIRES - loggs timestamp with microsecond resolution, but has a little bit more overhead

Besides these fundamental events, the following shortcuts are defined:

• ALL - All Events (maximum logging), without TIME_HIRES
• NONE - No logging.
• FAIL - equals

  FAIL_RESOURCE | GET_RESOURCE_FAIL  | EXECUTE_NFE | EXECUTE_FAIL 

Each ResourceType may define more events, plese refer to the linked topics:

• fatalmind::SQL::SQLFactoryInterface for SQL

Public Types
typedef unsigned int	event_t
Public Member Functions
virtual void	event (event_t eventID, const std::string &resourceID=NoResourceID, const std::string &message="")
	The callback to notify an observer about an event.
bool	isEvent (event_t eventID)
const std::string &	getEventName (const event_t event) const
	Translates the numeric EventID to a string representation.
const event_t	getEvent (const std::string &value) const
	Translates the event name to the EventID.
const event_t	registerEvent (const std::string &value)
	Registers a new named event.
const event_t	getEventMask (const std::string &value) const
	Translates an EventID Mask expression into it's binary representation.
event_t	setLogEvents (event_t events)
void	setDefaultEventMask ()
	To be used after initialization, will fetch the default from the env.
gc_ptr< EventReader >	getReader (const event_t event, const std::string &r)
Static Public Attributes
static const std::string	NoResourceID = "N/A"
static struct fatalmind::ResourcePoolEventObserver::Events	Event
	Symbol names for the defined events.
Protected Member Functions
virtual Clone *	DoClone () const
Protected Attributes
event_t	logevents
Classes
struct	Events
	Symbol names for the defined events.

---

Member Function Documentation

void fatalmind::ResourcePoolEventObserver::event	(	event_t	eventID,
		const std::string &	resourceID = NoResourceID,
		const std::string &	message = ""
	)			[virtual]

The callback to notify an observer about an event.

This method is called by ResourcePool upon the defined events (if they are enabled, see ResourcePool::setLogEvents). The implementation can do whatever it likes, but must take into consideration that it is synchronously called and might therefore block ResourcePool's processing.

The call to this method is not protected by any means to avoid reentrant access. Multi-Thread applications MUST take there own measures to prevent uncoordinated data manipulation.

const ResourcePoolEventObserver::event_t fatalmind::ResourcePoolEventObserver::getEvent

(

const std::string &

value

)

const

Translates the event name to the EventID.

This method is inteded for seldom usage (since the implementation is ruther expansive). Use this method to to build the EventID mask which is set with ResourcePool::setLogEvents.

Returns:

The Mapped EventID, or Event.NONE if it could not be mapped.

const ResourcePoolEventObserver::event_t fatalmind::ResourcePoolEventObserver::registerEvent

(

const std::string &

value

)

Registers a new named event.

Intended to be used by library authors.

Returns:

The newly (automatically assigned) EventID or an existing EventID (if the name was already used) or Event.NONE if it was not possible to map that event.

const ResourcePoolEventObserver::event_t fatalmind::ResourcePoolEventObserver::getEventMask

(

const std::string &

value

)

const

Translates an EventID Mask expression into it's binary representation.

pool.setLogEvents(logger.getEventMask("INCREMENT_POOL | DOWNSIZE_POOL")); is equivalent (but much slower) then pool.setLogEvents(logger.Event.INCREMENT_POOL | logger.Event.DOWNSIZE_POOL));

void fatalmind::ResourcePoolEventObserver::setDefaultEventMask

(

)

To be used after initialization, will fetch the default from the env.

e.g. after you register new events, to refetch it from the env

---

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

• ResourcePoolEventObserver.hh
• ResourcePoolEventObserver.cc

---