Kea  2.3.4-git
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. More...
 
 ~LibraryManager ()
 Destructor. More...
 
std::string getName () const
 Return library name. More...
 
bool loadLibrary ()
 Loads a library. More...
 
bool prepareUnloadLibrary ()
 Prepares library unloading. More...
 

Static Public Member Functions

static bool validateLibrary (const std::string &name)
 Validate library. More...
 

Protected Member Functions

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

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
nameName of the library to load. This should be an absolute path name.
indexIndex of this library
managerCalloutManager object
Exceptions
NoCalloutManagerThrown if the manager argument is NULL.

Definition at line 33 of file library_manager.cc.

References isc_throw.

◆ ~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 ( ) const
protected

Check multi-threading compatibility.

If the multi-threading mode is false 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.

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, isc::util::MultiThreadingMgr::instance(), 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 loadLibrary(), unloadLibrary(), validateLibrary(), and ~LibraryManager().

◆ getName()

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

Return library name.

Returns
Name of this library

Definition at line 140 of file library_manager.h.

◆ loadLibrary()

bool isc::hooks::LibraryManager::loadLibrary ( )

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.

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

Definition at line 317 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 247 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 loadLibrary(), unloadLibrary(), and ~LibraryManager().

+ 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 379 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)
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
nameName of the library to validate
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 410 of file library_manager.cc.

References 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: