1[/ 2 Copyright 2016 Klemens D. Morgenstern 3 Distributed under the Boost Software License, Version 1.0. 4 (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 5/] 6 7[template mangled_ref[path] '''<ulink url="https://github.com/apolukhin/Boost.DLL/blob/develop/example/'''[path]'''">example/'''[path]'''</ulink>'''] 8 9[def __to_top [link boost_dll.mangled_import Back to the Top]] 10 11[section Mangled Import] 12 13This section describes the experimental feature of allowing the import of mangled symbols from an dll. While this feature is unique to this library and looks quite promising, it is not throroughly tested and thus not considered stable. 14 15As a short example we can import the following functions quite easily: 16 17``` 18//library.dll 19namespace foo { 20int bar(int); 21double bar(double); 22} 23``` 24 25And the import looks like this: 26 27``` 28auto f1 = import_mangled<int(int)>("library.dll", "foo::bar"); 29auto f2 = import_mangled<double(double)>("library.dll", "foo::bar"); 30cout << f1(42) << endl; 31cout << f2(3.2) << endl; 32``` 33 34[section Support & Requirements] 35 36Currently, the Itanium ABI and the MSVC ABI are implemented. The MSVC ABI requires boost.spirit.x3 support, allowing only the usage of MSVC 2015. The Itanium API requires C++11. 37 38* Gcc 39* Clang 40* MSVC 2015 41* Intel C++ 42 43The Itanium API does not import the return type of functions, nor the type of global variables. 44 45[endsect] 46 47[section Mangled Import Example] 48 49The core of the mangled import is the [classref smart_library] class. It can import functions and variables in their mangled form; to do this, the smart_library reads the entire outline of the library and demangles every entry point in it. That also means, that this class should only be constructed once. 50 51In order to import all the methods in the following library, we will use the [classref smart_library] . 52 53The first thing to do when creating your own plugins is define the plugin interface. There is an example 54of an abstract class that will be our plugin API: 55 56[import ../example/mangled/my_cpp_plugin.hpp] 57[cppplug] 58 59Alright, now we have the definition for the plugin, so we use it in the following full-fleshed example. Mind that there is a more convenient solution to import member-functions which will be discussed later on. This example shows however what the [classref smart_lib] provides as features. 60 61[import ../example/mangled/smart_lib.cpp] 62 63At first we setup the smart library. Mind that the alias class is needed to provide a type-alias for the my_plugin. 64[smart_lib_setup] 65 66In order to create the class, we will need to allocate memory. That of course means, that we need to know the size; unfortunately it is not exported into the dll, so we added the static size function for export. Static are used as plain functions. 67 68So we import it, call it and allocate memory. 69 70[smart_lib_size] 71 72Now, we have the memory size and a reference with our alias type. In order to use it, we need to register the type as an alias. That will allow the smart library to resolve the type name. 73 74[smart_lib_type_alias] 75 76In order to use the class, we of course need to initialize it, i.e. call the constructor. The Itanium ABI may also implement an allocating constructor. That is why a constructor may have two functions; since we already have allocated the memory we use the standard constructor version, of the constructor from string. So we select the constructor by passing the signature. 77 78[smart_lib_ctor] 79 80So since the class is now initialized, we can call the name method. If the function is const and/or volatile the type parameter passed as type must have the same qualifiers. 81 82[smart_lib_name] 83 84Overloaded functions can only be imported separately. 85 86[smart_lib_calculate] 87 88Import of static variable is done like with plain variable. 89 90[smart_lib_var] 91 92Since we are finished, we call the destructor of the class. 93 94[smart_lib_dtor] 95 96__to_top 97 98[endsect] 99 100[section Class Import] 101 102Now it is demonstrated, how mangled and methods may be imported. This is however a rather versatile way, so an easier interface is provided, which also allows access to the type_info of an object. 103 104We will take the same class and import the same methods, but do it with the import features. 105 106[import ../example/mangled/import_class.cpp] 107 108We put the library into a shared_pointer, because every import will hold such a pointer to it. That is, we do not want to copy it. 109 110[import_class_setup] 111 112Similar to the previous example, we need the size of the class. 113 114[import_class_size] 115 116On a side note, we can also import variable easily with that function. 117 118[import_class_value] 119 120We do the forward declaration on the first call, and invoke the constructor directly. This is quite simple and allows to invoke the constructor directly. The destructor will be invoked automatically. 121 122[import_class_ctor] 123 124Invoking a function will still require to import it first. 125 126[import_class_name] 127 128For overloaded functions, we can import them as groups, which will give us an object containing the overloads. 129 130[import_class_calc] 131 132Additionally, we can access the typeinfo like this. 133 134[import_class_typeinfo] 135 136__to_top 137 138[endsect] 139 140[section Overloading qualifiers] 141 142Not handled in the example was the question, of how it is handled if the qualification differs for an overloaded function. This can be done, by passing the class again with another qualification - a function signature will always pick the last one provided. 143 144If we have this in our plugin: 145``` 146struct plugin 147{ 148 void f(int); 149 void f(double); 150 void f(int) const; 151 void f() const; 152 void f() volatile; 153 void f(int) volatile; 154 void f(double); const volatile; 155}; 156``` 157 158we can import them all at once, with the following command: 159 160``` 161 auto f = import_class< 162 alias, f(int), f(double), //not qualified 163 const alias, f(int), f(), //const 164 volatile alias, f(), f(int), //volatile 165 const volatile alias, f(double)//const volatile 166 >(lib, "f"); 167 168``` 169 170[endsect] 171[endsect] 172 173 174