Apply suggestions from code review

Co-authored-by: Axel Huebl <[email protected]>

docs/source/usage/examples.rst

@@ -20,6 +20,7 @@ C++
 - `5_write_parallel.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/5_write_parallel.cpp>`_: MPI-parallel mesh write
 - `6_dump_filebased_series.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/6_dump_filebased_series.cpp>`_: detailed reading with a file-based series
 - `7_extended_write_serial.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/7_extended_write_serial.cpp>`_: particle writing with patches and constant records
+- `12_span_write.cpp <https://github.com/openPMD/openPMD-api/blob/dev/examples/12_span_write.cpp>`_: using the span-based API to save memory when writing
 
 Benchmarks
 ^^^^^^^^^^
@@ -39,6 +40,7 @@ Python
 - `5_write_parallel.py <https://github.com/openPMD/openPMD-api/blob/dev/examples/5_write_parallel.py>`_: MPI-parallel mesh write
 - `7_extended_write_serial.py <https://github.com/openPMD/openPMD-api/blob/dev/examples/7_extended_write_serial.py>`_: particle writing with patches and constant records
 - `9_particle_write_serial.py <https://github.com/openPMD/openPMD-api/blob/dev/examples/9_particle_write_serial.py>`_: writing particles
+- `12_span_write.py <https://github.com/openPMD/openPMD-api/blob/dev/examples/12_span_write.py>`_: using the span-based API to save memory when writing
 
 Unit Tests
 ----------

docs/source/usage/workflow.rst

@@ -22,9 +22,10 @@ Flush points are triggered by:
 *   Calling ``Series::flush()``.
 *   Calling ``Iteration::flush( flush=true )``.
     Flush point guarantees affect only the corresponding iteration.
+*   Calling ``Writable::seriesFlush()`` or ``Attributable::seriesFlush()``.
 *   The streaming API (i.e. ``Series.readIterations()`` and ``Series.writeIteration()``) automatically before accessing the next iteration.
 
 Attributes are (currently) unaffected by this:
 
-*   In writing, attributes are stored by value and can afterwards not be aliased by the user (i.e. they are stored internally in the openPMD API and are not accessible to users).
-*   In reading, attributes are parsed upon opening the Series / an iteration and are available to read right-away without performing any IO.
+*   In writing, attributes are stored internally by value and can afterwards not be accessed by the user.
+*   In reading, attributes are parsed upon opening the Series / an iteration and are available to read right-away.

examples/12_span_write.py

@@ -7,11 +7,11 @@ def span_write(filename):
 
     datatype = np.dtype("double")
     length = 10
-    extent = [10]
+    extent = [length]
     dataset = io.Dataset(datatype, extent)
 
     iterations = series.write_iterations()
-    for i in range(10):
+    for i in range(12):
         iteration = iterations[i]
         electronPositions = iteration.particles["e"]["position"]
 

include/openPMD/IO/ADIOS/ADIOS2IOHandler.hpp

@@ -1065,11 +1065,44 @@ namespace detail
         std::string const m_IOName;
         adios2::ADIOS & m_ADIOS;
         adios2::IO m_IO;
+        /**
+         * The default queue for deferred actions.
+         * Drained upon ::flush().
+         */
         std::vector< std::unique_ptr< BufferedAction > > m_buffer;
+        /**
+         * Buffer for attributes to be written in the new (variable-based)
+         * attribute layout.
+         * Reason: If writing one variable twice within the same ADIOS step,
+         * it is undefined which value ADIOS2 will store.
+         * We want the last write operation to succeed, so this map stores
+         * attribute writes by attribute name, allowing us to override older
+         * write commands.
+         * The queue is drained only when closing a step / the engine.
+         */
         std::map< std::string, BufferedAttributeWrite > m_attributeWrites;
+        /**
+         * @todo This one is unnecessary, in the new schema, attribute reads do
+         * not need to be deferred, but can happen instantly without performance
+         * penalty, once preloadAttributes has been filled.
+         */
         std::vector< BufferedAttributeRead > m_attributeReads;
+        /**
+         * This contains deferred actions that have already been enqueued into
+         * ADIOS2, but not yet performed in ADIOS2.
+         * We must store them somewhere until the next PerformPuts/Gets, EndStep
+         * or Close in ADIOS2 to avoid use after free conditions.
+         */
         std::vector< std::unique_ptr< BufferedAction > > m_alreadyEnqueued;
         adios2::Mode m_mode;
+        /**
+         * The base pointer of an ADIOS2 span might change after reallocations.
+         * The frontend will ask the backend for those updated base pointers.
+         * Spans given out by the ADIOS2 backend to the frontend are hence
+         * identified by an unsigned integer and stored in this member for later
+         * retrieval of the updated base pointer.
+         * This map is cleared upon flush points.
+         */
         std::map< unsigned, std::unique_ptr< I_UpdateSpan > > m_updateSpans;
         detail::WriteDataset const m_writeDataset;
         detail::DatasetReader const m_readDataset;

include/openPMD/RecordComponent.hpp

@@ -1,4 +1,4 @@
-/* Copyright 2017-2021 Fabian Koller
+/* Copyright 2017-2021 Fabian Koller, Axel Huebl and Franz Poeschel
  *
  * This file is part of openPMD-api.
  *

include/openPMD/RecordComponent.tpp

@@ -1,4 +1,4 @@
-/* Copyright 2017-2021 Fabian Koller and Franz Poeschel
+/* Copyright 2017-2021 Fabian Koller, Axel Huebl and Franz Poeschel
  *
  * This file is part of openPMD-api.
  *

include/openPMD/Span.hpp

@@ -87,7 +87,7 @@ class Span
 
 /**
  * @brief A view into a buffer that might be reallocated at some points and
- *      have changing base pointers over time.
+ *      thus has changing base pointers over time.
  *      Reasoning: ADIOS2's span-based Engine::Put() API returns spans whose
  *      base pointers might change after internal reallocations.
  *      Hence, the concrete pointer needs to be acquired right before writing