Skip to content

Commit

Permalink
plugin engine: user guide docs
Browse files Browse the repository at this point in the history
  • Loading branch information
caitlinross authored and Chuck Atkins committed Sep 7, 2021
1 parent db627c5 commit 578e45d
Show file tree
Hide file tree
Showing 3 changed files with 73 additions and 0 deletions.
1 change: 1 addition & 0 deletions docs/user_guide/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,7 @@
'engines/sst.rst',
'engines/inline.rst',
'engines/null.rst',
'engines/plugin.rst',
# 'engines/engines.rst',
# 'faq/faq.rst',
]
Expand Down
1 change: 1 addition & 0 deletions docs/user_guide/source/engines/engines.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
71 changes: 71 additions & 0 deletions docs/user_guide/source/engines/plugin.rst
Original file line number Diff line number Diff line change
@@ -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)

0 comments on commit 578e45d

Please sign in to comment.