Class smart_library

boost::dll::experimental::smart_library — This class is an extension of shared_library, which allows to load C++ symbols.

Synopsis

// In header: <boost/dll/smart_library.hpp>


class smart_library {
public:
  // types
  typedef unspecified mangled_storage;

  // public member functions
  const shared_library & shared_lib() const;
  const mangled_storage & symbol_storage() const;
  mangled_storage & symbol_storage();
  smart_library() noexcept;
  smart_library(const boost::dll::fs::path &, 
                load_mode::type = load_mode::default_mode);
  smart_library(const boost::dll::fs::path &, boost::dll::fs::error_code &, 
                load_mode::type = load_mode::default_mode);
  smart_library(const boost::dll::fs::path &, load_mode::type, 
                boost::dll::fs::error_code &);
  smart_library(const smart_library &) noexcept;
  smart_library(smart_library &&) noexcept;
  explicit smart_library(const shared_library &) noexcept;
  explicit smart_library(shared_library &&) noexcept;
  ~smart_library() noexcept;
  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 &);
  template<typename T> T & get_variable(const std::string &) const;
  template<typename Func> Func & get_function(const std::string &) const;
  template<typename Class, typename Func> 
    unspecified get_mem_fn(const std::string &) const;
  template<typename Signature> 
    constructor< Signature > get_constructor() const;
  template<typename Class> destructor< Class > get_destructor() const;
  template<typename Class> const std::type_info & get_type_info() const;
  template<typename Alias> void add_type_alias(const std::string &);
  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;
  smart_library & assign(const smart_library &);
  void swap(smart_library &) noexcept;
};

Description

This class allows type safe loading of overloaded functions, member-functions, constructors and variables. It also allows to overwrite classes so they can be loaded, while being declared with different names.

	Warning
	Is still very experimental.

Currently known limitations:

Member functions must be defined outside of the class to be exported. That is:

//not exported:
struct BOOST_SYMBOL_EXPORT my_class { void func() {}};
//exported
struct BOOST_SYMBOL_EXPORT my_class { void func();};
void my_class::func() {};

With the current analysis, the first version does get exported in MSVC. MinGW also does export it, BOOST_SYMBOL_EXPORT is written before it. To allow this on windows one can use BOOST_DLL_MEMBER_EXPORT for this, so that MinGW and MSVC can provide those functions. This does however not work with gcc on linux.

Direct initialization of members. On linux the following member variable i will not be initialized when using the allocating constructor:

struct BOOST_SYMBOL_EXPORT my_class { int i; my_class() : i(42) {} };

This does however not happen when the value is set inside the constructor function.

`smart_library` public member functions

const shared_library & shared_lib() const;

Get the underlying shared_library

```
const mangled_storage & symbol_storage() const;
```
Access to the mangled storage, which is created on construction.

Throws:
Nothing.
```
mangled_storage & symbol_storage();
```
Overload, for current development.
```
smart_library() noexcept;
```
Creates in anstance that does not reference any DLL/DSO.

ifile "/root/project/libs/dll/include/boost/dll/smart_library.hpp"

Postconditions:

this->is_loaded() returns false.

Throws:
Nothing.

smart_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.

xmlonly <link linkend='boost.dll.fs.system_error'>boost::dll::fs::system_error</link>, std::bad_alloc in case of insufficient memory.

Parameters:

`lib_path`	Library file name. Can handle std::string, const char, std::wstring, const wchar_t or boost::dll::fs::path.
`mode`	A mode that will be used on library load.

Throws:

smart_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.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

`lib_path`	Library file name. Can handle std::string, const char, std::wstring, const wchar_t or boost::dll::fs::path.
`ec`	Variable that will be set to the result of the operation.
`mode`	A mode that will be used on library load.

Throws:

std::bad_alloc in case of insufficient memory.

smart_library(const boost::dll::fs::path & lib_path, load_mode::type mode, 
              boost::dll::fs::error_code & ec);

```
smart_library(const smart_library & lib) noexcept;
```
copy a smart_library object.

Parameters:

lib

A smart_library to move from.

Throws:
Nothing.
```
smart_library(smart_library && lib) noexcept;
```
Move a smart_library object.

Parameters:

lib

A smart_library to move from.

Throws:
Nothing.
```
explicit smart_library(const shared_library & lib) noexcept;
```
Construct from a shared_library object.

Parameters:

lib

A shared_library to move from.

Throws:
Nothing.
```
explicit smart_library(shared_library && lib) noexcept;
```
Construct from a shared_library object.

Parameters:

lib

A shared_library to move from.

Throws:
Nothing.
```
~smart_library() noexcept;
```
Destroys the smart_library. unload() is called if the DLL/DSO was loaded. If library was loaded multiple times by different instances of shared_library, the actual DLL/DSO won't be unloaded until there is at least one instance of shared_library.

Throws:
Nothing.

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.

xmlonly <link linkend='boost.dll.fs.system_error'>boost::dll::fs::system_error</link>, std::bad_alloc in case of insufficient memory.

Parameters:

`lib_path`	Library file name. Can handle std::string, const char, std::wstring, const wchar_t or boost::dll::fs::path.
`mode`	A mode that will be used on library load.

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.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

`lib_path`	Library file name. Can handle std::string, const char, std::wstring, const wchar_t or boost::dll::fs::path.
`ec`	Variable that will be set to the result of the operation.
`mode`	A mode that will be used on library load.

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);

```
template<typename T> T & get_variable(const std::string & name) const;
```
Load a variable from the referenced library.

Unlinke shared_library::get this function will also load scoped variables, which also includes static class members.

Note

When mangled, MSVC will also check the type.

xmlonly <link linkend='boost.dll.fs.system_error'>boost::dll::fs::system_error</link> if symbol does not exist or if the DLL/DSO was not loaded.

Parameters:

name

Name of the variable

Template Parameters:

T

Type of the variable

Returns:

A reference to the variable of type T.

Throws:

template<typename Func> Func & get_function(const std::string & name) const;

Load a function from the referenced library.

Example:

smart_library lib("test_lib.so");
typedef int      (&add_ints)(int, int);
typedef double (&add_doubles)(double, double);
add_ints     f1 = lib.get_function<int(int, int)>         ("func_name");
add_doubles  f2 = lib.get_function<double(double, double)>("func_name");

	Note
	When mangled, MSVC will also check the return type.

xmlonly <link linkend='boost.dll.fs.system_error'>boost::dll::fs::system_error</link> if symbol does not exist or if the DLL/DSO was not loaded.

Parameters:

name

Name of the function.

Template Parameters:

Func

Type of the function, required for determining the overload

Returns:

A reference to the function of type F.

Throws:

template<typename Class, typename Func> 
  unspecified get_mem_fn(const std::string & name) const;

Load a member-function from the referenced library.

Example (import class is MyClass, which is available inside the library and the host):

smart_library lib("test_lib.so");

typedef int      MyClass(*func)(int);
typedef int   MyClass(*func_const)(int) const;

add_ints     f1 = lib.get_mem_fn<MyClass, int(int)>              ("MyClass::function");
add_doubles  f2 = lib.get_mem_fn<const MyClass, double(double)>("MyClass::function");

	Note
	When mangled, MSVC will also check the return type.

xmlonly <link linkend='boost.dll.fs.system_error'>boost::dll::fs::system_error</link> if symbol does not exist or if the DLL/DSO was not loaded.

Parameters:

name

Name of the function.

Template Parameters:

`Class`	The class the function is a member of. If Class is const, the function will be assumed as taking a const this-pointer. The same applies for volatile.
`Func`	Signature of the function, required for determining the overload

Returns:

A pointer to the member-function with the signature provided

Throws:

template<typename Signature> constructor< Signature > get_constructor() const;

Load a constructor from the referenced library.

Example (import class is MyClass, which is available inside the library and the host):

smart_library lib("test_lib.so");

constructor<MyClass(int)    f1 = lib.get_mem_fn<MyClass(int)>();

xmlonly <link linkend='boost.dll.fs.system_error'>boost::dll::fs::system_error</link> if symbol does not exist or if the DLL/DSO was not loaded.

Template Parameters:

Signature

Signature of the function, required for determining the overload. The return type is the class which this is the constructor of.

Returns:

A constructor object.

Throws:

```
template<typename Class> destructor< Class > get_destructor() const;
```
Load a destructor from the referenced library.

Example (import class is MyClass, which is available inside the library and the host):
```
smart_library lib("test_lib.so");

destructor<MyClass>     f1 = lib.get_mem_fn<MyClass>();
```
xmlonly <link linkend='boost.dll.fs.system_error'>boost::dll::fs::system_error</link> if symbol does not exist or if the DLL/DSO was not loaded.

Template Parameters:

Class

The class whose destructor shall be loaded

Returns:

A destructor object.

Throws:
```
template<typename Class> const std::type_info & get_type_info() const;
```
Load the typeinfo of the given type.

Example (import class is MyClass, which is available inside the library and the host):
```
smart_library lib("test_lib.so");

std::type_info &ti = lib.get_Type_info<MyClass>();
```
xmlonly <link linkend='boost.dll.fs.system_error'>boost::dll::fs::system_error</link> if symbol does not exist or if the DLL/DSO was not loaded.

Template Parameters:

Class

The class whose typeinfo shall be loaded

Returns:

A reference to a type_info object.

Throws:
```
template<typename Alias> void add_type_alias(const std::string & name);
```
This function can be used to add a type alias.

This is to be used, when a class shall be imported, which is not declared on the host side.

Example:
```
smart_library lib("test_lib.so");

lib.add_type_alias<MyAlias>("MyClass"); //when using MyAlias, the library will look for MyClass

//get the destructor of MyClass
destructor<MyAlias> dtor = lib.get_destructor<MyAlias>();
```
Important

If the alias-type is not large enough for the imported class, it will result in undefined behaviour.

Warning

The alias will only be applied for the type signature, it will not replace the token in the scoped name.

Parameters:

name

Name of the class the alias is for.
```
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.

ifile "/root/project/libs/dll/include/boost/dll/smart_library.hpp"

Postconditions:

this->is_loaded() returns false.

Throws:
Nothing.
```
bool is_loaded() const noexcept;
```
Check if an library is loaded.

ifile "/root/project/libs/dll/include/boost/dll/smart_library.hpp"

Returns:

true if a library has been loaded.

Throws:
Nothing.
```
bool operator!() const noexcept;
```
Check if an library is not loaded.

ifile "/root/project/libs/dll/include/boost/dll/smart_library.hpp"

Returns:

true if a library has not been loaded.

Throws:
Nothing.

	Important
If the alias-type is not large enough for the imported class, it will result in undefined behaviour.

explicit operator bool() const noexcept;

bool() const

bool has(const char * symbol_name) const noexcept;

Search for a given symbol on loaded library. Works for all symbols, including alias names.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

symbol_name

Null-terminated symbol name. Can handle std::string, char*, const char*.

Returns:

true if the loaded library contains a symbol with a given name.

Throws:

Nothing.

bool has(const std::string & symbol_name) const noexcept;

```
smart_library & assign(const smart_library & lib);
```
Makes *this share the same shared object as lib. If *this is loaded, then unloads it.

xmlonly <link linkend='boost.dll.fs.system_error'>boost::dll::fs::system_error</link>, std::bad_alloc in case of insufficient memory.

Parameters:

lib

A library instance to assign from.

Postconditions:

lib.location() == this->location()

Throws:
```
void swap(smart_library & rhs) noexcept;
```
Swaps two libraries. Does not invalidate existing symbols and functions loaded from libraries.

ifile "/root/project/libs/dll/include/boost/dll/smart_library.hpp"

Parameters:

rhs

Library to swap with.

Throws:
Nothing.

Postconditions:	this->is_loaded() returns false.
Throws:	Nothing.

	Warning
	The alias will only be applied for the type signature, it will not replace the token in the scoped name.

Returns:	true if a library has not been loaded.
Throws:	Nothing.

Boost C++ Libraries