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	unloadLibrary ()
	Unloads a library. More...

Static Public Member Functions
static bool	validateLibrary (const std::string &name)
	Validate library. More...

Protected Member Functions
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	runUnload ()
	Run the unload function if present. 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 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 unload 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 unloaded, 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 "unload" 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 72 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 unload libraries.

Definition at line 57 of file library_manager.cc.

References closeLibrary(), and unloadLibrary().

Here is the call graph for this function:

Member Function Documentation

◆ 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 107 of file library_manager.cc.

References isc::hooks::HOOKS_DBG_CALLS, isc::hooks::hooks_logger, 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_logger, and LOG_ERROR.

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 and check the version. 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 253 of file library_manager.cc.

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

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, and LOG_ERROR.

Referenced by loadLibrary(), and validateLibrary().

◆ 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 140 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, 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 167 of file library_manager.cc.

References isc::hooks::HOOKS_DBG_TRACE, isc::hooks::hooks_logger, isc::hooks::PointerConverter::loadPtr(), LOG_DEBUG, LOG_ERROR, and isc::Exception::what().

Referenced by loadLibrary().

Here is the call graph for this function:

◆ runUnload()

bool isc::hooks::LibraryManager::runUnload ( )

protected

Run the unload function if present.

Searches for the "unload" 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 211 of file library_manager.cc.

References isc::hooks::HOOKS_DBG_TRACE, isc::hooks::hooks_logger, LOG_DEBUG, LOG_ERROR, LOG_WARN, isc::hooks::PointerConverter::unloadPtr(), and isc::Exception::what().

Referenced by unloadLibrary().

Here is the call graph for this function:

◆ unloadLibrary()

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

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 316 of file library_manager.cc.

References closeLibrary(), isc::hooks::ServerHooks::getHookNames(), isc::hooks::ServerHooks::getServerHooks(), isc::hooks::HOOKS_DBG_CALLS, isc::hooks::HOOKS_DBG_TRACE, isc::hooks::hooks_logger, LOG_DEBUG, LOG_INFO, and runUnload().

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

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.

Parameters

name	Name 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 357 of file library_manager.cc.

References 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

◆ checkVersion()

◆ closeLibrary()

◆ getName()

◆ loadLibrary()

◆ openLibrary()

◆ registerStandardCallouts()

◆ runLoad()

◆ runUnload()

◆ unloadLibrary()

◆ validateLibrary()