vpr::LibraryNSPR Class Reference

Low-level class for loading symbols dynamically. More...

#include <vpr/DynLoad/Library.h>

List of all members.

Public Member Functions
	LibraryNSPR (const std::string &name)
	Constructs a named library object.
	LibraryNSPR ()
	Default constructor.
	LibraryNSPR (const LibraryNSPR &lib)
	Copy constructor.
	~LibraryNSPR ()
	Unloads the library if one has been loaded.
LibraryNSPR &	operator= (const LibraryNSPR &lib)
	Overlaoded assignment operator.
const std::string &	getName () const
	Retrieves the name of the library associated with this object.
vpr::ReturnStatus	load ()
	Loads the library named by this object.
vpr::ReturnStatus	unload ()
	This function undoes the effect of the load() method.
bool	isLoaded () const
	Returns whether this library has been loaded from local storage.
void *	findSymbol (const char *symbolName)
	Finds and returns an untyped reference to the specified symbol in this library.
void *	findSymbol (const std::string &symbolName)
Static Public Member Functions
static void *	findSymbolAndLibrary (const char *symbolName, LibraryNSPR &lib)
	Finds a symbol in one of the currently loaded libraries, and returns both the symbol and the library in which it was found.
static void *	findSymbolAndLibrary (const std::string &symbolName, LibraryNSPR &lib)
Protected Member Functions
void	copy (const LibraryNSPR &lib)
	Makes a copy of the given vpr::LibraryNSPR into this object.

---

Detailed Description

Low-level class for loading symbols dynamically.

This implementation wraps NSPR's existing abstraction for loading symbols. The idea of this class is to provide the basic features needed to load a single shared/dynamic library and to get symbols from it. No features for path extension are provided here.

This class is typedef'd to vpr::Library.

Date:

September 7, 2002

Definition at line 69 of file LibraryNSPR.h.

---

Constructor & Destructor Documentation

vpr::LibraryNSPR::LibraryNSPR

(

const std::string &

name

)

[inline]

Constructs a named library object.

This is the only mechanism to name the library to be loaded, and once named, the library's name cannot be changed.

Parameters:

name

The name of the library to load. It must include the actual name of the library (e.g., "mylib.dll" or "libmylib.so"). The name may be an absolute path or a relative path.

Definition at line 81 of file LibraryNSPR.h.

      : mName(name)
      , mLibrary(NULL)
   {
      ;
   }

vpr::LibraryNSPR::LibraryNSPR

(

)

[inline]

Default constructor.

Using this constructor will prevent setting a name for the library to be loaded, but the created object may still be useful. For example, it can be used to provide access to all symbols currently loaded, or ir may be used as an argument to findSymbolAndLibrary().

See also:

findSymbolAndLibrary, load

Definition at line 97 of file LibraryNSPR.h.

      : mName("")
      , mLibrary(NULL)
   {
      ;
   }

vpr::LibraryNSPR::LibraryNSPR

(

const LibraryNSPR &

lib

)

[inline]

Copy constructor.

Definition at line 107 of file LibraryNSPR.h.

      : mName("")
      , mLibrary(NULL)
   {
      copy(lib);
   }

vpr::LibraryNSPR::~LibraryNSPR

(

)

[inline]

Unloads the library if one has been loaded.

Definition at line 117 of file LibraryNSPR.h.

   {
      if ( NULL != mLibrary )
      {
         unload();
      }
   }

---

Member Function Documentation

LibraryNSPR& vpr::LibraryNSPR::operator=

(

const LibraryNSPR &

lib

)

[inline]

Overlaoded assignment operator.

Definition at line 128 of file LibraryNSPR.h.

   {
      copy(lib);
      return *this;
   }

const std::string& vpr::LibraryNSPR::getName

(

)

const [inline]

Retrieves the name of the library associated with this object.

Definition at line 137 of file LibraryNSPR.h.

   {
      return mName;
   }

vpr::ReturnStatus vpr::LibraryNSPR::load

(

)

Loads the library named by this object.

This function loads and returns a reference to the specified library. The returned reference becomes the library's identity. The function suppresses duplicate loading if the library is already known by the runtime.

Postcondition:

The library is loaded if the runtime loader can find it.

Definition at line 54 of file LibraryNSPR.cpp.

References vpr::ReturnStatus::Fail, vpr::NSPR_PrintError(), vpr::ReturnStatus::setCode(), vpr::ReturnStatus::success(), unload(), and vprASSERT.

{
   vpr::ReturnStatus status;

   // Make sure a library object has not already been loaded.
   if ( NULL != mLibrary )
   {
      vpr::ReturnStatus unload_status;
      unload_status = unload();
      vprASSERT(unload_status.success() && "Library unload failed");
   }

   mLibrary = PR_LoadLibrary(mName.c_str());

   if ( NULL == mLibrary )
   {
      vpr::NSPR_PrintError("\nWARNING: Could not load library -- ");
      status.setCode(vpr::ReturnStatus::Fail);
   }

   return status;
}

vpr::ReturnStatus vpr::LibraryNSPR::unload

(

)

This function undoes the effect of the load() method.

After calling this method, future references to the library using its identity will be invalid.

Precondition:

A library has previously been loaded with load().

Postcondition:

The library is unloaded.

Definition at line 77 of file LibraryNSPR.cpp.

References vpr::ReturnStatus::Fail, vpr::NSPR_PrintError(), vpr::ReturnStatus::setCode(), and vprASSERT.

Referenced by load().

{
   vprASSERT(mLibrary != NULL && "Library not loaded");
   vpr::ReturnStatus status;

   if ( PR_UnloadLibrary(mLibrary) == PR_FAILURE )
   {
      vpr::NSPR_PrintError("WARNING: Could not unload library -- ");
      status.setCode(vpr::ReturnStatus::Fail);
   }
   else
   {
      mLibrary = NULL;
   }

   return status;
}

bool vpr::LibraryNSPR::isLoaded

(

)

const [inline]

Returns whether this library has been loaded from local storage.

Returns:

true is returned if this library has been loaded from local storage, false otherwise.

Definition at line 169 of file LibraryNSPR.h.

   {
      return mLibrary != NULL;
   }

void* vpr::LibraryNSPR::findSymbol

(

const char *

symbolName

)

[inline]

Finds and returns an untyped reference to the specified symbol in this library.

If no library was loaded previously, all libraries known to the runtime and the main program are searched in an unspecified order.

Use this function to look up functions or data symbols in a shared library. Getting a pointer to a symbol in a library does indicate that the library is available when the search was made. The runtime does nothing to ensure the continued validity of the symbol. If the library is unloaded, for instance, the results of any findSymbol() calls become invalid as well.

Parameters:

symbolName

The text representation of the symbol to resolve.

Returns:

An untyped pointer, possibly NULL.

Definition at line 191 of file LibraryNSPR.h.

   {
      return PR_FindSymbol(mLibrary, symbolName);
   }

void* vpr::LibraryNSPR::findSymbol

(

const std::string &

symbolName

)

[inline]

Definition at line 196 of file LibraryNSPR.h.

   {
      return findSymbol(symbolName.c_str());
   }

static void* vpr::LibraryNSPR::findSymbolAndLibrary	(	const char *	symbolName,
		LibraryNSPR &	lib
	)			[inline, static]

Finds a symbol in one of the currently loaded libraries, and returns both the symbol and the library in which it was found.

Definition at line 207 of file LibraryNSPR.h.

References mLibrary.

   {
      return PR_FindSymbolAndLibrary(symbolName, &lib.mLibrary);
   }

static void* vpr::LibraryNSPR::findSymbolAndLibrary	(	const std::string &	symbolName,
		LibraryNSPR &	lib
	)			[inline, static]

Definition at line 212 of file LibraryNSPR.h.

   {
      return findSymbolAndLibrary(symbolName.c_str(), lib);
   }

void vpr::LibraryNSPR::copy

(

const LibraryNSPR &

lib

)

[inline, protected]

Makes a copy of the given vpr::LibraryNSPR into this object.

Definition at line 223 of file LibraryNSPR.h.

References mLibrary, and mName.

   {
      this->mName    = lib.mName;
      this->mLibrary = lib.mLibrary;
   }

---

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

• LibraryNSPR.h
• LibraryNSPR.cpp

---