From e2f037ac3717ff07e2f2cd60434f2b5cc2a2ea0d Mon Sep 17 00:00:00 2001 From: Caitlin Ross Date: Thu, 8 Jul 2021 11:11:03 -0400 Subject: [PATCH] plugin engine: user guide docs --- docs/user_guide/source/conf.py | 1 + docs/user_guide/source/engines/engines.rst | 1 + docs/user_guide/source/engines/plugin.rst | 97 ++++++++++++++++++++++ 3 files changed, 99 insertions(+) create mode 100644 docs/user_guide/source/engines/plugin.rst diff --git a/docs/user_guide/source/conf.py b/docs/user_guide/source/conf.py index fc6fbfb4ef..0924fc2155 100644 --- a/docs/user_guide/source/conf.py +++ b/docs/user_guide/source/conf.py @@ -140,6 +140,7 @@ 'engines/sst.rst', 'engines/inline.rst', 'engines/null.rst', + 'engines/plugin.rst', # 'engines/engines.rst', # 'faq/faq.rst', ] diff --git a/docs/user_guide/source/engines/engines.rst b/docs/user_guide/source/engines/engines.rst index 802ca2683e..065e58beb5 100644 --- a/docs/user_guide/source/engines/engines.rst +++ b/docs/user_guide/source/engines/engines.rst @@ -25,4 +25,5 @@ Parameters are passed at: .. include:: inline.rst .. include:: insitu_mpi.rst .. include:: null.rst +.. include:: plugin.rst .. include:: virtual_engines.rst diff --git a/docs/user_guide/source/engines/plugin.rst b/docs/user_guide/source/engines/plugin.rst new file mode 100644 index 0000000000..28815f2f26 --- /dev/null +++ b/docs/user_guide/source/engines/plugin.rst @@ -0,0 +1,97 @@ +************* +Plugin Engine +************* + +The ``Plugin`` engine enables the ability to load an engine located in a separate library. +Your plugin class needs to inherit from the ``PluginEngineInterface`` class in the ``adios2/engine/plugin/PluginEngineInterface.h`` header. +Depending on the type of engine you want to implement, you'll need to override a number of methods that are inherited from the ``adios2::core::Engine`` class. +These are briefly described in the following table. +More detailed documentation can be found in ``adios2/core/Engine.h``. + +========================= ===================== =========================================================== + **Method** **Engine Type** **Description** +========================= ===================== =========================================================== +``BeginStep()`` Read/Write Indicates the beginning of a step +``EndStep()`` Read/Write Indicates the end of a step +``CurrentStep()`` Read/Write Returns current step info +``DoClose()`` Read/Write Close a particular transport +``Init()`` Read/Write Engine initialization +``InitParameters()`` Read/Write Initialize parameters +``InitTransports()`` Read/Write Initialize transports +``PerformPuts()`` Write Execute all deferred mode ``Put`` +``Flush()`` Write Flushes data and metadata to a transport +``DoPut()`` Write Implementation for ``Put`` +``DoPutSync()`` Write Implementation for ``Put`` (Sync mode) +``DoPutDeferred()`` Write Implementation for ``Put`` (Deferred Mode) +``PerformGets()`` Read Execute all deferred mode ``Get`` +``DoGetSync()`` Read Implementation for ``Get`` (Sync mode) +``DoGetDeferred()`` Read Implementation for ``Get`` (Deferred Mode) +========================= ===================== =========================================================== + +Examples showing how to implement an engine plugin can be found in ``examples/plugins/engine``. +An example write engine is ``ExampleWritePlugin.h``, while an example read engine is in ``ExampleReadPlugin.h``. +The writer is a simple file writing engine that creates a directory (called ``ExamplePlugin`` by default) and writes variable information to vars.txt and actual data to data.txt. +The reader example reads the files output by the writer example. + +In addition to implementing the methods above, you'll need to implement ``EngineCreate()`` and ``EngineDestroy`` functions so the Plugin Engine can create/destroy the engine object. +Because of C++ name mangling, you'll need to use ``extern "C"``. +Looking at ``ExampleWritePlugin.h``, this looks like: + +.. code-block:: c++ + + extern "C" { + + adios2::core::engine::ExampleWritePlugin * + EngineCreate(adios2::core::IO &io, const std::string &name, + const adios2::Mode mode, adios2::helper::Comm comm) + { + return new adios2::core::engine::ExampleWritePlugin(io, name, mode, + comm.Duplicate()); + } + + void EngineDestroy(adios2::core::engine::ExampleWritePlugin * obj) + { + delete obj; + } + + } + +To build your plugin, your CMake should look something like: + +.. code-block:: cmake + + find_package(ADIOS2 REQUIRED) + set(BUILD_SHARED_LIBS ON) + add_library(PluginEngineWrite + ExampleWritePlugin.cpp + ) + target_link_libraries(PluginEngineWrite adios2::cxx11 adios2::core) + +When using the Plugin Engine, ADIOS will check for your plugin at the path specified in the ``ADIOS2_PLUGIN_PATH`` environment variable. +If ``ADIOS2_PLUGIN_PATH`` is not set, ADIOS will warn you about it, and then look for your plugin in the current working directory. + +The following steps show how to use your engine plugin in your application. +``examplePluginEngine_write.cpp`` and ``examplePluginEngine_read.cpp`` are an example of how to use the engine plugins described above. +The key steps to use your plugin are: + +1. Set engine to ``Plugin``. i.e.: + +.. code-block:: c++ + + io.SetEngine("Plugin"); + +2. Set ``PluginName`` (optional) and ``PluginLibrary`` (required) parameters. + If you don't set ``PluginName``, the Plugin Engine will give your plugin a default name of ``UserPlugin``. + In the write example, this looks like + +.. code-block:: c++ + + io.SetParameters({{"PluginName", "WritePlugin"}}); + io.SetParameters({{"PluginLibrary", "PluginEngineWrite"}}); + +.. note:: + You don't need to add the ``lib`` prefix or the shared library ending (e.g., ``.so``, ``.dll``, etc.). + ADIOS will add these when searching for your plugin library. + +At this point you can open the engine and use it as you would any other ADIOS engine. +You also shouldn't need to make any changes to your CMake files for your application.