Kea: isc::hooks::LibraryManager Class Reference

| Kea 3.0.0

isc::hooks::LibraryManager Class Reference

Library manager. More...

`#include <library_manager.h>`

## Public Member Functions
| LibraryManager (const std::string &name, int index, const boost::shared_ptr< CalloutManager > &manager)
| Constructor.
| ~LibraryManager ()
| Destructor.
std::string | getName () const
| Return library name.
bool | loadLibrary (bool multi_threading_enabled=false)
| Loads a library.
bool | prepareUnloadLibrary ()
| Prepares library unloading.

## Static Public Member Functions
static bool | validateLibrary (const std::string &name, bool multi_threading_enabled=false)
| Validate library.

## Protected Member Functions
bool | checkMultiThreadingCompatible (bool multi_threading_enabled) const
| Check multi-threading compatibility.
bool | checkVersion () const
| Check library version.
bool | closeLibrary ()
| Close library.
bool | openLibrary ()
| Open library.
void | registerStandardCallouts ()
| Register standard callouts.
bool | runLoad ()
| Run the load function if present.
bool | unloadLibrary ()
| Unloads a library.

## Detailed Description

Library manager.

This class handles the loading and unloading of a specific library. It also provides a static method for checking that a library is valid (this is used in configuration parsing).

On loading, it opens the library using dlopen and checks the version (set with the "version" method. If all is OK, it iterates through the list of known hooks and locates their symbols, registering each callout as it does so. Finally it locates the "load" function (if present) and calls it.

On unload, it clears the callouts on all hooks, calls the "unload" method if present, clears the callouts on all hooks, and closes the library.

Note
  Caution needs to be exercised when using the close method. During normal use, data will pass between the server and the library. In this process, the library may allocate memory and pass it back to the server. This could happen by the server setting arguments or context in the CalloutHandle object, or by the library modifying the content of pointed-to data. If the library is closed, this memory may lie in the virtual address space deleted in that process. (The word "may" is used, as this could be operating-system specific.) Should this happen, any reference to the memory will cause a segmentation fault. This can occur in a quite obscure place, for example in the middle of a destructor of an STL class when it is deleting memory allocated when the data structure was extended by a function in the library.
  The only safe way to run the "close" function is to ensure that all possible references to it are removed first. This means that all CalloutHandles must be destroyed, as must any data items that were passed to the callouts. In practice, it could mean that a server suspends processing of new requests until all existing ones have been serviced and all packet/context structures destroyed before reloading the libraries.

When validating a library, only the fact that the library can be opened and version() exists and returns the correct number is checked. The library is closed after the validation.

Definition at line 73 of file library_manager.h.

## Constructor & Destructor Documentation

## ◆ LibraryManager()

isc::hooks::LibraryManager::LibraryManager | ( | const std::string & | name,
|  | int | index,
|  | const boost::shared_ptr< CalloutManager > & | manager )

Constructor.

This constructor is used by external agencies (i.e. the LibraryManagerCollection) when instantiating a LibraryManager. It stores the library name - the actual actual loading is done in loadLibrary().

Parameters

  name | Name of the library to load. This should be an absolute path name.
  index | Index of this library
  manager | CalloutManager object

Exceptions

  NoCalloutManager | Thrown if the manager argument is NULL.

Definition at line 33 of file library_manager.cc.

References isc_throw.

Referenced by validateLibrary().

## ◆ ~LibraryManager()

isc::hooks::LibraryManager::~LibraryManager | ( |  | ) |

Destructor.

If the library is open, closes it. This is principally a safety feature to ensure closure in the case of an exception destroying this object. However, see the caveat in the class header about when it is safe to close libraries.

Definition at line 57 of file library_manager.cc.

References closeLibrary(), and prepareUnloadLibrary().

Here is the call graph for this function:

## Member Function Documentation

## ◆ checkMultiThreadingCompatible()

bool isc::hooks::LibraryManager::checkMultiThreadingCompatible | ( | bool | multi_threading_enabled | ) | const
| protected

Check multi-threading compatibility.

If the multi-threading mode is disabled returns true, else with the library open, accesses the "multi_threading_compatible()" function and returns false if not exists or has value 0, returns true otherwise.

Parameters

  multi_threading_enabled | The flag which indicates if MT is enabled (used to check hook libraries compatibility with MT).

Returns
  bool true if the check succeeded

Definition at line 142 of file library_manager.cc.

References isc::hooks::HOOKS_DBG_CALLS, isc::hooks::HOOKS_LIBRARY_MULTI_THREADING_COMPATIBLE, isc::hooks::HOOKS_LIBRARY_MULTI_THREADING_NOT_COMPATIBLE, isc::hooks::hooks_logger, isc::hooks::HOOKS_MULTI_THREADING_COMPATIBLE_EXCEPTION, LOG_DEBUG, LOG_ERROR, and isc::hooks::PointerConverter::multiThreadingCompatiblePtr().

Referenced by loadLibrary(), and validateLibrary().

Here is the call graph for this function:

## ◆ checkVersion()

bool isc::hooks::LibraryManager::checkVersion | ( |  | ) | const
| protected

Check library version.

With the library open, accesses the "version()" function and, if present, checks the returned value against the hooks version symbol for the currently running Kea. The "version()" function is mandatory and must be present (and return the correct value) for the library to load.

If there is no version() function, or if there is a mismatch in version number, a message logged.

Returns
  bool true if the check succeeded

Definition at line 109 of file library_manager.cc.

References isc::hooks::HOOKS_DBG_CALLS, isc::hooks::HOOKS_INCORRECT_VERSION, isc::hooks::HOOKS_LIBRARY_VERSION, isc::hooks::hooks_logger, isc::hooks::HOOKS_NO_VERSION, isc::hooks::HOOKS_VERSION_EXCEPTION, LOG_DEBUG, LOG_ERROR, version(), and isc::hooks::PointerConverter::versionPtr().

Referenced by loadLibrary(), and validateLibrary().

Here is the call graph for this function:

## ◆ closeLibrary()

bool isc::hooks::LibraryManager::closeLibrary | ( |  | ) |
| protected

Close library.

Closes the library associated with this LibraryManager. A message is logged on an error.

Returns
  true if the library closed successfully, false otherwise. "true" is also returned if the library were already closed when this method was called.

Definition at line 88 of file library_manager.cc.

References isc::hooks::HOOKS_CLOSE_ERROR, isc::hooks::HOOKS_LIBRARY_CLOSED, isc::hooks::hooks_logger, LOG_ERROR, and LOG_INFO.

Referenced by ~LibraryManager(), loadLibrary(), unloadLibrary(), and validateLibrary().

## ◆ getName()

std::string isc::hooks::LibraryManager::getName | ( |  | ) | const
| inline

Return library name.

Returns
  Name of this library

Definition at line 146 of file library_manager.h.

## ◆ loadLibrary()

bool isc::hooks::LibraryManager::loadLibrary | ( | bool | multi_threading_enabled = false | ) |

Loads a library.

Open the library, check the version and the multi-threading compatibility. If all is OK, load all standard symbols then call "load" if present.

It also calls the `isc::log::MessageInitializer::loadDictionary`, prior to invoking the `version` function of the library, to update the global logging dictionary with the log messages registered by the loaded library.

Parameters

  multi_threading_enabled | The flag which indicates if MT is enabled (used to check hook libraries compatibility with MT).

Returns
  true if the library loaded successfully, false otherwise. In the latter case, the library will be unloaded if possible.

Definition at line 323 of file library_manager.cc.

References checkMultiThreadingCompatible(), checkVersion(), closeLibrary(), isc::hooks::HOOKS_DBG_TRACE, isc::hooks::HOOKS_LIBRARY_LOADED, isc::hooks::HOOKS_LIBRARY_LOADING, isc::hooks::hooks_logger, isc::log::MessageInitializer::loadDictionary(), LOG_DEBUG, LOG_INFO, isc::log::LoggerManager::logDuplicatedMessages(), openLibrary(), prepareUnloadLibrary(), registerStandardCallouts(), and runLoad().

Here is the call graph for this function:

## ◆ openLibrary()

bool isc::hooks::LibraryManager::openLibrary | ( |  | ) |
| protected

Open library.

Opens the library associated with this LibraryManager. A message is logged on an error.

Returns
  true if the library opened successfully, false otherwise.

Definition at line 72 of file library_manager.cc.

References isc::hooks::hooks_logger, isc::hooks::HOOKS_OPEN_ERROR, and LOG_ERROR.

Referenced by loadLibrary(), and validateLibrary().

## ◆ prepareUnloadLibrary()

bool isc::hooks::LibraryManager::prepareUnloadLibrary | ( |  | ) |

Prepares library unloading.

Searches for the "unload" framework function and, if present, runs it. Regardless of status, remove all callouts associated with this library on all hooks.

Returns
  bool true if not found or found and run successfully, false on an error. In this case, an error message will have been output.

Definition at line 253 of file library_manager.cc.

References isc::hooks::ServerHooks::getHookNames(), isc::hooks::ServerHooks::getServerHooks(), isc::hooks::HOOKS_CALLOUTS_REMOVED, isc::hooks::HOOKS_DBG_CALLS, isc::hooks::HOOKS_DBG_TRACE, isc::hooks::hooks_logger, isc::hooks::HOOKS_NO_UNLOAD, isc::hooks::HOOKS_UNLOAD_ERROR, isc::hooks::HOOKS_UNLOAD_EXCEPTION, isc::hooks::HOOKS_UNLOAD_FRAMEWORK_EXCEPTION, isc::hooks::HOOKS_UNLOAD_SUCCESS, LOG_DEBUG, LOG_ERROR, LOG_WARN, isc::hooks::PointerConverter::unloadPtr(), and isc::Exception::what().

Referenced by ~LibraryManager(), loadLibrary(), and unloadLibrary().

Here is the call graph for this function:

## ◆ registerStandardCallouts()

void isc::hooks::LibraryManager::registerStandardCallouts | ( |  | ) |
| protected

Register standard callouts.

Loops through the list of hook names and searches the library for functions with those names. Any that are found are registered as callouts for that hook.

Definition at line 176 of file library_manager.cc.

References isc::hooks::PointerConverter::calloutPtr(), isc::hooks::ServerHooks::getHookNames(), isc::hooks::ServerHooks::getServerHooks(), isc::hooks::HOOKS_DBG_CALLS, isc::hooks::hooks_logger, isc::hooks::HOOKS_STD_CALLOUT_REGISTERED, and LOG_DEBUG.

Referenced by loadLibrary().

Here is the call graph for this function:

## ◆ runLoad()

bool isc::hooks::LibraryManager::runLoad | ( |  | ) |
| protected

Run the load function if present.

Searches for the "load" framework function and, if present, runs it.

Returns
  bool true if not found or found and run successfully, false on an error. In this case, an error message will have been output.

Definition at line 203 of file library_manager.cc.

References isc::hooks::HOOKS_DBG_TRACE, isc::hooks::HOOKS_LOAD_ERROR, isc::hooks::HOOKS_LOAD_EXCEPTION, isc::hooks::HOOKS_LOAD_FRAMEWORK_EXCEPTION, isc::hooks::HOOKS_LOAD_SUCCESS, isc::hooks::hooks_logger, isc::hooks::HOOKS_NO_LOAD, isc::hooks::PointerConverter::loadPtr(), LOG_DEBUG, LOG_ERROR, and isc::Exception::what().

Referenced by loadLibrary().

Here is the call graph for this function:

## ◆ unloadLibrary()

bool isc::hooks::LibraryManager::unloadLibrary | ( |  | ) |
| protected

Unloads a library.

Calls the libraries "unload" function if present, the closes the library.

However, see the caveat in the class header about when it is safe to unload libraries.

Returns
  true if the library unloaded successfully, false if an error occurred in the process (most likely the unload() function (if present) returned an error). Even if an error did occur, the library is closed if possible.

Definition at line 385 of file library_manager.cc.

References closeLibrary(), isc::hooks::HOOKS_DBG_TRACE, isc::hooks::HOOKS_LIBRARY_UNLOADED, isc::hooks::HOOKS_LIBRARY_UNLOADING, isc::hooks::hooks_logger, LOG_DEBUG, LOG_INFO, and prepareUnloadLibrary().

Here is the call graph for this function:

## ◆ validateLibrary()

bool isc::hooks::LibraryManager::validateLibrary | ( | const std::string & | name,
|  | bool | multi_threading_enabled = false )
| static

Validate library.

A static method that is used to validate a library. Validation checks that the library can be opened, that "version" exists, and that it returns the right number, and the multi-threading compatibility.

Parameters

  name | Name of the library to validate
  multi_threading_enabled | The flag which indicates if MT is enabled (used to check hook libraries compatibility with MT).

Returns
  true if the library validated, false if not. If the library fails to validate, the reason for the failure is logged.

Definition at line 416 of file library_manager.cc.

References LibraryManager(), checkMultiThreadingCompatible(), checkVersion(), closeLibrary(), and openLibrary().

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

Here is the call graph for this function:

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

- library_manager.h
- library_manager.cc