Hooks Manager. More...

#include <hooks_manager.h>

Inheritance diagram for isc::hooks::HooksManager:

Static Public Member Functions
static void	callCallouts (int index, CalloutHandle &handle)
	Calls the callouts for a given hook. More...

static void	callCommandHandlers (const std::string &command_name, CalloutHandle &handle)
	Calls the callouts/command handlers for a given command name. More...

static bool	calloutsPresent (int index)
	Are callouts present? More...

static void	clearParkingLots ()
	Clears any parking packets. More...

static bool	commandHandlersPresent (const std::string &command_name)
	Checks if control command handlers are present for the specified command. More...

static boost::shared_ptr< CalloutHandle >	createCalloutHandle ()
	Return callout handle. More...

template<typename T >
static bool	drop (const std::string &hook_name, T parked_object)
	Removes parked object without calling a callback. More...

static HooksManager &	getHooksManager ()
	Get singleton hooks manager. More...

static HookLibsCollection	getLibraryInfo ()
	Return list of loaded libraries with its parameters. More...

static std::vector< std::string >	getLibraryNames ()
	Return list of loaded libraries. More...

static boost::shared_ptr< CalloutManager > &	getSharedCalloutManager ()
	Return the shared callout manager. More...

static bool	loadLibraries (const HookLibsCollection &libraries)
	Load and reload libraries. More...

template<typename T >
static void	park (const std::string &hook_name, T parked_object, std::function< void()> unpark_callback)
	Park an object (packet). More...

static LibraryHandle &	postCalloutsLibraryHandle ()
	Return post-callouts library handle. More...

static LibraryHandle &	preCalloutsLibraryHandle ()
	Return pre-callouts library handle. More...

template<typename T >
static void	reference (const std::string &hook_name, T parked_object)
	Increases reference counter for the parked object. More...

static int	registerHook (const std::string &name)
	Register Hook. More...

static void	unloadLibraries ()
	Unload libraries. More...

template<typename T >
static bool	unpark (const std::string &hook_name, T parked_object)
	Forces unparking the object (packet). More...

static std::vector< std::string >	validateLibraries (const std::vector< std::string > &libraries)
	Validate library list. More...

Static Public Attributes
static const int	CONTEXT_CREATE = ServerHooks::CONTEXT_CREATE
	Index numbers for pre-defined hooks. More...

static const int	CONTEXT_DESTROY = ServerHooks::CONTEXT_DESTROY

Detailed Description

Hooks Manager.

This is the overall manager of the hooks framework and is the main class used by a Kea module when handling hooks. It is responsible for the loading and unloading of user libraries, and for calling the callouts on each hook point.

The class is a singleton, the single instance of the object being accessed through the static getHooksManager() method.

Definition at line 38 of file hooks_manager.h.

Member Function Documentation

◆ callCallouts()

void isc::hooks::HooksManager::callCallouts	(	int	index,
		CalloutHandle &	handle
	)

static

Calls the callouts for a given hook.

Iterates through the library handles and calls the callouts associated with the given hook index.

Note: This method invalidates the current library index set with setLibraryIndex().

Parameters

index	Index of the hook to call.
handle	Reference to the CalloutHandle object for the current object being processed.

Definition at line 73 of file hooks_manager.cc.

◆ callCommandHandlers()

void isc::hooks::HooksManager::callCommandHandlers	(	const std::string &	command_name,
		CalloutHandle &	handle
	)

static

Calls the callouts/command handlers for a given command name.

Iterates through the library handles and calls the command handlers associated with the given command. It expects that the hook point for this command exists (with a name being a command_name prefixed with a dollar sign and with hyphens replaced with underscores).

Parameters

command_name	Command name for which handlers should be called.
handle	Reference to the CalloutHandle object for the current object being processed.

Exceptions

NoSuchHook if the hook point for the specified command does not exist.

Definition at line 85 of file hooks_manager.cc.

◆ calloutsPresent()

bool isc::hooks::HooksManager::calloutsPresent ( int index )

static

Are callouts present?

Checks loaded libraries and returns true if at lease one callout has been registered by them for the given hook.

Parameters

index Hooks index for which callouts are checked.

Returns: true if callouts are present, false if not.

Exceptions

NoSuchHook Given index does not correspond to a valid hook.

Definition at line 49 of file hooks_manager.cc.

◆ clearParkingLots()

static void isc::hooks::HooksManager::clearParkingLots ( )

inlinestatic

Clears any parking packets.

This method should be called during reconfiguration to ensure there are no dangling pointers that could possibly prevent the library from being unloaded.

Definition at line 318 of file hooks_manager.h.

References getHooksManager().

Here is the call graph for this function:

◆ commandHandlersPresent()

bool isc::hooks::HooksManager::commandHandlersPresent ( const std::string & command_name )

static

Checks if control command handlers are present for the specified command.

Parameters

command_name Command name for which handlers' presence should be checked.

Returns: true if there is a hook point associated with the specified command and callouts/command handlers are installed for this hook point, false otherwise.

Definition at line 60 of file hooks_manager.cc.

◆ createCalloutHandle()

boost::shared_ptr< CalloutHandle > isc::hooks::HooksManager::createCalloutHandle ( )

static

Return callout handle.

Returns a callout handle to be associated with a request passed round the system.

Note: This handle is valid only after a loadLibraries() call and then only up to the next loadLibraries() call.

Returns: Shared pointer to a CalloutHandle object.

Definition at line 150 of file hooks_manager.cc.

Referenced by isc::hooks::CalloutHandleAssociate::getCalloutHandle().

◆ drop()

template<typename T >

static bool isc::hooks::HooksManager::drop	(	const std::string &	hook_name,
		T	parked_object
	)

inlinestatic

Removes parked object without calling a callback.

Template Parameters

T	type of the parked object.

Parameters

hook_name	name of the hook point for which the packet is parked.
parked_object	parked object to be removed.

Returns: true if the specified object has been found false otherwise.

Definition at line 295 of file hooks_manager.h.

References getHooksManager().

Here is the call graph for this function:

◆ getHooksManager()

HooksManager & isc::hooks::HooksManager::getHooksManager ( )

static

Get singleton hooks manager.

Returns: Reference to the singleton hooks manager.

Definition at line 35 of file hooks_manager.cc.

Referenced by clearParkingLots(), drop(), park(), reference(), and unpark().

◆ getLibraryInfo()

HookLibsCollection isc::hooks::HooksManager::getLibraryInfo ( )

static

Return list of loaded libraries with its parameters.

Returns the names of the loaded libraries and their parameters.

Returns: List of loaded libraries (names + parameters)

Definition at line 174 of file hooks_manager.cc.

◆ getLibraryNames()

std::vector< std::string > isc::hooks::HooksManager::getLibraryNames ( )

static

Return list of loaded libraries.

Returns the names of the loaded libraries.

Returns: List of loaded library names.

Definition at line 169 of file hooks_manager.cc.

◆ getSharedCalloutManager()

boost::shared_ptr< CalloutManager > & isc::hooks::HooksManager::getSharedCalloutManager ( )

static

Return the shared callout manager.

Declared as static as other methods but only one for the singleton will be created.

Returns: A reference to the shared callout manager

Definition at line 232 of file hooks_manager.cc.

Referenced by isc::hooks::LibraryManagerCollection::loadLibraries().

◆ loadLibraries()

bool isc::hooks::HooksManager::loadLibraries ( const HookLibsCollection & libraries )

static

Load and reload libraries.

Loads the list of libraries into the server address space. For each library, the "standard" functions (ones with the same names as the hook points) are configured and the libraries' "load" function called.

If libraries are already loaded, they are unloaded and the new libraries loaded.

If any library fails to load, an error message will be logged. The remaining libraries will be loaded if possible.

Parameters

libraries List of libraries to be loaded. The order is important, as it determines the order that callouts on the same hook will be called.

Returns: true if all libraries loaded without a problem, false if one or more libraries failed to load. In the latter case, message will be logged that give the reason.

Definition at line 117 of file hooks_manager.cc.

◆ park()

template<typename T >

static void isc::hooks::HooksManager::park	(	const std::string &	hook_name,
		T	parked_object,
		std::function< void()>	unpark_callback
	)

inlinestatic

Park an object (packet).

The typical use case for parking an object is when the server needs to suspend processing of a packet to perform an asynchronous operation, before the response is sent to a client. In this case, the object type is a pointer to the processed packet. Therefore, further in this description we're going to refer to the parked objects as "parked packets". However, any other object can be parked if necessary.

The following is the typical flow when packets are parked. The callouts responsible for performing an asynchronous operation signal this need to the server by returning the status NEXT_STEP_PARK, which instructs the server to call this function. This function stops processing the packet and puts it in, so called, parking lot. In order to be able to resume the packet processing when instructed by the hooks library, the parked packet is associated with the callback which, when called, will resume packet processing.

The hook library must increase a reference count on the parked object by calling ParkingLotHandle::reference prior to returning the NEXT_STEP_PARK status. This is important when multiple callouts are installed on the same hook point and each of them schedules an asynchronous operation. In this case, the packet must not be unparked until all hook libraries call ParkingLotHandle::unpark to mark that respective asynchronous operations are completed.

Template Parameters

Type	of the parked object.

Parameters

hook_name	name of the hook point for which the packet is parked.
parked_object	packet to be parked.
unpark_callback	callback invoked when the packet is unparked.

Definition at line 268 of file hooks_manager.h.

References getHooksManager().

Here is the call graph for this function:

◆ postCalloutsLibraryHandle()

isc::hooks::LibraryHandle & isc::hooks::HooksManager::postCalloutsLibraryHandle ( )

static

Return post-callouts library handle.

Returns a library handle that can be used by the server to register callouts on a hook that are called _after any callouts belonging to a library.

Note: Both the reference returned and the callouts registered with this handle only remain valid until the next loadLibraries() or unloadLibraries() call. If the callouts are to remain registered after this time, a new handle will need to be obtained and the callouts re-registered.

Returns: Reference to library handle associated with post-library callout registration.

Definition at line 219 of file hooks_manager.cc.

◆ preCalloutsLibraryHandle()

isc::hooks::LibraryHandle & isc::hooks::HooksManager::preCalloutsLibraryHandle ( )

static

Return pre-callouts library handle.

Returns a library handle that can be used by the server to register callouts on a hook that are called before any callouts belonging to a library.

Note: Both the reference returned and the callouts registered with this handle only remain valid until the next loadLibraries() or unloadLibraries() call. If the callouts are to remain registered after this time, a new handle will need to be obtained and the callouts re-registered.

Returns: Reference to library handle associated with pre-library callout registration.

Definition at line 208 of file hooks_manager.cc.

◆ reference()

template<typename T >

static void isc::hooks::HooksManager::reference	(	const std::string &	hook_name,
		T	parked_object
	)

inlinestatic

Increases reference counter for the parked object.

Reference counter must be increased at least to 1 before the park() method can be called.

Template Parameters

Type	of the parked object.

Parameters

hook_name	name of the hook point for which the packet is parked.
parked_object	parked object for which reference counter should be increased.

Definition at line 309 of file hooks_manager.h.

References getHooksManager().

Here is the call graph for this function:

◆ registerHook()

int isc::hooks::HooksManager::registerHook ( const std::string & name )

static

Register Hook.

This is just a convenience shell around the ServerHooks::registerHook() method. It - along with the definitions of the two hook indexes for the context_create and context_destroy methods - means that server authors only need to deal with HooksManager and CalloutHandle, and not include any other hooks framework classes.

Parameters

name	Name of the hook

Returns: Index of the hook, to be used in subsequent hook-related calls. This will be greater than or equal to zero (so allowing a negative value to indicate an invalid index).

Exceptions

DuplicateHook A hook with the same name has already been registered.

Definition at line 195 of file hooks_manager.cc.

◆ unloadLibraries()

void isc::hooks::HooksManager::unloadLibraries ( )

static

Unload libraries.

Unloads the loaded libraries and leaves the hooks subsystem in the state it was after construction but before loadLibraries() is called.

Note: : This method should be used with caution - see the notes for the class LibraryManager for pitfalls. In general, a server should not call this method: library unloading will automatically take place when new libraries are loaded, and when appropriate objects are destroyed.

Returns: true if all libraries unloaded successfully, false on an error. In the latter case, an error message will have been output.

Definition at line 136 of file hooks_manager.cc.

◆ unpark()

template<typename T >

static bool isc::hooks::HooksManager::unpark	(	const std::string &	hook_name,
		T	parked_object
	)

inlinestatic

Forces unparking the object (packet).

This method unparks the object regardless of the reference counting value. This is used in the situations when the callouts fail to unpark the packet for some reason.

Template Parameters

T	type of the parked object.

Parameters

hook_name	name of the hook point for which the packet is parked.
parked_object	parked object to be unparked.

Returns: true if the specified object has been found, false otherwise.

Definition at line 284 of file hooks_manager.h.

References getHooksManager().

Here is the call graph for this function:

◆ validateLibraries()

std::vector< std::string > isc::hooks::HooksManager::validateLibraries ( const std::vector< std::string > & libraries )

static

Validate library list.

For each library passed to it, checks that the library can be opened and that the "version" function is present and gives the right answer. Each library is closed afterwards.

This is used during the configuration parsing - when the list of hooks libraries is changed, each of the new libraries is checked before the change is committed.

Parameters

libraries List of libraries to be validated.

Returns: An empty vector if all libraries validated. Otherwise it holds the names of the libraries that failed validation.

Definition at line 226 of file hooks_manager.cc.

Member Data Documentation

◆ CONTEXT_CREATE

const int isc::hooks::HooksManager::CONTEXT_CREATE = ServerHooks::CONTEXT_CREATE

static

Index numbers for pre-defined hooks.

Definition at line 226 of file hooks_manager.h.

◆ CONTEXT_DESTROY

const int isc::hooks::HooksManager::CONTEXT_DESTROY = ServerHooks::CONTEXT_DESTROY

static

Definition at line 227 of file hooks_manager.h.

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

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ callCallouts()

◆ callCommandHandlers()

◆ calloutsPresent()

◆ clearParkingLots()

◆ commandHandlersPresent()

◆ createCalloutHandle()

◆ drop()

◆ getHooksManager()

◆ getLibraryInfo()

◆ getLibraryNames()

◆ getSharedCalloutManager()

◆ loadLibraries()

◆ park()

◆ postCalloutsLibraryHandle()

◆ preCalloutsLibraryHandle()

◆ reference()

◆ registerHook()

◆ unloadLibraries()

◆ unpark()

◆ validateLibraries()

Member Data Documentation

◆ CONTEXT_CREATE

◆ CONTEXT_DESTROY