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.

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

static bool	calloutsPresent (int index)
	Are callouts present?

static void	clearParkingLots ()
	Clears any parking packets.

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

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

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

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

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

static bool	getTestMode ()
	Get test mode.

static bool	loadLibraries (const HookLibsCollection &libraries, bool multi_threading_enabled=false)
	Load and reload libraries.

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

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

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

static void	prepareUnloadLibraries ()
	Prepare the unloading of libraries.

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

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

static void	setTestMode (bool mode)
	Set test mode.

static bool	unloadLibraries ()
	Unload libraries.

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

static std::vector< std::string >	validateLibraries (const std::vector< std::string > &libraries, bool multi_threading_enabled=false)
	Validate library list.

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

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 50 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 76 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 87 of file hooks_manager.cc.

Referenced by isc::config::HookedCommandMgr::delegateCommandToHookLibrary().

◆ 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 54 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 350 of file hooks_manager.h.

References isc::hooks::ServerHooks::getParkingLotsPtr(), and isc::hooks::ServerHooks::getServerHooks().

Referenced by isc::dhcp::Dhcpv4Srv::discardPackets(), and isc::dhcp::Dhcpv6Srv::discardPackets().

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 64 of file hooks_manager.cc.

Referenced by isc::config::HookedCommandMgr::delegateCommandToHookLibrary(), and isc::config::HookedCommandMgr::handleCommand().

◆ 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 203 of file hooks_manager.cc.

Referenced by isc::d2::D2Process::configure(), isc::dhcp::CBControlDHCPv4::databaseConfigApply(), isc::dhcp::CBControlDHCPv6::databaseConfigApply(), isc::config::HookedCommandMgr::delegateCommandToHookLibrary(), isc::dhcp::ControlledDhcpv4Srv::finishConfigHookLibraries(), isc::dhcp::ControlledDhcpv6Srv::finishConfigHookLibraries(), isc::hooks::CalloutHandleAssociate::getCalloutHandle(), isc::config::BaseCommandMgr::processCommand(), isc::dhcp::AllocEngine::reclaimExpiredLeases4Internal(), isc::dhcp::AllocEngine::reclaimExpiredLeases6Internal(), and isc::d2::NameChangeTransaction::selectTSIGKey().

◆ 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 325 of file hooks_manager.h.

References drop(), and isc::hooks::ServerHooks::getServerHooks().

Referenced by drop(), isc::dhcp::Dhcpv4Srv::processLocalizedQuery4(), isc::dhcp::Dhcpv6Srv::processLocalizedQuery6(), isc::dhcp::Dhcpv4Srv::selectSubnet(), isc::dhcp::Dhcpv6Srv::selectSubnet(), and isc::dhcp::Dhcpv4Srv::selectSubnet4o6().

Here is the call graph for this function:

◆ 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 225 of file hooks_manager.cc.

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

◆ 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 220 of file hooks_manager.cc.

Referenced by isc::process::DControllerBase::~DControllerBase(), isc::dhcp::Dhcpv4Srv::~Dhcpv4Srv(), isc::dhcp::Dhcpv6Srv::~Dhcpv6Srv(), and isc::hooks::HooksConfig::verifyLibraries().

◆ getTestMode()

bool isc::hooks::HooksManager::getTestMode ( )

static

Get test mode.

Returns: the test mode flag.

Definition at line 275 of file hooks_manager.cc.

◆ loadLibraries()

bool isc::hooks::HooksManager::loadLibraries	(	const HookLibsCollection &	libraries,
		bool	multi_threading_enabled = false )

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.

Note: this method now requires the libraries are unloaded before being called.

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.
multi_threading_enabled	The flag which indicates if MT is enabled (used to check hook libraries compatibility with MT).

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.

Exceptions

LibrariesStillOpened when some libraries are already loaded.

Definition at line 133 of file hooks_manager.cc.

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

◆ 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 296 of file hooks_manager.h.

References isc::hooks::ServerHooks::getServerHooks().

Referenced by isc::dhcp::Dhcpv4Srv::processLocalizedQuery4(), isc::dhcp::Dhcpv6Srv::processLocalizedQuery6(), isc::dhcp::Dhcpv4Srv::selectSubnet(), isc::dhcp::Dhcpv6Srv::selectSubnet(), and isc::dhcp::Dhcpv4Srv::selectSubnet4o6().

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 254 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 244 of file hooks_manager.cc.

◆ prepareUnloadLibraries()

void isc::hooks::HooksManager::prepareUnloadLibraries ( )

static

Prepare the unloading of libraries.

Calls the unload functions when they exist and removes callouts.

Note: : after the call to this method there should be no visible dangling pointers (i.e. callout handles owning the library manager collection) nor invisible dangling pointers. In the first case it will be impossible to close libraries so they will remain in memory, in the second case a crash is possible in particular at exit time during global object finalization. In both cases the hook library code causing the problem is incorrect and must be fixed.; : it is a logic error to not call this method before unloadLibraries even it hurts only with particular hooks libraries.

Definition at line 191 of file hooks_manager.cc.

Referenced by isc::process::DControllerBase::~DControllerBase(), isc::dhcp::Dhcpv4Srv::~Dhcpv4Srv(), isc::dhcp::Dhcpv6Srv::~Dhcpv6Srv(), isc::dhcp::configureDhcp4Server(), and isc::dhcp::configureDhcp6Server().

◆ 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 340 of file hooks_manager.h.

References isc::hooks::ServerHooks::getServerHooks().

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 232 of file hooks_manager.cc.

◆ setTestMode()

void isc::hooks::HooksManager::setTestMode ( bool mode )

static

Set test mode.

If enabled by unit tests will permit to register callouts before calling loadLibraries which will return immediately without changing current internal state.

Parameters

mode	the test mode flag which enables or disabled the functionality.

Definition at line 270 of file hooks_manager.cc.

◆ unloadLibraries()

bool 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 called after prepareUnloadLibraries in order to destroy appropriate objects. See notes for the class LibraryManager for pitfalls.; : if even after prepareUnloadLibraries there are still visible pointers (i.e. callout handles owning the library manager collection) the method will fail to close libraries and returns false. It is a fatal error as there is no possible recovery. It is a logic error in the hook code too so the solution is to fix it and to restart the server with a correct hook library binary.

Returns: true if all libraries unloaded successfully, false if they are still in memory.

Definition at line 177 of file hooks_manager.cc.

Referenced by isc::process::DControllerBase::~DControllerBase(), isc::dhcp::Dhcpv4Srv::~Dhcpv4Srv(), isc::dhcp::Dhcpv6Srv::~Dhcpv6Srv(), isc::dhcp::configureDhcp4Server(), and isc::dhcp::configureDhcp6Server().

◆ 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 313 of file hooks_manager.h.

References isc::hooks::ServerHooks::getServerHooks(), and unpark().

Referenced by unpark().

Here is the call graph for this function:

◆ validateLibraries()

std::vector< std::string > isc::hooks::HooksManager::validateLibraries	(	const std::vector< std::string > &	libraries,
		bool	multi_threading_enabled = false )

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.
multi_threading_enabled	The flag which indicates if MT is enabled (used to check hook libraries compatibility with MT).

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

Definition at line 261 of file hooks_manager.cc.

Referenced by isc::hooks::HooksConfig::verifyLibraries().

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 262 of file hooks_manager.h.

◆ CONTEXT_DESTROY

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

static

Definition at line 263 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()

◆ getLibraryInfo()

◆ getLibraryNames()

◆ getTestMode()

◆ loadLibraries()

◆ park()

◆ postCalloutsLibraryHandle()

◆ preCalloutsLibraryHandle()

◆ prepareUnloadLibraries()

◆ reference()

◆ registerHook()

◆ setTestMode()

◆ unloadLibraries()

◆ unpark()

◆ validateLibraries()

Member Data Documentation

◆ CONTEXT_CREATE

◆ CONTEXT_DESTROY