1[/ 2 Copyright 2014 Renato Tegon Forti, Antony Polukhin 3 Copyright 2015-2019 Antony Polukhin 4 Distributed under the Boost Software License, Version 1.0. 5 (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6/] 7 8[template example_ref[path] '''<ulink url="https://github.com/apolukhin/Boost.DLL/blob/develop/example/'''[path]'''">example/'''[path]'''</ulink>'''] 9 10[def __to_top [link boost_dll.tutorial Back to the Top]] 11 12[section Tutorial] 13 14This Tutorial is provided to give you an idea of how to create and use plugins. 15 16[section Plugin basics] 17 18The first thing to do when creating your own plugins is define the plugin interface. There is an example 19of an abstract class that will be our plugin API: 20 21[import ../example/tutorial_common/my_plugin_api.hpp] 22[plugapi] 23 24Now let's make a DLL/DSO library that will holds implementation of plugin interface and exports it using the 25`extern "C"` and [macroref BOOST_SYMBOL_EXPORT]: 26 27[import ../example/tutorial1/my_plugin_sum.cpp] 28[plugcpp_my_plugin_sum] 29 30Simple application that loads plugin using the [funcref boost::dll::import] 31and [enumref boost::dll::load_mode::type append_decorations]: 32 33[import ../example/tutorial1/tutorial1.cpp] 34[callplugcpp_tutorial1] 35 36That application will output: 37 38[pre 39Loading the plugin 40Constructing my_plugin_sum 41plugin->calculate(1.5, 1.5) call: 3 42Destructing my_plugin_sum ;o) 43] 44 45[*Full sources:] 46 47* [example_ref tutorial_common/my_plugin_api.hpp] 48* [example_ref tutorial1/my_plugin_sum.cpp] 49* [example_ref tutorial1/tutorial1.cpp] 50 51__to_top 52 53[endsect] 54 55 56 57[section Factory method in plugin] 58 59In previous example we were importing from a plugin a single variable. Let's make a class 60that uses our plugin API plugin and holds some state: 61 62[import ../example/tutorial2/my_plugin_aggregator.cpp] 63[plugcpp_my_plugin_aggregator] 64 65As you may see, `my_namespace::create_plugin` is a factory method, that creates 66instances of `my_namespace::my_plugin_aggregator`. We export that method with the name "create_plugin" 67using [macroref BOOST_DLL_ALIAS]. 68 69[import ../example/tutorial2/tutorial2.cpp] 70[callplugcpp_tutorial2] 71 72In that application we have imported the factory method using [funcref boost::dll::import_alias]. 73 74[caution Be careful: `creator` variable holds a reference to the loaded shared library. If this 75variable goes out of scope or will be reset, then the *DLL/DSO will be unloaded* and any attempt to 76dereference the `plugin` variable will lead to *undefined behavior*. ] 77 78Output of the application will be the following: 79 80[pre 81plugin->calculate(1.5, 1.5) call: 3 82plugin->calculate(1.5, 1.5) second call: 6 83Plugin Name: aggregator 84] 85 86[*Full sources:] 87 88* [example_ref tutorial2/my_plugin_aggregator.cpp] 89* [example_ref tutorial2/tutorial2.cpp] 90 91__to_top 92 93[endsect] 94 95[section Searching for a symbol in multiple plugins] 96 97Consider the situation: we have multiple plugins, but only some of them have symbols that we need. 98Let's write a function that search list of plugins and attempts to find `"create_plugin"` method. 99 100[import ../example/tutorial3/tutorial3.cpp] 101[callplugcpp_tutorial3] 102 103If we call that method for all our plugins we'll get the following output: 104 105[pre 106Loading plugin: "/test/libmy_plugin_aggregator.so" 107Matching plugin name: aggregator 108Loading plugin: "/test/libmy_plugin_sum.so" 109Constructing my_plugin_sum 110Destructing my_plugin_sum ;o) 111] 112 113[*Full sources:] 114 115* [example_ref tutorial3/tutorial3.cpp] 116* [example_ref tutorial2/my_plugin_aggregator.cpp] 117* [example_ref tutorial1/my_plugin_sum.cpp] 118 119__to_top 120 121 122[endsect] 123 124[section Linking plugin into the executable] 125 126Linking plugin into the executable has the advantages of 127 128* reducing common size of distribution 129* simplification of installation of distribution 130* faster plugin load 131 132Let's start from creating a linkable in plugin. Such plugin will have a header, 133common for plugin library itself and for the executable: 134 135[import ../example/tutorial4/static_plugin.hpp] 136[plugcpp_my_plugin_static] 137 138Main trick here is the alias definition. When linking plugin into the executable, the alias *must* 139be instantiated in one of the source files of the executable. Otherwise the linker will optimize 140away our plugin. 141 142Here's how the implementation of the plugin looks like: 143 144[import ../example/tutorial4/static_plugin.cpp] 145[plugcpp_my_plugin_staic_impl] 146 147Now if we make a static library from source file and link that static library with the following code, 148we'll be able to import symbols from plugin: 149 150[import ../example/tutorial4/load_self.cpp] 151[plugcpp_my_plugin_load_self] 152 153[note Flag '-rdynamic' must be used when linking the plugin into the executable on Linux OS. 154Otherwise loading symbols from self *will fail*.] 155 156Running the program will output the following: 157 158[pre 159Call function 160Constructing my_plugin_static 161Computed Value: 0 162Destructing my_plugin_static 163] 164 165[note If we want to make a traditional plugin that is located in a separate shared library, all we need to do is 166remove the `#include "static_plugin.hpp"` line and replace `dll::program_location()` with plugin location and name.] 167 168[*Full sources:] 169 170* [example_ref tutorial4/static_plugin.hpp] 171* [example_ref tutorial4/static_plugin.cpp] 172* [example_ref tutorial4/load_self.cpp] 173 174__to_top 175 176[endsect] 177 178[section Symbol shadowing problem (Linux)] 179Let's make an executable, link a plugin into it and attempt to load all the existing plugins: 180 181[import ../example/tutorial5/load_all.cpp] 182[plugcpp_plugins_collector_def] 183[plugcpp_load_all] 184 185With the default flags you'll get a very strange output: 186[pre 187Loaded (0x180db60):"/libs/dll/test/libmy_plugin_aggregator.so" 188Constructing my_plugin_static 189Destructing my_plugin_static 190... 191 192Unique plugins 2: 193(0x180db60): static 194(0x180e3b0): sum 195Destructing my_plugin_sum ;o) 196] 197 198Why `my_plugin_static` was constructed while we were loading `my_plugin_aggregator`? 199 200That's because function `create_plugin` from `libmy_plugin_aggregator.so` was shadowed by 201the `create_plugin` function from other plugin. Dynamic linker thought that `create_plugin` 202was already loaded and there is no need to load it again. 203 204[warning Use "-fvisibility=hidden" flag (at least for plugins) while compiling for POSIX platforms. 205This flag makes your code more portable ("-fvisibility=hidden" is the default behavior under Windows), 206reduces size of the binaries and improves binary load time. 207] 208 209Now if we recompile your example with "-fvisibility=hidden" we'll get the following output: 210[pre 211Loaded (0x2406b60):"/libs/dll/test/libmy_plugin_aggregator.so" 212Loaded (0x2407410):"/libs/dll/test/libgetting_started_library.so" 213Constructing my_plugin_sum 214... 215 216Unique plugins 3: 217(0x2406b60): aggregator 218(0x7fd1cadce2c8): static 219(0x24073b0): sum 220Destructing my_plugin_sum ;o) 221] 222 223[*Full sources:] 224 225* [example_ref tutorial5/load_all.cpp] 226* [example_ref tutorial4/static_plugin.cpp] 227* [example_ref tutorial2/my_plugin_aggregator.cpp] 228* [example_ref tutorial1/my_plugin_sum.cpp] 229 230__to_top 231 232[endsect] 233 234[section Executing callbacks on library unload] 235Boost.DLL provides no out of the box mechanism for catching library unloads. However such task could be easily implemented. 236 237[import ../example/tutorial6/on_unload_lib.cpp] 238All you need to do, is write a simple class that stores callbacks and calls them at destruction: 239[plugcpp_on_unload] 240 241In the example above `my_namespace::on_unload` is a singleton structure that holds a vector of callbacks and 242calls all the callbacks at destruction. 243 244[import ../example/tutorial6/tutorial6.cpp] 245Now we can load this library and provide a callback: 246[callplugcpp_tutorial6] 247 248If we run the example we'll get the following output: 249 250[pre 251Before library unload. 252unloaded 253After library unload. 254] 255 256[*Full sources:] 257 258* [example_ref tutorial6/on_unload_lib.cpp] 259* [example_ref tutorial6/tutorial6.cpp] 260 261__to_top 262 263[endsect] 264 265[section Querying libraries for symbols] 266 267Situation when we do not know names of functions in plugin could occur. In that case querying library could 268be useful. 269 270Imagine the situation: we have a project called 'Anna' that is capable of loading and using plugins that contain 271functions with signature `void(const std::string&)`. We do not know function names, but wish to find out them somehow. 272 273Solution would be pretty simple. Let's agree with plugin developers, that they can name functions as they like, 274but all the plugin functions aliases must be located in section named 'Anna': 275 276[import ../example/tutorial7/library1.cpp] 277[plugcpp_tutorial7_library1] 278 279[import ../example/tutorial7/library2.cpp] 280[plugcpp_tutorial7_library2] 281 282Now we can easily get those functions using the [classref boost::dll::library_info]: 283 284[import ../example/tutorial7/tutorial7.cpp] 285[callplugcpp_tutorial7] 286 287If we run the example we'll get the following output: 288 289[pre 290Function 'print_hello' prints: 291 Hello, User! 292 293Function 'are_you_bored' prints: 294 Are you bored, User? 295 296Function 'howdy' prints: 297 How're you doing, User? 298] 299 300[note `BOOST_DLL_ALIAS` macro by default places all the aliases into the "boostdll" section. ] 301 302[*Full sources:] 303 304* [example_ref tutorial7/library1.cpp] 305* [example_ref tutorial7/library2.cpp] 306* [example_ref tutorial7/tutorial7.cpp] 307 308__to_top 309 310[endsect] 311 312 313[section Advanced library reference counting] 314 315As noted in documentation to the [funcref boost::dll::import] 316variables and functions returned from those functions hold a reference to the shared library. However nested objects and 317objects that are returned by `import*` functions do not hold a reference to the shared library. There's no way to solve 318this issue on the Boost.DLL library level, but you can take care of this problem by your own. Here's an example how this 319could be done. 320 321In this example we'll be importing function that constructs an instance of plugin and binding that 322instance to shared_library. 323 324First of all we need to define a new plugin api: 325 326[import ../example/tutorial8/refcounting_api.hpp] 327[plugcpp_my_plugin_refcounting_api] 328 329This API does not differ much from the previous one. Only one abstract method was added. 330 331Now let's define the plugin: 332[/ 333 [import ../example/tutorial8/refcounting_plugin.hpp] 334 [plugcpp_my_plugin_refcounting_hpp] 335/] 336 337[import ../example/tutorial8/refcounting_plugin.cpp] 338[plugcpp_my_plugin_refcounting] 339 340This plugin does not differ much from our previous examples except the additional method that calls 341[funcref boost::dll::this_line_location] and `create()` function that returns a simple pointer instead of 342`boost::shared_ptr`. 343 344Now lets make a function that binds a newly created instance of `my_refcounting_api` to a shared library: 345[plugcpp_library_holding_deleter_api_bind] 346 347In `bind` method we call `plugin->location()`. This call results in a call to 348[funcref boost::dll::this_line_location] and returns the plugin location. Then a `shared_ptr` that holds a `shared_library` 349is created using the `make_shared` call. 350 351After that we construct a `boost::shared_ptr<my_refcounting_api>` with a `library_holding_deleter` that keeps an instance of the shared library. 352 353[note Use `std::unique_ptr<my_refcounting_api>` instead of `my_refcounting_api*` in production code to avoid memory leaks when `plugin->location()` 354throws or when some other class rises an exception.] 355 356That's it, now we can get instance of a plugin: 357[plugcpp_get_plugin_refcounting] 358 359Here's how it `main()` function look like: 360 361[import ../example/tutorial8/tutorial8.cpp] 362[import ../example/tutorial8/tutorial8_static.cpp] 363 364[table 365[[][Runtime plugin load][Plugin was linked in]] 366[[Code][[callplugcpp_tutorial8]][[callplugcpp_tutorial8_static]]] 367[[Output] 368 [[pre Plugin name: refcounting, 369location: "/libs/dll/librefcounting_plugin.so"]] 370 [[pre Plugin name: refcounting, 371location: "/tutorial8_static"]] 372] 373] 374 375 376 377[*Full sources:] 378 379* [example_ref tutorial8/refcounting_api.hpp] 380* [example_ref tutorial8/refcounting_plugin.hpp] 381* [example_ref tutorial8/refcounting_plugin.cpp] 382* [example_ref tutorial8/tutorial8.cpp] 383* [example_ref tutorial8/tutorial8_static.cpp] 384 385__to_top 386 387[endsect] 388 389[section Importing a C function from Windows dll] 390 391This a trivial example, but it has one tricky place. When you are importing a C function by *it's name* 392you must use [funcref boost::dll::import], not [funcref boost::dll::import_alias]: 393 394[import ../example/tutorial9/tutorial9.cpp] 395[callplugcpp_tutorial9] 396 397[*Full sources:] 398 399* [example_ref tutorial9/tutorial9.cpp] 400 401__to_top 402 403[endsect] 404 405[endsect] 406 407 408