ceph/src/boost/libs/dll/doc/tutorial.qbk

   1 [/
   2     Copyright 2014 Renato Tegon Forti, Antony Polukhin
   3     Copyright 2015-2016 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
  14 This Tutorial is provided to give you an idea of how to create and use plugins.
  15
  16 [section Plugin basics]
  17
  18 The first thing to do when creating your own plugins is define the plugin interface. There is an example
  19 of an abstract class that will be our plugin API:
  20
  21 [import ../example/tutorial_common/my_plugin_api.hpp]
  22 [plugapi]
  23
  24 Now 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
  30 Simple application that loads plugin using the [funcref boost::dll::import]
  31 and [enumref boost::dll::load_mode::type append_decorations]:
  32
  33 [import ../example/tutorial1/tutorial1.cpp]
  34 [callplugcpp_tutorial1]
  35
  36 That application will output:
  37
  38 [pre
  39 Loading the plugin
  40 Constructing my_plugin_sum
  41 plugin->calculate(1.5, 1.5) call:  3
  42 Destructing 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
  59 In previous example we were importing from a plugin a single variable. Let's make a class
  60 that uses our plugin API plugin and holds some state:
  61
  62 [import ../example/tutorial2/my_plugin_aggregator.cpp]
  63 [plugcpp_my_plugin_aggregator]
  64
  65 As you may see, `my_namespace::create_plugin` is a factory method, that creates
  66 instances of `my_namespace::my_plugin_aggregator`. We export that method with the name "create_plugin"
  67 using [macroref BOOST_DLL_ALIAS].
  68
  69 [import ../example/tutorial2/tutorial2.cpp]
  70 [callplugcpp_tutorial2]
  71
  72 In 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
  75 variable goes out of scope or will be reset, then the *DLL/DSO will be unloaded* and any attempt to
  76 dereference the `plugin` variable will lead to *undefined behavior*. ]
  77
  78 Output of the application will be the following:
  79
  80 [pre
  81 plugin->calculate(1.5, 1.5) call:  3
  82 plugin->calculate(1.5, 1.5) second call:  6
  83 Plugin 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
  97 Consider the situation: we have multiple plugins, but only some of them have symbols that we need.
  98 Let'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
 103 If we call that method for all our plugins we'll get the following output:
 104
 105 [pre
 106 Loading plugin: "/test/libmy_plugin_aggregator.so"
 107 Matching plugin name: aggregator
 108 Loading plugin: "/test/libmy_plugin_sum.so"
 109 Constructing my_plugin_sum
 110 Destructing 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
 126 Linking 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
 132 Let's start from creating a linkable in plugin. Such plugin will have a header,
 133 common for plugin library itself and for the executable:
 134
 135 [import ../example/tutorial4/static_plugin.hpp]
 136 [plugcpp_my_plugin_static]
 137
 138 Main trick here is the alias definition. When linking plugin into the executable, the alias *must*
 139 be instantiated in one of the source files of the executable. Otherwise the linker will optimize
 140 away our plugin.
 141
 142 Here's how the implementation of the plugin looks like:
 143
 144 [import ../example/tutorial4/static_plugin.cpp]
 145 [plugcpp_my_plugin_staic_impl]
 146
 147 Now if we make a static library from source file and link that static library with the following code,
 148 we'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.
 154 Otherwise loading symbols from self *will fail*.]
 155
 156 Running the program will output the following:
 157
 158 [pre
 159 Call function
 160 Constructing my_plugin_static
 161 Computed Value: 0
 162 Destructing 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
 166 remove 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)]
 179 Let'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
 185 With the default flags you'll get a very strange output:
 186 [pre
 187 Loaded (0x180db60):"/libs/dll/test/libmy_plugin_aggregator.so"
 188 Constructing my_plugin_static
 189 Destructing my_plugin_static
 190 ...
 191
 192 Unique plugins 2:
 193 (0x180db60): static
 194 (0x180e3b0): sum
 195 Destructing my_plugin_sum ;o)
 196 ]
 197
 198 Why `my_plugin_static` was constructed while we were loading `my_plugin_aggregator`?
 199
 200 That's because function `create_plugin` from `libmy_plugin_aggregator.so` was shadowed by
 201 the `create_plugin` function from other plugin. Dynamic linker thought that `create_plugin`
 202 was 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.
 205 This flag makes your code more portable ("-fvisibility=hidden" is the default behavior under Windows),
 206 reduces size of the binaries and improves binary load time.
 207 ]
 208
 209 Now if we recompile your example with "-fvisibility=hidden" we'll get the following output:
 210 [pre
 211 Loaded (0x2406b60):"/libs/dll/test/libmy_plugin_aggregator.so"
 212 Loaded (0x2407410):"/libs/dll/test/libgetting_started_library.so"
 213 Constructing my_plugin_sum
 214 ...
 215
 216 Unique plugins 3:
 217 (0x2406b60): aggregator
 218 (0x7fd1cadce2c8): static
 219 (0x24073b0): sum
 220 Destructing 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]
 235 Boost.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]
 238 All you need to do, is write a simple class that stores callbacks and calls them at destruction:
 239 [plugcpp_on_unload]
 240
 241 In the example above `my_namespace::on_unload` is a singleton structure that holds a vector of callbacks and
 242 calls all the callbacks at destruction.
 243
 244 [import ../example/tutorial6/tutorial6.cpp]
 245 Now we can load this library and provide a callback:
 246 [callplugcpp_tutorial6]
 247
 248 If we run the example we'll get the following output:
 249
 250 [pre
 251 Before library unload.
 252 unloaded
 253 After 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
 267 Situation when we do not know names of functions in plugin could occur. In that case querying library could
 268 be useful.
 269
 270 Imagine the situation: we have a project called 'Anna' that is capable of loading and using plugins that contain
 271 functions with signature `void(const std::string&)`. We do not know function names, but wish to find out them somehow.
 272
 273 Solution would be pretty simple. Let's agree with plugin developers, that they can name functions as they like,
 274 but 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
 282 Now we can easily get those functions using the [classref boost::dll::library_info]:
 283
 284 [import ../example/tutorial7/tutorial7.cpp]
 285 [callplugcpp_tutorial7]
 286
 287 If we run the example we'll get the following output:
 288
 289 [pre
 290 Function 'print_hello' prints:
 291         Hello, User!
 292
 293 Function 'are_you_bored' prints:
 294         Are you bored, User?
 295
 296 Function '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
 315 As noted in documentation to the [funcref boost::dll::import]
 316 variables and functions returned from those functions hold a reference to the shared library. However nested objects and
 317 objects that are returned by `import*` functions do not hold a reference to the shared library. There's no way to solve
 318 this issue on the Boost.DLL library level, but you can take care of this problem by your own. Here's an example how this
 319 could be done.
 320
 321 In this example we'll be importing function that constructs an instance of plugin and binding that
 322 instance to shared_library.
 323
 324 First 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
 329 This API does not differ much from the previous one. Only one abstract method was added.
 330
 331 Now 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
 340 This 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
 344 Now 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
 347 In `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`
 349 is created using the `make_shared` call.
 350
 351 After 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()`
 354 throws or when some other class rises an exception.]
 355
 356 That's it, now we can get instance of a plugin:
 357 [plugcpp_get_plugin_refcounting]
 358
 359 Here'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,
 369 location: "/libs/dll/librefcounting_plugin.so"]]
 370     [[pre Plugin name: refcounting,
 371 location: "/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
 391 This a trivial example, but it has one tricky place. When you are importing a C function by *it's name*
 392 you 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