Kea  2.3.3-git
isc::hooks::HooksManager Class Reference

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< CalloutHandlecreateCalloutHandle ()
 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 HookLibsCollection getLibraryInfo ()
 Return list of loaded libraries with its parameters. More...
 
static std::vector< std::string > getLibraryNames ()
 Return list of loaded libraries. More...
 
static bool getTestMode ()
 Get test mode. 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 LibraryHandlepostCalloutsLibraryHandle ()
 Return post-callouts library handle. More...
 
static LibraryHandlepreCalloutsLibraryHandle ()
 Return pre-callouts library handle. More...
 
static void prepareUnloadLibraries ()
 Prepare the unloading of libraries. 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 setTestMode (bool mode)
 Set test mode. More...
 
static bool 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 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
indexIndex of the hook to call.
handleReference 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_nameCommand name for which handlers should be called.
handleReference to the CalloutHandle object for the current object being processed.
Exceptions
NoSuchHookif the hook point for the specified command does not exist.

Definition at line 87 of file hooks_manager.cc.

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

+ Here is the call graph for this function:

◆ 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
indexHooks index for which callouts are checked.
Returns
true if callouts are present, false if not.
Exceptions
NoSuchHookGiven 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 345 of file hooks_manager.h.

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

+ 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_nameCommand 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.

◆ 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 200 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,
parked_object 
)
inlinestatic

Removes parked object without calling a callback.

Template Parameters
Ttype of the parked object.
Parameters
hook_namename of the hook point for which the packet is parked.
parked_objectparked object to be removed.
Returns
true if the specified object has been found false otherwise.

Definition at line 320 of file hooks_manager.h.

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

+ 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 222 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 217 of file hooks_manager.cc.

◆ getTestMode()

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

Get test mode.

Returns
the test mode flag.

Definition at line 270 of file hooks_manager.cc.

◆ 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.

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
librariesList 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.
Exceptions
LibrariesStillOpenedwhen some libraries are already loaded.

Definition at line 132 of file hooks_manager.cc.

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

Referenced by isc::test::LibLoadTest::loadLibraries().

+ Here is the call graph for this function:

◆ park()

template<typename T >
static void isc::hooks::HooksManager::park ( const std::string &  hook_name,
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
Typeof the parked object.
Parameters
hook_namename of the hook point for which the packet is parked.
parked_objectpacket to be parked.
unpark_callbackcallback invoked when the packet is unparked.

Definition at line 291 of file hooks_manager.h.

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

+ 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 251 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 241 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 188 of file hooks_manager.cc.

◆ reference()

template<typename T >
static void isc::hooks::HooksManager::reference ( const std::string &  hook_name,
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
Typeof the parked object.
Parameters
hook_namename of the hook point for which the packet is parked.
parked_objectparked object for which reference counter should be increased.

Definition at line 335 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
nameName 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
DuplicateHookA hook with the same name has already been registered.

Definition at line 229 of file hooks_manager.cc.

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

+ Here is the call graph for this function:

◆ 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
modethe test mode flag which enables or disabled the functionality.

Definition at line 265 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 174 of file hooks_manager.cc.

Referenced by isc::test::LibLoadTest::unloadLibraries().

◆ unpark()

template<typename T >
static bool isc::hooks::HooksManager::unpark ( const std::string &  hook_name,
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
Ttype of the parked object.
Parameters
hook_namename of the hook point for which the packet is parked.
parked_objectparked object to be unparked.
Returns
true if the specified object has been found, false otherwise.

Definition at line 308 of file hooks_manager.h.

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

+ 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
librariesList 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 258 of file hooks_manager.cc.

References isc::hooks::LibraryManagerCollection::validateLibraries().

+ Here is the call graph for this function:

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

◆ CONTEXT_DESTROY

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

Definition at line 258 of file hooks_manager.h.


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