Kea 2.5.8
isc::hooks::LibraryManagerCollection Class Reference

Library manager collection. More...

#include <library_manager_collection.h>

Public Member Functions

 LibraryManagerCollection (const HookLibsCollection &libraries)
 Constructor.
 
 ~LibraryManagerCollection ()
 Destructor.
 
boost::shared_ptr< CalloutManagergetCalloutManager () const
 Get callout manager.
 
HookLibsCollection getLibraryInfo () const
 Returns library info.
 
std::vector< std::string > getLibraryNames () const
 Get library names.
 
int getLoadedLibraryCount () const
 Get number of loaded libraries.
 
bool loadLibraries (bool multi_threading_enabled=false)
 Load libraries.
 
bool prepareUnloadLibraries ()
 Prepare libaries unloading.
 

Static Public Member Functions

static std::vector< std::string > validateLibraries (const std::vector< std::string > &libraries, bool multi_threading_enabled=false)
 Validate libraries.
 

Protected Member Functions

void unloadLibraries ()
 Unload libraries.
 

Detailed Description

Library manager collection.

The LibraryManagerCollection class, as the name implies, is responsible for managing the collection of LibraryManager objects that describe the loaded libraries. As such, it converts a single operation (e.g load libraries) into multiple operations, one per library. However, the class does more than that - it provides a single object with which to manage lifetimes.

As described in the LibraryManager documentation, a CalloutHandle may end up with pointers to memory within the address space of a loaded library. If the library is closed before this address space is deleted, the deletion of the CalloutHandle may attempt to free memory into the newly- unmapped address space and cause a segmentation fault.

To prevent this, each CalloutHandle maintains a shared pointer to the LibraryManagerCollection current when it was created. In addition, the containing HooksManager object also maintains a shared pointer to it. A LibraryManagerCollection is never explicitly deleted: when a new set of libraries is loaded, the HooksManager clears its pointer to the collection. The LibraryManagerCollection is only destroyed when all CallHandle objects referencing it are destroyed.

Note that this does not completely solve the problem - a hook function may have modified a packet being processed by the server and that packet may hold a pointer to memory in the library's virtual address space. To avoid a segmentation fault, that packet needs to free the memory before the LibraryManagerCollection is destroyed and this places demands on the server code. However, the link with the CalloutHandle does at least mean that authors of server code do not need to be so careful about when they destroy CalloutHandles.

The collection object also provides a utility function to validate a set of libraries. The function checks that each library exists, can be opened, that the "version" function exists and return the right number.

Definition at line 70 of file library_manager_collection.h.

Constructor & Destructor Documentation

◆ LibraryManagerCollection()

isc::hooks::LibraryManagerCollection::LibraryManagerCollection ( const HookLibsCollection libraries)

Constructor.

Parameters
librariesList of libraries that this collection will manage. The order of the libraries is important. It holds the library names and its configuration parameters.

Definition at line 41 of file library_manager_collection.cc.

◆ ~LibraryManagerCollection()

isc::hooks::LibraryManagerCollection::~LibraryManagerCollection ( )
inline

Destructor.

Unloads all loaded libraries.

Definition at line 82 of file library_manager_collection.h.

References unloadLibraries().

+ Here is the call graph for this function:

Member Function Documentation

◆ getCalloutManager()

boost::shared_ptr< CalloutManager > isc::hooks::LibraryManagerCollection::getCalloutManager ( ) const

Get callout manager.

Returns a callout manager that can be used with this set of loaded libraries (even if the number of loaded libraries is zero). This method may only be called after loadLibraries() has been called.

Returns
Pointer to a callout manager for this set of libraries.
Exceptions
LoadLibrariesNotCalledThrown if this method is called between construction and the time loadLibraries() is called.

Definition at line 30 of file library_manager_collection.cc.

References isc_throw.

◆ getLibraryInfo()

HookLibsCollection isc::hooks::LibraryManagerCollection::getLibraryInfo ( ) const
inline

Returns library info.

Returns a collection of libraries, each entry consisting of a library name + all its parameters.

Definition at line 125 of file library_manager_collection.h.

◆ getLibraryNames()

std::vector< std::string > isc::hooks::LibraryManagerCollection::getLibraryNames ( ) const
inline

Get library names.

Returns the list of library names. If called before loadLibraries(), the list is the list of names to be loaded; if called afterwards, it is the list of libraries that have been loaded.

Definition at line 117 of file library_manager_collection.h.

◆ getLoadedLibraryCount()

int isc::hooks::LibraryManagerCollection::getLoadedLibraryCount ( ) const

Get number of loaded libraries.

Mainly for testing, this returns the number of libraries that are loaded.

Returns
Number of libraries that are loaded.

Definition at line 133 of file library_manager_collection.cc.

◆ loadLibraries()

bool isc::hooks::LibraryManagerCollection::loadLibraries ( bool  multi_threading_enabled = false)

Load libraries.

Loads the libraries. This creates the LibraryManager associated with each library and calls its loadLibrary() method. If a library fails to load, the loading is abandoned and all libraries loaded so far are unloaded.

Parameters
multi_threading_enabledThe flag which indicates if MT is enabled (used to check hook libraries compatibility with MT).
Returns
true if all libraries loaded, false if one or more failed t

Definition at line 53 of file library_manager_collection.cc.

References isc_throw, and unloadLibraries().

+ Here is the call graph for this function:

◆ prepareUnloadLibraries()

bool isc::hooks::LibraryManagerCollection::prepareUnloadLibraries ( )

Prepare libaries unloading.

Utility function to call before closing libraries. It runs the unload() function when it exists and removes associated callout. When this function returns either there is only one owner (the hook manager) or some visible dangling pointers so libraries are not closed to lower the probability of a crash. See LibraryManager::prepareUnloadLibrary.

Returns
true if all libraries unload were not found or run successfully, false on an error.

Definition at line 122 of file library_manager_collection.cc.

◆ unloadLibraries()

void isc::hooks::LibraryManagerCollection::unloadLibraries ( )
protected

Unload libraries.

Unloads and closes all loaded libraries. They are unloaded in the reverse order to the order in which they were loaded.

Definition at line 107 of file library_manager_collection.cc.

Referenced by ~LibraryManagerCollection(), and loadLibraries().

◆ validateLibraries()

std::vector< std::string > isc::hooks::LibraryManagerCollection::validateLibraries ( const std::vector< std::string > &  libraries,
bool  multi_threading_enabled = false 
)
static

Validate libraries.

Utility function to validate libraries. It checks that the libraries exist, can be opened, that a "version" function is present in them, and that it returns the right number. All errors are logged.

Parameters
librariesList of libraries to validate.
multi_threading_enabledThe flag which indicates if MT is enabled (used to check hook libraries compatibility with MT).
Returns
Vector of libraries that failed to validate, or an empty vector if all validated.

Definition at line 139 of file library_manager_collection.cc.

References isc::hooks::LibraryManager::validateLibrary().

+ Here is the call graph for this function:

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