...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
boost::dll::shared_library — This class can be used to load a Dynamic link libraries (DLL's) or Shared Libraries, also know as dynamic shared objects (DSO's) and get their exported symbols (functions and variables).
// In header: <boost/dll/shared_library.hpp> class shared_library { public: // types typedef platform_specific native_handle_t; // construct/copy/destruct shared_library() noexcept; shared_library(const shared_library &); shared_library(const shared_library &, boost::dll::fs::error_code &); shared_library(shared_library &&) noexcept; explicit shared_library(const boost::dll::fs::path &, load_mode::type = load_mode::default_mode); shared_library(const boost::dll::fs::path &, boost::dll::fs::error_code &, load_mode::type = load_mode::default_mode); shared_library(const boost::dll::fs::path &, load_mode::type, boost::dll::fs::error_code &); shared_library & operator=(const shared_library &); shared_library & operator=(shared_library &&) noexcept; ~shared_library(); // public member functions shared_library & assign(const shared_library &, boost::dll::fs::error_code &); shared_library & assign(const shared_library &); void load(const boost::dll::fs::path &, load_mode::type = load_mode::default_mode); void load(const boost::dll::fs::path &, boost::dll::fs::error_code &, load_mode::type = load_mode::default_mode); void load(const boost::dll::fs::path &, load_mode::type, boost::dll::fs::error_code &); void unload() noexcept; bool is_loaded() const noexcept; bool operator!() const noexcept; explicit operator bool() const noexcept; bool has(const char *) const noexcept; bool has(const std::string &) const noexcept; template<typename T> boost::enable_if_c< boost::is_member_pointer< T >::value||boost::is_reference< T >::value, T >::type get(const std::string &) const; template<typename T> boost::disable_if_c< boost::is_member_pointer< T >::value||boost::is_reference< T >::value, T & >::type get(const std::string &) const; template<typename T> boost::enable_if_c< boost::is_member_pointer< T >::value||boost::is_reference< T >::value, T >::type get(const char *) const; template<typename T> boost::disable_if_c< boost::is_member_pointer< T >::value||boost::is_reference< T >::value, T & >::type get(const char *) const; template<typename T> T & get_alias(const char *) const; template<typename T> T & get_alias(const std::string &) const; native_handle_t native() const noexcept; boost::dll::fs::path location() const; boost::dll::fs::path location(boost::dll::fs::error_code &) const; void swap(shared_library &) noexcept; // public static functions static boost::dll::fs::path suffix(); static boost::dll::fs::path decorate(const boost::dll::fs::path &); };
shared_library instances share reference count to an actual loaded DLL/DSO, so it is safe and memory efficient to have multiple instances of shared_library referencing the same DLL/DSO even if those instances were loaded using different paths (relative + absolute) referencing the same object.
On Linux/POSIX link with library "dl". "-fvisibility=hidden" flag is also recommended for use on Linux/POSIX.
shared_library
public
construct/copy/destructshared_library() noexcept;
Creates in anstance that does not reference any DLL/DSO.
Postconditions: |
this->is_loaded() returns false. |
Throws: |
Nothing. |
shared_library(const shared_library & lib);
Copy constructor that increments the reference count of an underlying shared library. Same as calling constructor with lib.location()
parameter.
Parameters: |
|
||
Postconditions: |
lib == *this |
||
Throws: |
shared_library(const shared_library & lib, boost::dll::fs::error_code & ec);
Copy constructor that increments the reference count of an underlying shared library. Same as calling constructor with lib.location(), ec
parameters.
Parameters: |
|
||||
Postconditions: |
lib == *this |
||||
Throws: |
std::bad_alloc in case of insufficient memory. |
shared_library(shared_library && lib) noexcept;
Move constructor. Does not invalidate existing symbols and functions loaded from lib.
Parameters: |
|
||
Postconditions: |
lib.is_loaded() returns false, this->is_loaded() return true. |
||
Throws: |
Nothing. |
explicit shared_library(const boost::dll::fs::path & lib_path, load_mode::type mode = load_mode::default_mode);
Loads a library by specified path with a specified mode.
Parameters: |
|
||||
Throws: |
shared_library(const boost::dll::fs::path & lib_path, boost::dll::fs::error_code & ec, load_mode::type mode = load_mode::default_mode);
Loads a library by specified path with a specified mode.
Parameters: |
|
||||||
Throws: |
std::bad_alloc in case of insufficient memory. |
shared_library(const boost::dll::fs::path & lib_path, load_mode::type mode, boost::dll::fs::error_code & ec);
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
shared_library & operator=(const shared_library & lib);
Assignment operator. If this->is_loaded() then calls this->unload(). Does not invalidate existing symbols and functions loaded from lib.
Parameters: |
|
||
Postconditions: |
lib == *this |
||
Throws: |
shared_library & operator=(shared_library && lib) noexcept;
Move assignment operator. If this->is_loaded() then calls this->unload(). Does not invalidate existing symbols and functions loaded from lib.
Parameters: |
|
||
Postconditions: |
lib.is_loaded() returns false. |
||
Throws: |
Nothing. |
~shared_library();
Destroys the object by calling unload()
. If library was loaded multiple times by different instances, the actual DLL/DSO won't be unloaded until there is at least one instance that references the DLL/DSO.
Throws: |
Nothing. |
shared_library
public member functionsshared_library & assign(const shared_library & lib, boost::dll::fs::error_code & ec);
Makes *this share the same shared object as lib. If *this is loaded, then unloads it.
Parameters: |
|
||||
Postconditions: |
lib.location() == this->location(), lib == *this |
||||
Throws: |
std::bad_alloc in case of insufficient memory. |
shared_library & assign(const shared_library & lib);
Makes *this share the same shared object as lib. If *this is loaded, then unloads it.
Parameters: |
|
||
Postconditions: |
lib.location() == this->location() |
||
Throws: |
void load(const boost::dll::fs::path & lib_path, load_mode::type mode = load_mode::default_mode);
Loads a library by specified path with a specified mode.
Note that if some library is already loaded in this instance, load will call unload() and then load the new provided library.
Parameters: |
|
||||
Throws: |
void load(const boost::dll::fs::path & lib_path, boost::dll::fs::error_code & ec, load_mode::type mode = load_mode::default_mode);
Loads a library by specified path with a specified mode.
Note that if some library is already loaded in this instance, load will call unload() and then load the new provided library.
Parameters: |
|
||||||
Throws: |
std::bad_alloc in case of insufficient memory. |
void load(const boost::dll::fs::path & lib_path, load_mode::type mode, boost::dll::fs::error_code & ec);
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void unload() noexcept;
Unloads a shared library. If library was loaded multiple times by different instances, the actual DLL/DSO won't be unloaded until there is at least one instance that references the DLL/DSO.
Postconditions: |
this->is_loaded() returns false. |
Throws: |
Nothing. |
bool is_loaded() const noexcept;
Check if an library is loaded.
Returns: |
true if a library has been loaded. |
Throws: |
Nothing. |
bool operator!() const noexcept;
Check if an library is not loaded.
Returns: |
true if a library has not been loaded. |
Throws: |
Nothing. |
explicit operator bool() const noexcept;
Check if an library is loaded.
Returns: |
true if a library has been loaded. |
Throws: |
Nothing. |
bool has(const char * symbol_name) const noexcept;
Search for a given symbol on loaded library. Works for all symbols, including alias names.
Parameters: |
|
||
Returns: |
|
||
Throws: |
Nothing. |
bool has(const std::string & symbol_name) const noexcept;
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<typename T> boost::enable_if_c< boost::is_member_pointer< T >::value||boost::is_reference< T >::value, T >::type get(const std::string & symbol_name) const;
Returns reference to the symbol (function or variable) with the given name from the loaded library. This call will always succeed and throw nothing if call to has(const char* )
member function with the same symbol name returned true
.
Example:
int& i0 = lib.get<int>("integer_name"); int& i1 = *lib.get<int*>("integer_alias_name");
Parameters: |
|
||
Template Parameters: |
|
||
Returns: |
Reference to the symbol. |
||
Throws: |
template<typename T> boost::disable_if_c< boost::is_member_pointer< T >::value||boost::is_reference< T >::value, T & >::type get(const std::string & symbol_name) const;
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<typename T> boost::enable_if_c< boost::is_member_pointer< T >::value||boost::is_reference< T >::value, T >::type get(const char * symbol_name) const;
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<typename T> boost::disable_if_c< boost::is_member_pointer< T >::value||boost::is_reference< T >::value, T & >::type get(const char * symbol_name) const;
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<typename T> T & get_alias(const char * alias_name) const;
Returns a symbol (function or variable) from a shared library by alias name of the symbol.
Example:
int& i = lib.get_alias<int>("integer_alias_name");
Parameters: |
|
||
Template Parameters: |
|
||
Throws: |
template<typename T> T & get_alias(const std::string & alias_name) const;
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
native_handle_t native() const noexcept;
Returns the native handler of the loaded library.
Returns: |
Platform-specific handle. |
boost::dll::fs::path location() const;
Returns full path and name of this shared object.
Example:
shared_library lib("test_lib.dll"); filesystem::path full_path = lib.location(); // C:\Windows\System32\test_lib.dll
Returns: |
Full path to the shared library. |
Throws: |
boost::dll::fs::path location(boost::dll::fs::error_code & ec) const;
Returns full path and name of shared module.
Example:
shared_library lib("test_lib.dll"); filesystem::path full_path = lib.location(); // C:\Windows\System32\test_lib.dll
Parameters: |
|
||
Returns: |
Full path to the shared library. |
||
Throws: |
std::bad_alloc. |
void swap(shared_library & rhs) noexcept;
Swaps two libraries. Does not invalidate existing symbols and functions loaded from libraries.
Parameters: |
|
||
Throws: |
Nothing. |
shared_library
public static functionsstatic boost::dll::fs::path suffix();
Returns suffix of shared module: in a call to load() or the constructor/load.
Returns: |
The suffix od shared module: ".dll" (Windows), ".so" (Unix/Linux/BSD), ".dylib" (MacOS/IOS) |
static boost::dll::fs::path decorate(const boost::dll::fs::path & sl);
Returns the decorated path to a shared module name, i.e. with needed prefix/suffix added.
Recommendations: Use load
with load_mode::append_decorations
instead of constructing the decorated path via decorate()
and loading by it.
For instance, for a path like "path/to/boost" it returns :
path/to/libboost.so on posix platforms
path/to/libboost.dylib on OSX
path/to/boost.dll on Windows
Method handles both relative and absolute paths.
Windows note: decorate()
does not prepend "lib" to the decorated path. Use load
with load_mode::append_decorations
for MinGW compatibility purpose.
Posix note: if the initial module name is already prepended with lib, only the suffix() is appended to the path
Parameters: |
|
||
Returns: |
The decorated unportable path that may not exists in the filesystem or could be wrong due to platform specifics. |