Example update (#19)

Author: marip8

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<T>::createInstance` are effectively singleton objects.
+Multiple calls to `PluginLoader<T>::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<ShapeFactory> 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
+```

examples/CMakeLists.txt

@@ -5,7 +5,12 @@ target_cxx_version(${PROJECT_NAME}_example_plugin PUBLIC VERSION 17)
 target_clang_tidy(${PROJECT_NAME}_example_plugin ENABLE ${ENABLE_CLANG_TIDY})
 
 # Example Implementation Library
-add_library(${PROJECT_NAME}_example_plugin_impl plugin_impl.cpp)
+add_library(
+  ${PROJECT_NAME}_example_plugin_impl
+  printer/console_printer.cpp
+  printer/hello_world_printer.cpp
+  shape/square.cpp
+  shape/triangle.cpp)
 target_link_libraries(${PROJECT_NAME}_example_plugin_impl PUBLIC ${PROJECT_NAME}_example_plugin)
 target_cxx_version(${PROJECT_NAME}_example_plugin_impl PUBLIC VERSION 17)
 target_clang_tidy(${PROJECT_NAME}_example_plugin_impl ENABLE ${ENABLE_CLANG_TIDY})

examples/example.cpp

@@ -16,11 +16,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-#include "plugin.h"
+// Include the plugin APIs
+#include "printer/printer.h"
+#include "shape/shape.h"
 
 // STD
 #include <string>
 #include <vector>
+#include <iomanip>
 #include <iostream>
 #include <cassert>
 
@@ -30,12 +33,11 @@
 using boost_plugin_loader::PluginLoader;
 using boost_plugin_loader::Printer;
 using boost_plugin_loader::Shape;
+using boost_plugin_loader::ShapeFactory;
 
-int main(int /*argc*/, char** /*argv*/)  // NOLINT
+void demoPrinterPlugins(const PluginLoader& loader)
 {
-  PluginLoader loader;
-  loader.search_paths.insert(PLUGIN_DIR);
-  loader.search_libraries.insert(PLUGINS);
+  std::cout << "Loading printer plugins" << std::endl;
 
   const std::vector<std::string> printer_plugins = loader.getAvailablePlugins<Printer>();
   assert(printer_plugins.size() == 2);
@@ -46,16 +48,49 @@ int main(int /*argc*/, char** /*argv*/)  // NOLINT
     const Printer::Ptr plugin = loader.createInstance<Printer>(plugin_name);
     assert(plugin != nullptr);
     plugin->operator()();
+    // Note: `plugin` goes out of scope here, and the library providing its definition will be unloaded
   }
+}
+
+void demoShapePlugins(const PluginLoader& loader)
+{
+  std::cout << "Loading shape plugins" << std::endl;
 
-  const std::vector<std::string> shape_plugins = loader.getAvailablePlugins<Shape>();
+  std::vector<std::string> shape_plugins = loader.getAvailablePlugins<ShapeFactory>();
   assert(shape_plugins.size() == 2);
 
-  for (const std::string& plugin_name : shape_plugins)
-  {
-    std::cout << "Loading plugin '" << plugin_name << "'\n";
-    const Printer::Ptr plugin = loader.createInstance<Printer>(plugin_name);
-    assert(plugin != nullptr);
-    plugin->operator()();
-  }
+  // Create the square and triangle factory plugins
+  // Note: these factories must stay in scope as long as they and any object they create are being used. Otherwise, the
+  // library providing them will be unloaded, resulting in undefined behavior and potential segfaults
+  auto square_factory = loader.createInstance<ShapeFactory>("Square");
+  auto triangle_factory = loader.createInstance<ShapeFactory>("Triangle");
+
+  // Create two different types of squares
+  Shape::Ptr square_1 = square_factory->create(2.0);
+  Shape::Ptr square_2 = square_factory->create(4.0);
+
+  // Create two different types of triangles
+  Shape::Ptr triangle_1 = triangle_factory->create(std::tuple<double, double>{ 2.0, 3.0 });
+  Shape::Ptr triangle_2 = triangle_factory->create(std::tuple<double, double>{ 8.0, 20.0 });
+
+  // Compute the areas of all of the different shapes
+  std::cout << std::setprecision(2) << "Square 1 area:   " << square_1->area() << std::endl;
+  std::cout << std::setprecision(2) << "Square 2 area:   " << square_2->area() << std::endl;
+  std::cout << std::setprecision(2) << "Triangle 1 area: " << triangle_1->area() << std::endl;
+  std::cout << std::setprecision(2) << "Triangle 2 area: " << triangle_2->area() << std::endl;
+}
+
+int main(int /*argc*/, char** /*argv*/)  // NOLINT
+{
+  // Create and configure the plugin loader to be able to find libraries in which plugins exist
+  PluginLoader loader;
+  loader.search_paths.insert(PLUGIN_DIR);
+  loader.search_libraries.insert(PLUGINS);
+
+  // Printer plugins
+  demoPrinterPlugins(loader);
+
+  // Shape plugins
+  std::cout << std::endl;
+  demoShapePlugins(loader);
 }

examples/plugin.cpp

@@ -16,7 +16,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-#include "plugin.h"
+#include "printer/printer.h"
+#include "shape/shape.h"
 
 // STD
 #include <string>
@@ -35,11 +36,12 @@ std::string Printer::getSection()
 }
 INSTANTIATE_PLUGIN_LOADER(Printer)
 
-// Define the section name for loading plugins of base class `Shape`
+// Define the section name for loading plugins of base class `ShapeFactory`
 // This should match the section name specified in the plugin export macro for this class
-std::string Shape::getSection()
+std::string ShapeFactory::getSection()
 {
   return "shape";
 }
-INSTANTIATE_PLUGIN_LOADER(Shape)
+INSTANTIATE_PLUGIN_LOADER(ShapeFactory)
+
 }  // namespace boost_plugin_loader

examples/printer/console_printer.cpp

@@ -0,0 +1,35 @@
+/**
+ *
+ * @copyright Copyright (c) 2021, Southwest Research Institute
+ *
+ * @par License
+ * Software License Agreement (Apache License)
+ * @par
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * @par
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#include "printer.h"
+#include <iostream>
+
+namespace boost_plugin_loader
+{
+struct ConsolePrinter : public Printer
+{
+public:
+  void operator()() const override
+  {
+    std::cout << "IMPL: ConsolePrinter" << std::endl;
+  }
+};
+
+}  // namespace boost_plugin_loader
+
+EXPORT_PRINTER_PLUGIN(boost_plugin_loader::ConsolePrinter, ConsolePrinter)

examples/plugin_impl.cpp renamed to examples/printer/hello_world_printer.cpp

@@ -16,21 +16,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-#include "plugin.h"
-
+#include "printer.h"
 #include <iostream>
 
 namespace boost_plugin_loader
 {
-struct ConsolePrinter : public Printer
-{
-public:
-  void operator()() const override
-  {
-    std::cout << "IMPL: ConsolePrinter\n";
-  }
-};
-
 struct HelloWorldPrinter : public Printer
 {
 public:
@@ -40,27 +30,6 @@ struct HelloWorldPrinter : public Printer
   }
 };
 
-struct Square : public Shape
-{
-public:
-  void operator()() const override
-  {
-    std::cout << "IMPL: Square\n";
-  }
-};
-
-struct Triangle : public Shape
-{
-public:
-  void operator()() const override
-  {
-    std::cout << "IMPL: Triangle\n";
-  }
-};
-
 }  // namespace boost_plugin_loader
 
-EXPORT_PRINTER_PLUGIN(boost_plugin_loader::ConsolePrinter, ConsolePrinter)
 EXPORT_PRINTER_PLUGIN(boost_plugin_loader::HelloWorldPrinter, HelloWorldPrinter)
-EXPORT_SHAPE_PLUGIN(boost_plugin_loader::Square, Square)
-EXPORT_SHAPE_PLUGIN(boost_plugin_loader::Triangle, Triangle)

examples/printer/printer.h

@@ -0,0 +1,50 @@
+/**
+ *
+ * @copyright Copyright (c) 2021, Southwest Research Institute
+ *
+ * @par License
+ * Software License Agreement (Apache License)
+ * @par
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * @par
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#pragma once
+
+#include <memory>
+#include <string>
+
+namespace boost_plugin_loader
+{
+// Forward declare PluginLoader and has_getSection classes
+class PluginLoader;
+
+template <typename T>
+struct has_getSection;
+
+/** @brief Plugin interface implementation for testing */
+class Printer
+{
+public:
+  using Ptr = std::shared_ptr<Printer>;
+  virtual ~Printer() = default;
+  virtual void operator()() const = 0;
+
+private:
+  friend class PluginLoader;
+  friend struct has_getSection<Printer>;
+  static std::string getSection();
+};
+
+}  // namespace boost_plugin_loader
+
+#include <boost_plugin_loader/macros.h>
+// NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
+#define EXPORT_PRINTER_PLUGIN(DERIVED_CLASS, ALIAS) EXPORT_CLASS_SECTIONED(DERIVED_CLASS, ALIAS, printer)

examples/plugin.h renamed to examples/shape/shape.h

@@ -20,6 +20,7 @@
 
 #include <memory>
 #include <string>
+#include <any>
 
 namespace boost_plugin_loader
 {
@@ -29,38 +30,42 @@ class PluginLoader;
 template <typename T>
 struct has_getSection;
 
-/** @brief Plugin interface implementation for testing */
-class Printer
+/**
+ * @brief Interface class for representing shapes that can compute area
+ */
+class Shape
 {
 public:
-  using Ptr = std::shared_ptr<Printer>;
-  virtual ~Printer() = default;
+  using Ptr = std::shared_ptr<Shape>;
+  virtual ~Shape() = default;
+
   virtual void operator()() const = 0;
+  virtual double area() const = 0;
 
 private:
   friend class PluginLoader;
-  friend struct has_getSection<Printer>;
+  friend struct has_getSection<Shape>;
   static std::string getSection();
 };
 
-/** @brief Plugin interface implementation for testing */
-class Shape
+/**
+ *  @brief Plugin interface for creating shape objects
+ */
+class ShapeFactory
 {
 public:
-  using Ptr = std::shared_ptr<Shape>;
-  virtual ~Shape() = default;
-  virtual void operator()() const = 0;
+  using Ptr = std::shared_ptr<ShapeFactory>;
+  virtual ~ShapeFactory() = default;
+  virtual std::shared_ptr<Shape> create(const std::any& params) const = 0;
 
 private:
   friend class PluginLoader;
-  friend struct has_getSection<Shape>;
+  friend struct has_getSection<ShapeFactory>;
   static std::string getSection();
 };
 
 }  // namespace boost_plugin_loader
 
 #include <boost_plugin_loader/macros.h>
 // NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
-#define EXPORT_PRINTER_PLUGIN(DERIVED_CLASS, ALIAS) EXPORT_CLASS_SECTIONED(DERIVED_CLASS, ALIAS, printer)
-// NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
 #define EXPORT_SHAPE_PLUGIN(DERIVED_CLASS, ALIAS) EXPORT_CLASS_SECTIONED(DERIVED_CLASS, ALIAS, shape)