VR Juggler Portable Runtime: vpr::LibraryLoader Class Reference

List of all members.


Static Public Member Functions
static vpr::LibraryPtr	findDSO (const std::string &dsoBaseName, const std::vector< std::string > &searchPath)
	Searches for a dynamic shared object (DSO) with the "base" name given in dsoBaseName.
static vpr::LibraryPtr	findDSO (const std::string &dsoBaseName, const std::vector< boost::filesystem::path > &searchPath)
	Searches for a dynamic shared object (DSO) with the "base" name given in dsoBaseName.
static vpr::ReturnStatus	findDSOAndCallEntryPoint (const std::string &dsoBaseName, const std::vector< std::string > &searchPath, const std::string &funcName, boost::function1< bool, void * > callback, vpr::LibraryPtr &dso)
	Searches for a dynamic shared object (DSO) with the "base" name given in dsoBaseName, looks up the named function, and invokes the given callback with that function as its only argument.
static vpr::ReturnStatus	findDSOAndCallEntryPoint (const std::string &dsoBaseName, const std::vector< boost::filesystem::path > &searchPath, const std::string &funcName, boost::function1< bool, void * > callback, vpr::LibraryPtr &dso)
	Searches for a dynamic shared object (DSO) with the "base" name given in dsoBaseName, looks up the named function, and invokes the given callback with that function as its only argument.
static vpr::ReturnStatus	callEntryPoint (vpr::LibraryPtr dso, const std::string &funcName, boost::function1< bool, void * > callback)
	Looks up the named function, and invokes the given callback with that function as its only argument.
static std::string	makeFullDSOName (const std::string &dsoBaseName)
	Constructs the platform-specific DSO name using the given "base" name.
static vpr::ReturnStatus	findDSOAndLookup (const std::string &dsoBaseName, const std::vector< std::string > &searchPath, const std::string &funcName, boost::function1< bool, void * > callback, vpr::LibraryPtr &dso)
static vpr::ReturnStatus	findDSOAndLookup (const std::string &dsoBaseName, const std::vector< boost::filesystem::path > &searchPath, const std::string &funcName, boost::function1< bool, void * > callback, vpr::LibraryPtr &dso)
static vpr::ReturnStatus	findEntryPoint (vpr::LibraryPtr dso, const std::string &funcName, boost::function1< bool, void * > callback)

Detailed Description

Through (relatively) high-level methods, this class introduces a uniform naming scheme for DSOs. More details are provided in the documentation for individual methods. In particular, refer to the documentation for makeFullDSOName.

Member Function Documentation

vpr::LibraryPtr vpr::LibraryLoader::findDSO	(	const std::string &	dsoBaseName,
		const std::vector< std::string > &	searchPath
	)			`[static]`

Searches for a dynamic shared object (DSO) with the "base" name given in dsoBaseName.

The platform-specific name will be determined using makeFullDSOName(). The search will be performed using the list of directories given in searchPath.

Parameters:

	dsoBaseName	The base name of the DSO to be loaded. The platform-specific file extension will be appended prior to the search.
	searchPath	A list of directories where the target DSO may exist. The paths given must be platform-specific (i.e., native) paths.

See also:: makeFullDSOName

Definition at line 80 of file LibraryLoader.cpp.

00082 {
00083    std::vector<fs::path> fs_path;
00084    makeBoostFsVector(searchPath, fs_path);
00085    return findDSO(dsoBaseName, fs_path);
00086 }

static vpr::LibraryPtr vpr::LibraryLoader::findDSO	(	const std::string &	dsoBaseName,
		const std::vector< boost::filesystem::path > &	searchPath
	)			`[static]`

Searches for a dynamic shared object (DSO) with the "base" name given in dsoBaseName.

The platform-specific name will be determined using makeFullDSOName(). The search will be performed using the list of directories given in searchPath.

Parameters:

	dsoBaseName	The base name of the DSO to be loaded. The platform-specific file extension will be appended prior to the search.
	searchPath	A list of directories (specified as Boost.Filesystem path objects) where the target DSO may exist.

See also:: makeFullDSOName

vpr::ReturnStatus vpr::LibraryLoader::findDSOAndCallEntryPoint	(	const std::string &	dsoBaseName,
		const std::vector< std::string > &	searchPath,
		const std::string &	funcName,
		boost::function1< bool, void * >	callback,
		vpr::LibraryPtr &	dso
	)			`[static]`

Searches for a dynamic shared object (DSO) with the "base" name given in dsoBaseName, looks up the named function, and invokes the given callback with that function as its only argument.

The platform-specific name will be determined using makeFullDSOName(). The search will be performed using the list of directories given in searchPath.

Parameters:

	dsoBaseName	The base name of the DSO to be loaded. The platform-specific file extension will be appended prior to the search.
	searchPath	A list of directories where the target DSO may exist. The paths given must be platform-specific (i.e., native) paths.
	funcName	The name of the initialization function in the DSO that will be invoked to initialize the DSO's code.
	callback	A Boost.Function object (that is, a callable object) that will be invoked as a callback to initialize the DSO. It will be passed a void* pointer to the initialization function looked up in the DSO.
	dso	A reference to a vpr::LibraryPtr object through which the loaded DSO will be returned to the caller.

See also:: makeFullDSOName, callEntryPoint

Note:: This method was renamed from findDSOAndLookup() in VPR 0.92.3.

Since:: 0.92.3

Definition at line 125 of file LibraryLoader.cpp.

00130 {
00131    std::vector<fs::path> fs_path;
00132    makeBoostFsVector(searchPath, fs_path);
00133    return findDSOAndCallEntryPoint(dsoBaseName, fs_path, funcName, callback,
00134                                    dso);
00135 }

static vpr::ReturnStatus vpr::LibraryLoader::findDSOAndCallEntryPoint	(	const std::string &	dsoBaseName,
		const std::vector< boost::filesystem::path > &	searchPath,
		const std::string &	funcName,
		boost::function1< bool, void * >	callback,
		vpr::LibraryPtr &	dso
	)			`[static]`

Searches for a dynamic shared object (DSO) with the "base" name given in dsoBaseName, looks up the named function, and invokes the given callback with that function as its only argument.

The platform-specific name will be determined using makeFullDSOName(). The search will be performed using the list of directories given in searchPath.

Parameters:

	dsoBaseName	The base name of the DSO to be loaded. The platform-specific file extension will be appended prior to the search.
	searchPath	A list of directories (specified as Boost.Filesystem path objects) where the target DSO may exist.
	funcName	The name of the initialization function in the DSO that will be invoked to initialize the DSO's code.
	callback	A Boost.Function object (that is, a callable object) that will be invoked as a callback to initialize the DSO. It will be passed a void* pointer to the initialization function looked up in the DSO.
	dso	A reference to a vpr::LibraryPtr object through which the loaded DSO will be returned to the caller.

See also:: makeFullDSOName, callEntryPoint

Note:: This method was renamed from findDSOAndLookup() in VPR 0.92.3.

Since:: 0.92.3

vpr::ReturnStatus vpr::LibraryLoader::callEntryPoint	(	vpr::LibraryPtr	dso,
		const std::string &	funcName,
		boost::function1< bool, void * >	callback
	)			`[static]`

Looks up the named function, and invokes the given callback with that function as its only argument.

If the DSO has not already been loaded, this happens first. This method serves to hide the details of looking up the initialization function. No extra steps are taken with the vpr::Library object to handle platform-specific issues. It is assumed that by this point, the file has been found on the local file system and is ready to be loaded or is already loaded.

This method is essentially just a wrapper around invoking vpr::Library::findSymbol() and handling possible errors associated with doing so. In many cases, it is better to call vpr::Library::findSymbol() directly to avoid the complications of using the callback to handle invoking the entry point function.

Precondition:: vpr::LibraryPtr contains a pointer to a valid vpr::Library object.

Postcondition:: The DSO is loaded.

Parameters:

	dso	A pointer to the vpr::Library object holding the DSO information.
	funcName	The name of the initialization function in the DSO that will be invoked to initialize the DSO's code.
	callback	A Boost.Function object (that is, a callable object) that will be invoked as a callback to initialize the DSO. It will be passed a void* pointer to the initialization function looked up in the DSO.

Note:: This method was renamed from findEntryPoint() in VPR 0.92.3.

Since:: 0.92.3

Definition at line 189 of file LibraryLoader.cpp.

References clrGREEN, clrOutNORM, clrRED, clrRESET, clrSetNORM, clrYELLOW, vpr::ReturnStatus::Fail, vprASSERT, vprDBG_ALL(), vprDBG_CONFIG_LVL, vprDBG_CONFIG_STATUS_LVL, vprDBG_STATE_LVL, vprDBG_WARNING_LVL, vprDEBUG, and vprDEBUG_CONT.

00192 {
00193    vprASSERT(dso.get() != NULL && "Invalid vpr::LibraryPtr object");
00194 
00195    vpr::ReturnStatus status;
00196    const int lib_name_width(50);
00197    bool had_to_load(false);
00198 
00199    // Load the DSO if it has not already been loaded.
00200    if ( ! dso->isLoaded() )
00201    {
00202       had_to_load = true;
00203       vprDEBUG(vprDBG_ALL, vprDBG_CONFIG_STATUS_LVL)
00204          << "Loading library: " << std::setiosflags(std::ios::right)
00205          << std::setfill(' ') << std::setw(lib_name_width) << dso->getName()
00206          << std::resetiosflags(std::ios::right) << "     " << vprDEBUG_FLUSH;
00207 
00208       dso->load();
00209    }
00210 
00211    if ( dso->isLoaded() )
00212    {
00213       // Look up the named function in the DSO and store it in the pointer
00214       // called "entry_point".
00215       void* entry_point = dso->findSymbol(funcName);
00216 
00217       if ( NULL != entry_point )
00218       {
00219          // Only print this closing thing if we had to load the DSO ourselves.
00220          if ( had_to_load )
00221          {
00222             vprDEBUG_CONT(vprDBG_ALL, vprDBG_CONFIG_STATUS_LVL)
00223                << "[ " << clrSetNORM(clrGREEN) << "OK" << clrRESET << " ]\n"
00224                << vprDEBUG_FLUSH;
00225          }
00226 
00227          vprDEBUG(vprDBG_ALL, vprDBG_STATE_LVL)
00228             << "Got pointer to DSO entry point function.\n" << vprDEBUG_FLUSH;
00229 
00230          // Use the caller-provided callback function for actual invocation
00231          // of entry_point.  It is up to this function to cast creator to the
00232          // desired type and do the cool stuff with it.
00233          if ( ! callback(entry_point) )
00234          {
00235             status.setCode(vpr::ReturnStatus::Fail);
00236          }
00237       }
00238       else
00239       {
00240          // Only print this closing thing if we had to load the DSO ourselves.
00241          if ( had_to_load )
00242          {
00243             vprDEBUG_CONT(vprDBG_ALL, vprDBG_CONFIG_STATUS_LVL)
00244                << "[ " << clrSetNORM(clrRED) << "FAILED lookup" << clrRESET
00245                << " ]\n" << vprDEBUG_FLUSH;
00246          }
00247 
00248          vprDEBUG(vprDBG_ALL, vprDBG_WARNING_LVL)
00249             << clrOutNORM(clrYELLOW, "WARNING")
00250             << ": Failed to look up entry point function '" << funcName
00251             << "' in DSO '" << dso->getName() << "'\n"
00252             << vprDEBUG_FLUSH;
00253          status.setCode(vpr::ReturnStatus::Fail);
00254       }
00255    }
00256    else
00257    {
00258       status.setCode(vpr::ReturnStatus::Fail);
00259 
00260       // Only print this closing thing if we had to load the DSO ourselves.
00261       if ( had_to_load )
00262       {
00263          vprDEBUG_CONT(vprDBG_ALL, vprDBG_CONFIG_LVL)
00264             << "[ " << clrSetNORM(clrRED) << "FAILED" << clrRESET << " ]\n"
00265             << vprDEBUG_FLUSH;
00266       }
00267    }
00268 
00269    return status;
00270 }

std::string vpr::LibraryLoader::makeFullDSOName ( const std::string & dsoBaseName ) [static]

Constructs the platform-specific DSO name using the given "base" name.

The DSO base name is a platform-independent, abstract name that makes up a substring of the name of the actual file that will be loaded. A platform-specific extension (.so, .dll, etc) will be appended, and for an instantiation of this class in debug-enabled code, the suffix "_d" will be appended to the DSO's base name. For example, given the base name mydso, a debug build on Windows would search for the file mydso_d.dll. For a release (optimized) build, it would search for mysdso.dll.

Parameters:

dsoBaseName

The base name of the DSO to be loaded.

Definition at line 272 of file LibraryLoader.cpp.

References vpr::DSO_FILE_EXT(), and vpr::DSO_NAME_EXT().

00273 {
00274    return dsoBaseName + DSO_NAME_EXT + DSO_FILE_EXT;
00275 }

vpr::LibraryLoader Class Reference

Static Public Member Functions

Detailed Description

Member Function Documentation