Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

Class shared_library

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

Synopsis

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


class shared_library {
public:
  // construct/copy/destruct
  shared_library() noexcept;
  shared_library(const shared_library &);
  shared_library(const shared_library &, boost::system::error_code &);
  shared_library(BOOST_RV_REF(shared_library)) noexcept;
  explicit shared_library(const boost::filesystem::path &, 
                          load_mode::type = load_mode::default_mode);
  shared_library(const boost::filesystem::path &, boost::system::error_code &, 
                 load_mode::type = load_mode::default_mode);
  shared_library(const boost::filesystem::path &, load_mode::type, 
                 boost::system::error_code &);
  shared_library & operator=(BOOST_COPY_ASSIGN_REF(shared_library));
  shared_library & operator=(BOOST_RV_REF(shared_library)) noexcept;
  ~shared_library();

  // private member functions
  shared_library & assign(const shared_library &, boost::system::error_code &);
  shared_library & assign(const shared_library &);
  void load(const boost::filesystem::path &, 
            load_mode::type = load_mode::default_mode);
  void load(const boost::filesystem::path &, boost::system::error_code &, 
            load_mode::type = load_mode::default_mode);
  void load(const boost::filesystem::path &, load_mode::type, 
            boost::system::error_code &);
  void unload() noexcept;
  bool is_loaded() const noexcept;
  bool operator!() const noexcept;
   BOOST_EXPLICIT_OPERATOR_BOOL() 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;

  // public member functions
  native_handle_t native() const noexcept;
  boost::filesystem::path location() const;
  boost::filesystem::path location(boost::system::error_code &) const;
  void swap(shared_library &) noexcept;

  // public static functions
  static boost::filesystem::path suffix();
};

Description

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/destruct

  1. shared_library() noexcept;

    Creates in anstance that does not reference any DLL/DSO.

    Postconditions:

    this->is_loaded() returns false.

    Throws:

    Nothing.
  2. 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:

    lib

    A library to copy.

    Postconditions:

    lib == *this

    Throws:

    boost::system::system_error in case of insufficient memory.
  3. shared_library(const shared_library & lib, boost::system::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:

    ec

    Variable that will be set to the result of the operation.

    lib

    A shared library to copy.

    Postconditions:

    lib == *this

    Throws:

    std::bad_alloc in case of insufficient memory.
  4. shared_library(BOOST_RV_REF(shared_library) lib) noexcept;

    Move constructor. Does not invalidate existing symbols and functions loaded from lib.

    Parameters:

    lib

    A shared library to move from.

    Postconditions:

    lib.is_loaded() returns false, this->is_loaded() return true.

    Throws:

    Nothing.
  5. explicit shared_library(const boost::filesystem::path & lib_path, 
                            load_mode::type mode = load_mode::default_mode);

    Loads a library by specified path with a specified mode.

    Parameters:

    lib_path

    Library file name. Can handle std::string, const char*, std::wstring, const wchar_t* or boost::filesystem::path.

    mode

    A mode that will be used on library load.

    Throws:

    boost::system::system_error in case of insufficient memory.
  6. shared_library(const boost::filesystem::path & lib_path, 
                   boost::system::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:

    ec

    Variable that will be set to the result of the operation.

    lib_path

    Library file name. Can handle std::string, const char*, std::wstring, const wchar_t* or boost::filesystem::path.

    mode

    A mode that will be used on library load.

    Throws:

    std::bad_alloc in case of insufficient memory.
  7. shared_library(const boost::filesystem::path & lib_path, load_mode::type mode, 
                   boost::system::error_code & ec);
  8. shared_library & operator=(BOOST_COPY_ASSIGN_REF(shared_library) lib);

    Assignment operator. If this->is_loaded() then calls this->unload(). Does not invalidate existing symbols and functions loaded from lib.

    Parameters:

    lib

    A shared library to assign from.

    Postconditions:

    lib == *this

    Throws:

    boost::system::system_error in case of insufficient memory.
  9. shared_library & operator=(BOOST_RV_REF(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:

    lib

    A library to move from.

    Postconditions:

    lib.is_loaded() returns false.

    Throws:

    Nothing.
  10. ~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 private member functions

  1. shared_library & 
    assign(const shared_library & lib, boost::system::error_code & ec);

    Makes *this share the same shared object as lib. If *this is loaded, then unloads it.

    Parameters:

    ec

    Variable that will be set to the result of the operation.

    lib

    A library to copy.

    Postconditions:

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

    Throws:

    std::bad_alloc in case of insufficient memory.
  2. shared_library & assign(const shared_library & lib);

    Makes *this share the same shared object as lib. If *this is loaded, then unloads it.

    Parameters:

    lib

    A library instance to assign from.

    Postconditions:

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

    Throws:

    boost::system::system_error in case of insufficient memory.
  3. void load(const boost::filesystem::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:

    lib_path

    Library file name. Can handle std::string, const char*, std::wstring, const wchar_t* or boost::filesystem::path.

    mode

    A mode that will be used on library load.

    Throws:

    boost::system::system_error in case of insufficient memory.
  4. void load(const boost::filesystem::path & lib_path, 
              boost::system::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:

    ec

    Variable that will be set to the result of the operation.

    lib_path

    Library file name. Can handle std::string, const char*, std::wstring, const wchar_t* or boost::filesystem::path.

    mode

    A mode that will be used on library load.

    Throws:

    std::bad_alloc in case of insufficient memory.
  5. void load(const boost::filesystem::path & lib_path, load_mode::type mode, 
              boost::system::error_code & ec);
  6. 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.
  7. bool is_loaded() const noexcept;

    Check if an library is loaded.

    Returns:

    true if a library has been loaded.

    Throws:

    Nothing.
  8. bool operator!() const noexcept;

    Check if an library is not loaded.

    Returns:

    true if a library has not been loaded.

    Throws:

    Nothing.
  9.  BOOST_EXPLICIT_OPERATOR_BOOL() const noexcept;

    Check if an library is loaded.

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

    Returns:

    true if a library has been loaded.

    Returns:

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

    Throws:

    Nothing.

    Nothing.

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

  11. 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");
    

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

    Template Parameters:

    T

    Type of the symbol that we are going to import. Must be explicitly specified.

    Returns:

    Reference to the symbol.

    Throws:

    boost::system::system_error if symbol does not exist or if the DLL/DSO was not loaded.
  12. 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;
  13. 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;
  14. 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;
  15. 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");
    

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

    Parameters:

    alias_name

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

    Template Parameters:

    T

    Type of the symbol that we are going to import. Must be explicitly specified..

    Throws:

    boost::system::system_error if symbol does not exist or if the DLL/DSO was not loaded.
  16. template<typename T> T & get_alias(const std::string & alias_name) const;

shared_library public member functions

  1. native_handle_t native() const noexcept;

    Returns the native handler of the loaded library.

    Returns:

    Platform-specific handle.

  2. boost::filesystem::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::system::system_error
  3. boost::filesystem::path location(boost::system::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:

    ec

    Variable that will be set to the result of the operation.

    Returns:

    Full path to the shared library.

    Throws:

    std::bad_alloc.
  4. void swap(shared_library & rhs) noexcept;

    Swaps two libraries. Does not invalidate existing symbols and functions loaded from libraries.

    Parameters:

    rhs

    Library to swap with.

    Throws:

    Nothing.

shared_library public static functions

  1. static boost::filesystem::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)


PrevUpHomeNext