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.

◆ ~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 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 ~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 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,
		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 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:

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ LibraryManager()

◆ ~LibraryManager()

Member Function Documentation

◆ checkMultiThreadingCompatible()

◆ checkVersion()

◆ closeLibrary()

◆ getName()

◆ loadLibrary()

◆ openLibrary()

◆ prepareUnloadLibrary()

◆ registerStandardCallouts()

◆ runLoad()

◆ unloadLibrary()

◆ validateLibrary()