Kea: isc::hooks::CalloutManager Class Reference

| Kea 3.0.3-git

isc::hooks::CalloutManager Class Reference

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

References isc::hooks::callouts_logger, calloutsPresent(), isc::hooks::PointerConverter::dlsymPtr(), isc::hooks::CalloutHandle::getCurrentHook(), isc::hooks::CalloutHandle::getCurrentLibrary(), 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::util::Stopwatch::logFormatLastDuration(), isc::util::Stopwatch::logFormatTotalDuration(), isc::hooks::CalloutHandle::NEXT_STEP_CONTINUE, isc::hooks::CalloutHandle::NEXT_STEP_DROP, isc::hooks::CalloutHandle::setCurrentHook(), isc::hooks::CalloutHandle::setCurrentLibrary(), isc::hooks::CalloutHandle::setStatus(), isc::util::Stopwatch::start(), and isc::util::Stopwatch::stop().

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

References callCallouts(), isc::hooks::ServerHooks::commandToHookName(), isc::hooks::ServerHooks::getIndex(), 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 109 of file callout_manager.cc.

References calloutsPresent(), isc::hooks::ServerHooks::commandToHookName(), isc::hooks::ServerHooks::findIndex(), 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 286 of file callout_manager.cc.

References isc::hooks::callouts_logger, isc::hooks::HOOKS_ALL_CALLOUTS_DEREGISTERED, isc::hooks::HOOKS_DBG_EXTENDED_CALLS, and LOG_DEBUG.

## ◆ 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 233 of file callout_manager.cc.

References isc::hooks::callouts_logger, isc::hooks::HOOKS_CALLOUT_DEREGISTERED, isc::hooks::HOOKS_DBG_EXTENDED_CALLS, and LOG_DEBUG.

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

## ◆ 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::HOOKS_CALLOUT_REGISTRATION, isc::hooks::HOOKS_DBG_CALLS, and LOG_DEBUG.

## ◆ 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 323 of file callout_manager.cc.

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

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:

- callout_manager.h
- callout_manager.cc