VR Juggler Portable Runtime: vpr::LibraryUNIX Class Reference

List of all members.


Public Member Functions
	LibraryUNIX (const std::string &name)
	Constructs a named library object.
	LibraryUNIX ()
	Default constructor.
	LibraryUNIX (const LibraryUNIX &lib)
	Copy constructor.
	~LibraryUNIX ()
	Unloads the library if one has been loaded.
LibraryUNIX &	operator= (const LibraryUNIX &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.
Symbol search
These functions search within this library for the named symbol.
void *	findSymbol (const char *symbolName)
	Finds and returns an untyped reference to the specified symbol in this library.
void *	findSymbol (const std::string &symbolName)
	Finds and returns an untyped reference to the specified symbol in this library.
Static Public Member Functions
Symbol and library search
Non-instance search routines that give back vpr::LibraryUNIX objects.
static void *	findSymbolAndLibrary (const char *symbolName, LibraryUNIX &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, LibraryUNIX &lib)
	Finds a symbol in one of the currently loaded libraries, and returns both the symbol and the library in which it was found.
Protected Member Functions
void	copy (const LibraryUNIX &lib)
	Makes a copy of the given vpr::LibraryUNIX into this object.

Detailed Description

This implementation wraps dlopen(3) and friends. 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.

Constructor & Destructor Documentation

vpr::LibraryUNIX::LibraryUNIX ( 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 LibraryUNIX.h.

00082       : mName(name)
00083       , mLibrary(NULL)
00084    {
00085       ;
00086    }

vpr::LibraryUNIX::LibraryUNIX ( ) [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 LibraryUNIX.h.

00098       : mName("")
00099       , mLibrary(NULL)
00100    {
00101       ;
00102    }

vpr::LibraryUNIX::LibraryUNIX ( const LibraryUNIX & lib ) [inline]

Copy constructor.

Definition at line 107 of file LibraryUNIX.h.

References copy().

00108       : mName("")
00109       , mLibrary(NULL)
00110    {
00111       copy(lib);
00112    }

vpr::LibraryUNIX::~LibraryUNIX ( ) [inline]

Unloads the library if one has been loaded.

Definition at line 117 of file LibraryUNIX.h.

References unload().

00118    {
00119       if ( NULL != mLibrary )
00120       {
00121          unload();
00122       }
00123    }

Member Function Documentation

LibraryUNIX& vpr::LibraryUNIX::operator= ( const LibraryUNIX & lib ) [inline]

Overlaoded assignment operator.

Definition at line 128 of file LibraryUNIX.h.

References copy().

00129    {
00130       copy(lib);
00131       return *this;
00132    }

const std::string& vpr::LibraryUNIX::getName ( ) const [inline]

Retrieves the name of the library associated with this object.

Definition at line 137 of file LibraryUNIX.h.

00138    {
00139       return mName;
00140    }

vpr::ReturnStatus vpr::LibraryUNIX::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.

Definition at line 55 of file LibraryUNIX.cpp.

References clrOutNORM, clrYELLOW, vpr::ReturnStatus::Fail, RTLD_GLOBAL, RTLD_NOW, vpr::ReturnStatus::setCode(), vprDBG_ALL(), vprDBG_WARNING_LVL, vprDEBUG, vprDEBUG_CONT, vprDEBUG_FLUSH, and vprDEBUG_NEXT.

Referenced by findSymbol().

00056 {
00057    vpr::ReturnStatus status;
00058 
00059    if ( std::string("") != mName )
00060    {
00061       mLibrary = dlopen(mName.c_str(), RTLD_NOW | RTLD_GLOBAL);
00062    }
00063    else
00064    {
00065       mLibrary = dlopen(NULL, RTLD_NOW | RTLD_GLOBAL);
00066    }
00067 
00068    if ( NULL == mLibrary )
00069    {
00070       vprDEBUG_CONT(vprDBG_ALL, vprDBG_WARNING_LVL)
00071          << std::endl << vprDEBUG_FLUSH;
00072       vprDEBUG(vprDBG_ALL, vprDBG_WARNING_LVL)
00073          << clrOutNORM(clrYELLOW, "WARNING:") << " Could not load '" << mName
00074          << "'\n" << vprDEBUG_FLUSH;
00075       vprDEBUG_NEXT(vprDBG_ALL, vprDBG_WARNING_LVL)
00076          << dlerror() << std::endl << vprDEBUG_FLUSH;
00077       status.setCode(vpr::ReturnStatus::Fail);
00078    }
00079 
00080    return status;
00081 }

vpr::ReturnStatus vpr::LibraryUNIX::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 83 of file LibraryUNIX.cpp.

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

Referenced by ~LibraryUNIX().

00084 {
00085    vprASSERT(mLibrary != NULL && "No library to unload");
00086    vpr::ReturnStatus status;
00087 
00088    if ( dlclose(mLibrary) != 0 )
00089    {
00090       status.setCode(vpr::ReturnStatus::Fail);
00091    }
00092    else
00093    {
00094       mLibrary = NULL;
00095    }
00096 
00097    return status;
00098 }

bool vpr::LibraryUNIX::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 167 of file LibraryUNIX.h.

00168    {
00169       return mLibrary != NULL;
00170    }

void* vpr::LibraryUNIX::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.

Postcondition:: If the library was not loaded, it is loaded before symbol lookup.

Parameters:

symbolName

The text representation of the symbol to resolve.

Returns:: An untyped pointer, possibly NULL.

Definition at line 196 of file LibraryUNIX.h.

References load(), and vprASSERT.

Referenced by findSymbol().

00197    {
00198       // If no library has been loaded yet, do it now.  This is done to mimic
00199       // the NSPR behavior.
00200       if ( NULL == mLibrary )
00201       {
00202          load();
00203          vprASSERT(NULL != mLibrary && "Could not load any library");
00204       }
00205 
00206       return dlsym(mLibrary, symbolName);
00207    }

void* vpr::LibraryUNIX::findSymbol ( const std::string & 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.

Postcondition:: If the library was not loaded, it is loaded before symbol lookup.

Parameters:

symbolName

The text representation of the symbol to resolve.

Returns:: An untyped pointer, possibly NULL.

Definition at line 227 of file LibraryUNIX.h.

References findSymbol().

00228    {
00229       return findSymbol(symbolName.c_str());
00230    }

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

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

Parameters:

	symbolName	The text representation of the symbol to resolve.
	lib	The shared library containing the requested symbol.

Returns:: An untyped pointer, possibly NULL.

Definition at line 100 of file LibraryUNIX.cpp.

References vprASSERT.

Referenced by findSymbolAndLibrary().

00102 {
00103    boost::ignore_unused_variable_warning(symbolName);
00104    boost::ignore_unused_variable_warning(lib);
00105    vprASSERT(false && "Not implemented yet");
00106    return NULL;
00107 }

static void* vpr::LibraryUNIX::findSymbolAndLibrary	(	const std::string &	symbolName,
		LibraryUNIX &	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.

Parameters:

	symbolName	The text representation of the symbol to resolve.
	lib	The shared library containing the requested symbol.

Returns:: An untyped pointer, possibly NULL.

Definition at line 259 of file LibraryUNIX.h.

References findSymbolAndLibrary().

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

void vpr::LibraryUNIX::copy ( const LibraryUNIX & lib ) [inline, protected]

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

Definition at line 270 of file LibraryUNIX.h.

References mLibrary, and mName.

Referenced by LibraryUNIX(), and operator=().

00271    {
00272       this->mName    = lib.mName;
00273       this->mLibrary = lib.mLibrary;
00274    }

vpr::LibraryUNIX Class Reference

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation