rttr::library Class Reference

The library class provides a cross platform way of explicit loading shared objects (.so on Unix based system and .DLL on windows). More...

#include <library.h>

Public Member Functions

 library (const library &)=delete
 
 library (string_view file_name, string_view version=string_view())
 Constructs a library instance that will load the given library `file_name` and an optional version number version.
 
 ~library ()
 Destroys the library instance.
 
string_view get_error_string () const noexcept
 Returns a text string with the description of the last error that occurred.
 
string_view get_file_name () const noexcept
 When the library was not yet loaded, the file name given in the constructor will be returned.
 
array_range< methodget_global_methods () const noexcept
 A range of all registered global methods in this library.
 
array_range< propertyget_global_properties () const noexcept
 A range of all registered global properties in this library.
 
array_range< typeget_types () const noexcept
 A range of all registered type in this library.
 
bool is_loaded () const noexcept
 Returns true if the library is loaded; otherwise returns false.
 
bool load ()
 Loads the library and returns true; otherwise false.
 
libraryoperator= (const library &)=delete
 
bool unload ()
 Unloads the library.
 

Detailed Description

The library class provides a cross platform way of explicit loading shared objects (.so on Unix based system and .DLL on windows).

With a call to load() the library will be loaded and with unload() unloaded. The explicit call to unload() is not necessary. An internal ref count will trigger the unload automatically on application exit. So you are free the let the library instance go out of scope after loading, the type data will still be available.

After loading the library, the types of the plugin will be registered to the type system of RTTR. Use therefore the macro: RTTR_PLUGIN_REGISTRATION. The types or global properties or methods can be retrieved directly from the library class via getters.

Because the types are registered via RTTR, it is not necessary to additionally mark your types for export (e.g. using __declspec( dllexport ) on windows). Furthermore, with using RTTR, it is possible to export overloaded methods (same name but different signature).

Copying and Assignment

A library object cannot be copied or assigned.

Typical Usage

A typical usage example is the following: Some cpp file in your plugin called: "MyPlugin":

#include <rttr/registration>
struct Foo
{
void set_value(int v) { value = v; }
int get_value() const { return value; }
int value = 0;
};
{
.property("value", &Foo::set_value, &Foo::get_value);
}
The array_range class provides a view into an underlying data structure with lower and upper limits.
Definition array_range.h:64
The class_ is used to register classes to RTTR.
Definition registration.h:130
bind< detail::ctor, Class_Type, acc_level, Visitor_List, Args... > constructor(acc_level level=acc_level())
Register a constructor for this class type with or without arguments.
detail::enum_data< Enum_Type > value(string_view, Enum_Type value)
The value function should be used to add a mapping from enum name to value during the registration pr...
#define RTTR_PLUGIN_REGISTRATION
Use this macro to automatically register your reflection information inside a plugin to RTTR.
Definition registration.h:769

Now in your application, which loads the plugin:

library lib("MyPlugin"); // file suffix is not needed, will be automatically appended
lib.load();
auto t = type::get_by_name("Foo");
std::cout << t.get_name() << std::endl; // prints "Foo"
variant var = t.create();
auto value = t.set_property_value("value", var, 12);
std::cout << t.get_property_value("value", var).to_string() << std::endl; // prints "12"
The library class provides a cross platform way of explicit loading shared objects (....
Definition library.h:100
static type get_by_name(string_view name) noexcept
Returns the type object with the given name name.
The variant class allows to store data of any type and convert between these types transparently.
Definition variant.h:199

Constructor & Destructor Documentation

◆ library() [1/2]

rttr::library::library ( string_view file_name,
string_view version = string_view() )

Constructs a library instance that will load the given library `file_name` and an optional version number version.

The file name is expected to be encoded in UTF-8 format.

It is recommend to omit the file suffix, the library class will automatically look for a file with the native library suffix/prefix ( e.g. lib, .so on Unix, .dylib on macOS and iOS, and .dll on Windows)

◆ ~library()

rttr::library::~library ( )

Destroys the library instance.

Remarks
This will not unload the library. However, on application exit, the library will be unloaded automatically.
See also
unload()

◆ library() [2/2]

rttr::library::library ( const library & )
delete

Member Function Documentation

◆ get_error_string()

string_view rttr::library::get_error_string ( ) const
noexcept

Returns a text string with the description of the last error that occurred.

The error string will be only set when the loading or unloading fails.

Returns
An error string. Empty when no error occurred.
See also
load(), unload()

◆ get_file_name()

string_view rttr::library::get_file_name ( ) const
noexcept

When the library was not yet loaded, the file name given in the constructor will be returned.

After a successful call to load(), get_file_name() returns the fully-qualified file name of the library, including the absolute path to the library if one was given in the constructor. e.g.

library lib("MyPlugin"); // loading a windows DLL relative (actual name is MyPlugin.dll)
lib.load();
lib.get_file_name(); // returns "MyPlugin.dll"
Returns
true when the library is loaded; otherwise false.
See also
load(), unload()

◆ get_global_methods()

array_range< method > rttr::library::get_global_methods ( ) const
noexcept

A range of all registered global methods in this library.

Returns
A range of all loaded methods. Or empty if no methods were loaded.
See also
method

◆ get_global_properties()

array_range< property > rttr::library::get_global_properties ( ) const
noexcept

A range of all registered global properties in this library.

Returns
A range of all loaded properties. Or empty if no properties were loaded.
See also
property

◆ get_types()

array_range< type > rttr::library::get_types ( ) const
noexcept

A range of all registered type in this library.

Returns
A range of all loaded types. Or empty if no types were loaded.
See also
type

◆ is_loaded()

bool rttr::library::is_loaded ( ) const
noexcept

Returns true if the library is loaded; otherwise returns false.

Returns
true when the library is loaded; otherwise false.
See also
load(), unload()

◆ load()

bool rttr::library::load ( )

Loads the library and returns true; otherwise false.

When the library could not be loaded, check the error string.

Returns
true when the library was successfully loaded; otherwise false.
See also
unload(), get_error_string()

◆ operator=()

library & rttr::library::operator= ( const library & )
delete

◆ unload()

bool rttr::library::unload ( )

Unloads the library.

On application exit this happens automatically, so usually you don't need to call this function. When the same library is loaded multiple times, this call will not succeed before every library instance was unloaded.

Remarks
When you unload the library, make sure you don't hold any data (methods, properties or variants etc...) anymore, which was created by this library. Otherwise undefined behavior may occur (crash!).
Returns
true when the library was successfully unloaded, otherwise false.
See also
load(), get_error_string()

The documentation for this class was generated from the following file: