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< CalloutManager >	getCalloutManager () 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

libraries

List 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

LoadLibrariesNotCalled

Thrown 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_enabled

The 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

libraries	List of libraries to validate.
multi_threading_enabled	The 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:

• library_manager_collection.h
• library_manager_collection.cc