Callout Manager. More...

#include <callout_manager.h>

Public Member Functions
	CalloutManager (int num_libraries=0)
	Constructor.

void	callCallouts (int hook_index, CalloutHandle &callout_handle)
	Calls the callouts for a given hook.

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

bool	calloutsPresent (int hook_index) const
	Checks if callouts are present on a hook.

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

bool	deregisterAllCallouts (const std::string &name, int library_index)
	Removes all callouts on a hook for the current library.

bool	deregisterCallout (const std::string &name, CalloutPtr callout, int library_index)
	De-Register a callout on a hook for the current library.

size_t	getHookLibsVectorSize () const
	Return number of currently available hooks.

LibraryHandle &	getLibraryHandle ()
	Return library handle.

int	getLibraryIndex () const
	Get current library index.

int	getNumLibraries () const
	Get number of libraries.

LibraryHandle &	getPostLibraryHandle ()
	Return post-user callouts library handle.

LibraryHandle &	getPreLibraryHandle ()
	Return pre-user callouts library handle.

void	registerCallout (const std::string &name, CalloutPtr callout, int library_index)
	Register a callout on a hook for the current library.

void	registerCommandHook (const std::string &command_name)
	Registers a hook point for the specified command name.

void	setLibraryIndex (int library_index)
	Set current library index.

Detailed Description

Callout Manager.

This class manages the registration, deregistration and execution of the library callouts. It is part of the hooks framework used by the Kea server, and is not for use by user-written code in a hooks library.

In operation, the class needs to know two items of data:

The list of server hooks, which is used in two ways. Firstly, when a library registers or deregisters a hook, it does so by name: the isc::hooks::ServerHooks object supplies the names of registered hooks. Secondly, when the callouts associated with a hook are called by the server, the server supplies the index of the relevant hook: this is validated by reference to the list of hooks.
The number of loaded libraries. Each callout registered by a user library is associated with that library, the callout manager storing both a pointer to the callout and the index of the library in the list of loaded libraries. When calling a callout, the callout manager maintains the idea of a "current library index": this is used to access the context associated with the library.

These two items of data are supplied when an object of this class is constructed. The latter (number of libraries) can be updated after the class is constructed. (Such an update is used during library loading where the CalloutManager has to be constructed before the libraries are loaded, but one of the libraries subsequently fails to load.)

The library index is important because it determines in what order callouts on a particular hook are called. For each hook, the CalloutManager maintains a vector of callouts ordered by library index. When a callout is added to the list, it is added at the end of the callouts associated with the current library. To clarify this further, suppose that three libraries are loaded, A (assigned an index 1), B (assigned an index 2) and C (assigned an index 3). Suppose A registers two callouts on a given hook, A1 and A2 (in that order) B registers B1 and B2 (in that order) and C registers C1 and C2 (in that order). Internally, the callouts are stored in the order A1, A2, B1, B2, C1, and C2: this is also the order in which they are called.

Indexes range between 1 and n (where n is the number of the libraries loaded) and are assigned to libraries based on the order the libraries presented to the hooks framework for loading (something that occurs in the isc::hooks::HooksManager) class. However, two other indexes are recognized, 0 and INT_MAX. These are used when the server itself registers callouts - the server is able to register callouts that get called before any user-library callouts, and ones that get called after user-library callouts. In other words, assuming the callouts on a hook are A1, A2, B1, B2, B3, C2, C2 as before, and that the server registers S1 (to run before the user-registered callouts) and S2 (to run after them), the callouts are stored (and executed) in the order S1, A1, A2, B1, B2, B3, C2, C2, S2. In summary, the recognized index values are:

< 0: invalid.
0: used for server-registered callouts that are called before user-registered callouts.
1 - n: callouts from user libraries.
INT_MAX: used for server-registered callouts called after user-registered callouts.

Since Kea 1.3.0 release hook libraries can register callouts as control command handlers. Such handlers are associated with dynamically created hook points which names are created after command names. For example, if a command name is 'foo-bar', the name of the hook point to which callouts/command handlers are registered is '$foo_bar'. Prefixing the hook point name with the dollar sign eliminates potential conflicts between hook points dedicated to commands handling and other (fixed) hook points.

Prefixing hook names for command handlers with a dollar sign precludes auto registration of command handlers, i.e. hooks framework is unable to match hook points with names of functions implementing command handlers, because the dollar sign is not legal in C++ function names. This is intended because we want hook libraries to explicitly register commands handlers for supported commands and not rely on Kea to register hook points for them. Should we find use cases for auto registration of command handlers, we may modify the ServerHooks::commandToHookName to use an encoding of hook point names for command handlers that would only contain characters allowed in function names.

The CalloutManager::registerCommandHook has been added to allow for dynamically creating hook points for which command handlers are registered. This method is called from the LibraryHandle::registerCommandCallout as a result of registering the command handlers by the hook library in its load() function. If the hook point for the given command already exists, this function doesn't do anything. The LibraryHandle::registerCommandCallout can install callouts on this hook point.

Note that the callout functions do not access the CalloutManager: instead, they use a LibraryHandle object. This contains an internal pointer to the CalloutManager, but provides a restricted interface. In that way, callouts are unable to affect callouts supplied by other libraries.

Definition at line 128 of file callout_manager.h.

Constructor & Destructor Documentation

◆ CalloutManager()

isc::hooks::CalloutManager::CalloutManager ( int num_libraries = 0 )

Constructor.

Initializes member variables, in particular sizing the hook vector (the vector of callout vectors) to the appropriate size.

Parameters

num_libraries Number of loaded libraries.

Exceptions

isc::BadValue if the number of libraries is less than 0,

Definition at line 28 of file callout_manager.cc.

References isc_throw.

Member Function Documentation

◆ callCallouts()

void isc::hooks::CalloutManager::callCallouts	(	int	hook_index,
		CalloutHandle &	callout_handle )

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

hook_index	Index of the hook to call.
callout_handle	Reference to the CalloutHandle object for the current object being processed.

Definition at line 129 of file callout_manager.cc.

References isc::hooks::callouts_logger, calloutsPresent(), isc::hooks::PointerConverter::dlsymPtr(), isc::hooks::ServerHooks::getName(), isc::hooks::HOOKS_CALLOUT_CALLED, isc::hooks::HOOKS_CALLOUT_ERROR, isc::hooks::HOOKS_CALLOUT_EXCEPTION, isc::hooks::HOOKS_CALLOUTS_BEGIN, isc::hooks::HOOKS_CALLOUTS_COMPLETE, isc::hooks::HOOKS_DBG_CALLS, isc::hooks::HOOKS_DBG_EXTENDED_CALLS, LOG_DEBUG, LOG_ERROR, isc::hooks::CalloutHandle::NEXT_STEP_CONTINUE, and isc::hooks::CalloutHandle::NEXT_STEP_DROP.

Referenced by callCommandHandlers().

Here is the call graph for this function:

◆ callCommandHandlers()

void isc::hooks::CalloutManager::callCommandHandlers	(	const std::string &	command_name,
		CalloutHandle &	callout_handle )

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.
callout_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 219 of file callout_manager.cc.

References callCallouts(), isc::hooks::ServerHooks::commandToHookName(), and isc::hooks::ServerHooks::getServerHooks().

Here is the call graph for this function:

◆ calloutsPresent()

bool isc::hooks::CalloutManager::calloutsPresent ( int hook_index ) const

Checks if callouts are present on a hook.

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

Parameters

hook_index Hook 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 96 of file callout_manager.cc.

References isc_throw.

Referenced by callCallouts(), and commandHandlersPresent().

◆ commandHandlersPresent()

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

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 108 of file callout_manager.cc.

References calloutsPresent(), isc::hooks::ServerHooks::commandToHookName(), and isc::hooks::ServerHooks::getServerHooks().

Here is the call graph for this function:

◆ deregisterAllCallouts()

bool isc::hooks::CalloutManager::deregisterAllCallouts	(	const std::string &	name,
		int	library_index )

Removes all callouts on a hook for the current library.

Removes all callouts associated with a given hook that were registered by the current library.

Parameters

name	Name of the hook from which the callouts are removed.
library_index	Library index used for deregistering all callouts.

Returns: true if one or more callouts were deregistered.

Exceptions

NoSuchHook Thrown if the hook name is unrecognized.

Construct a CalloutEntry matching the current library (the callout pointer is NULL as we are not checking that).

To decide if any entries were removed, we'll record the initial size of the callout vector for the hook, and compare it with the size after the removal.

Definition at line 285 of file callout_manager.cc.

References isc::hooks::callouts_logger, isc::hooks::ServerHooks::getIndex(), isc::hooks::HOOKS_ALL_CALLOUTS_DEREGISTERED, isc::hooks::HOOKS_DBG_EXTENDED_CALLS, and LOG_DEBUG.

Referenced by isc::hooks::LibraryHandle::deregisterAllCallouts().

Here is the call graph for this function:

◆ deregisterCallout()

bool isc::hooks::CalloutManager::deregisterCallout	(	const std::string &	name,
		CalloutPtr	callout,
		int	library_index )

De-Register a callout on a hook for the current library.

Searches through the functions registered by the current library with the named hook and removes all entries matching the callout.

Parameters

name	Name of the hook from which the callout is removed.
callout	Pointer to the callout function to be removed.
library_index	Library index used for deregistering the callout.

Returns: true if a one or more callouts were deregistered.

Exceptions

NoSuchHook	The hook name is unrecognized.
Unexpected	The hook name is valid but an internal data structure is of the wrong size.

Construct a CalloutEntry matching the current library and the callout we want to remove.

To decide if any entries were removed, we'll record the initial size of the callout vector for the hook, and compare it with the size after the removal.

Definition at line 232 of file callout_manager.cc.

References isc::hooks::callouts_logger, isc::hooks::ServerHooks::getIndex(), isc::hooks::HOOKS_CALLOUT_DEREGISTERED, isc::hooks::HOOKS_DBG_EXTENDED_CALLS, and LOG_DEBUG.

Referenced by isc::hooks::LibraryHandle::deregisterCallout().

Here is the call graph for this function:

◆ getHookLibsVectorSize()

size_t isc::hooks::CalloutManager::getHookLibsVectorSize ( ) const

inline

Return number of currently available hooks.

Definition at line 361 of file callout_manager.h.

◆ getLibraryHandle()

LibraryHandle & isc::hooks::CalloutManager::getLibraryHandle ( )

inline

Return library handle.

a post-library callout handle, used by the server to register callouts to run after the user-library callouts.

The library handle is available to the user callout via the callout handle object. It provides a cut-down view of the CalloutManager, allowing the callout to register and deregister callouts in the library of which it is part, whilst denying access to anything that may affect other libraries.

Returns: Reference to library handle for this manager

Definition at line 334 of file callout_manager.h.

◆ getLibraryIndex()

int isc::hooks::CalloutManager::getLibraryIndex ( ) const

inline

Get current library index.

Returns the index of the "current" library. This the index associated with the currently executing callout when callCallouts is executing. When callCallouts() is not executing (as is the case when the load() function in a user-library is called during the library load process), the index can be set by setLibraryIndex().

Note: The value set by this method is lost after a call to callCallouts.

Returns: Current library index.

Definition at line 289 of file callout_manager.h.

Referenced by isc::hooks::LibraryHandle::deregisterAllCallouts(), isc::hooks::LibraryHandle::deregisterCallout(), isc::hooks::LibraryHandle::getParameters(), and isc::hooks::LibraryHandle::registerCallout().

◆ getNumLibraries()

int isc::hooks::CalloutManager::getNumLibraries ( ) const

inline

Get number of libraries.

Returns the number of libraries that this CalloutManager is expected to serve. This is the number passed to its constructor.

Returns: Number of libraries served by this CalloutManager.

Definition at line 273 of file callout_manager.h.

◆ getPostLibraryHandle()

LibraryHandle & isc::hooks::CalloutManager::getPostLibraryHandle ( )

inline

Return post-user callouts library handle.

The LibraryHandle to affect callouts that will run before the user-library callouts.

Returns: Reference to post-user library handle for this manager

Definition at line 354 of file callout_manager.h.

◆ getPreLibraryHandle()

LibraryHandle & isc::hooks::CalloutManager::getPreLibraryHandle ( )

inline

Return pre-user callouts library handle.

The LibraryHandle to affect callouts that will run before the user-library callouts.

Returns: Reference to pre-user library handle for this manager

Definition at line 344 of file callout_manager.h.

◆ registerCallout()

void isc::hooks::CalloutManager::registerCallout	(	const std::string &	name,
		CalloutPtr	callout,
		int	library_index )

Register a callout on a hook for the current library.

Registers a callout function for the current library with a given hook. The callout is added to the end of the callouts for this library that are associated with that hook.

Parameters

name	Name of the hook to which the callout is added.
callout	Pointer to the callout function to be registered.
library_index	Library index used for registering the callout.

Exceptions

NoSuchHook	The hook name is unrecognized.
Unexpected	The hook name is valid but an internal data structure is of the wrong size.

Definition at line 57 of file callout_manager.cc.

References isc::hooks::callouts_logger, isc::hooks::ServerHooks::getIndex(), isc::hooks::HOOKS_CALLOUT_REGISTRATION, isc::hooks::HOOKS_DBG_CALLS, and LOG_DEBUG.

Referenced by isc::hooks::LibraryHandle::registerCallout().

Here is the call graph for this function:

◆ registerCommandHook()

void isc::hooks::CalloutManager::registerCommandHook ( const std::string & command_name )

Registers a hook point for the specified command name.

If the hook point for such command already exists, this function doesn't do anything. The registered hook point name is created after command_name by prefixing it with a dollar sign and replacing all hyphens with underscores, e.g. for the 'foo-bar' command the following hook point name will be generated: '$foo_bar'.

Parameters

command_name Command name for which the hook point should be registered.

Definition at line 322 of file callout_manager.cc.

References isc::hooks::ServerHooks::commandToHookName(), isc::hooks::ServerHooks::findIndex(), isc::hooks::ServerHooks::getCount(), isc::hooks::ServerHooks::getServerHooks(), and isc::hooks::ServerHooks::registerHook().

Referenced by isc::hooks::LibraryHandle::registerCommandCallout().

Here is the call graph for this function:

◆ setLibraryIndex()

void isc::hooks::CalloutManager::setLibraryIndex ( int library_index )

inline

Set current library index.

Sets the current library index. This has the following valid values:

-1: invalidate current index.
0: pre-user library callout.
1 - numlib: user-library callout (where "numlib" is the number of libraries loaded in the system, this figure being passed to this object at construction time).
INT_MAX: post-user library callout.

Parameters

library_index New library index.

Exceptions

NoSuchLibrary if the index is not valid.

Definition at line 307 of file callout_manager.h.

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ CalloutManager()

Member Function Documentation

◆ callCallouts()

◆ callCommandHandlers()

◆ calloutsPresent()

◆ commandHandlersPresent()

◆ deregisterAllCallouts()

◆ deregisterCallout()

◆ getHookLibsVectorSize()

◆ getLibraryHandle()

◆ getLibraryIndex()

◆ getNumLibraries()

◆ getPostLibraryHandle()

◆ getPreLibraryHandle()

◆ registerCallout()

◆ registerCommandHook()

◆ setLibraryIndex()