From 578e45ddc96cd0a53de86b11f4f5ba2c26f47f33 Mon Sep 17 00:00:00 2001
From: Caitlin Ross <caitlin.ross@kitware.com>
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  | 71 ++++++++++++++++++++++
 3 files changed, 73 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..80827bcc16
--- /dev/null
+++ b/docs/user_guide/source/engines/plugin.rst
@@ -0,0 +1,71 @@
+*************
+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 use the plugin engine 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.
+
+
+``examplePluginEngine_write.cpp`` and ``examplePluginEngine_read.cpp`` show how to use your engine plugins in your application.
+The key steps to use your plugin are:
+
+1. Call ``adios2::core::engine::PluginEngine::RegisterPlugin()``. For the write example, this looks like
+
+.. code-block:: c++
+
+   adios2::core::engine::PluginEngine::RegisterPlugin<
+       adios2::core::engine::ExampleWritePlugin>("MyPlugin")
+
+2. Set engine to ``Plugin``. i.e.:
+
+.. code-block:: c++
+
+   io.SetEngine("Plugin");
+
+3. Set ``PluginName`` parameter to the name you provided in the ``RegisterPlugin`` call. In the write example, this looks like
+
+.. code-block:: c++
+
+   io.SetParameters({{"PluginName", "MyPlugin"}});
+
+At this point you can open the engine and use it as you would any other ADIOS engine.
+
+In your CMakeLists.txt for your application, you'll now need to link to the ``adios2::core`` library.
+For example:
+
+.. code-block:: cmake
+
+    find_package(ADIOS2 REQUIRED)
+    add_executable(myApp
+      myApp.cpp
+      MyWritePlugin.cpp
+    )
+    target_link_libraries(myApp adios2::cxx11 adios2::core)