From 43e598ebeeb821e231ebf79c745d1e975ed6f38a Mon Sep 17 00:00:00 2001 From: Michael Ripperger Date: Thu, 26 Sep 2024 17:27:23 -0500 Subject: [PATCH] Updated README with usage notes --- README.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/README.md b/README.md index 45ea591..eb3027d 100644 --- a/README.md +++ b/README.md @@ -41,3 +41,32 @@ See the [test plugin base class definition](examples/plugin.h) for an example. ## Declaring plugin implementations Creating an implementation of a plugin is as simple as inheriting from the plugin base class, and calling the `EXPORT_CLASS_SECTIONED` macro with the correct section (or calling a custom export macro defined for the plugin base class, described above). See the [test plugin implementations](examples/plugin_impl.cpp) for an example. + +## Usage Notes + +### Multiple instances of the same plugin with varying configuration + +Objects loaded with `PluginLoader::createInstance` are effectively singleton objects. +Multiple calls to `PluginLoader::createInstance` with the same arguments will create a pointer to the same object. +If you need to load multiple instances of the same type of plugin but configured differently, consider making your plugin base class a factory that is itself capable of creating and configuring objects. +See the [`ShapeFactory` plugin for an example implementation](examples/shape/shape.h). + +## Keep plugins in scope during use + +Once the plugin object goes out of scope, the library providing it will be unloaded, resulting in undefined behavior and potential segfaults. +Thus, the plugin object must be kept in scope for as long as it (and objects created by it) are being used. +Here is an example of what **not** to do: + +```c++ +boost_plugin_loader::PluginLoader plugin_loader; + +Shape::Ptr shape; +{ + ShapeFactory::Ptr square_factory = plugin_loader.createInstance("Square"); + shape = square_factory.create(2.0); + + // Library providing "Square" plugin is unloaded here when `square_factory` goes out of scope +} + +std::cout << "Square area: " << shape->area() << std::endl; // <-- segfault because the library providing plugin factory (and the object generated by it) was unloaded +```