Merge pull request #3227 from eisenhauer/UnnecessaryPerformPuts

Second, BP5 can add a large user variable as a chunk to this list without copying it at all and use it directly to write (or send to aggregator). `Put(..., adios2::Mode::Deferred)` will handle the user data directly, unless its size is below a threshold (see parameter **MinDeferredSize**). 

.. note::

    Do not call `PerformPuts()` when using BP5, because this call forces copying all user data into the internal buffer before writing, eliminating all benefits of zero-copy that BP5 provides. 

    Do not call `PerformPuts()` when using BP5, because this call forces copying all user data into the internal buffer before writing, eliminating all benefits of zero-copy that BP5 provides when operating with large buffers.  Instead, consider using Put() with the Sync option if you want to force ADIOS to copy data immediately.  Alternatively, BP5 offers PerformDataWrite(), an collective operation that actually moves data to storage, potentially freeing up buffer and application memory.

Third, BP5 is using a shared memory segment on each compute node for aggregation, instead of MPI. The best settings for the shared memory is 4GB (see parameter **MaxShmSize**), enough place for two chunks with the POSIX write limit. More is useless but can be smaller if a system/application cannot allow this much space for aggregation (but there will be more write calls to disk as a result).

15. ``Put Span``: create all spans in a step before populating them. Spans follow the same iterator invalidation rules as ``std::vector``, so use ``span.data()`` to always keep the span pointer up-to-date 

16. Always populate data before calling ``Put`` in deferred mode,

    and do not change it between ``Put`` and ``PerformPuts``, ``EndStep``, or ``Close``

    and do not change it between ``Put`` and ``EndStep``, or ``Close``

17. Use ``BeginStep`` and ``EndStep`` to write code that is portable

17. Never call ``PerformPuts`` right before ``EndStep``.  This was a

    code pattern that had no adverse effects with the BP3/4 file

    engines and is present in some older code, but was never

    beneficial.

18. Use ``BeginStep`` and ``EndStep`` to write code that is portable

    across all ADIOS 2 Engine types: file and streaming.

18. Always use ``Close`` for every call to ``Open``.

19. Always use ``Close`` for every call to ``Open``.

19. C, Fortran: always call ``adios2_finalize`` for every call to ``adios2_init`` to avoid memory leaks.

20. C, Fortran: always call ``adios2_finalize`` for every call to ``adios2_init`` to avoid memory leaks.

20. Reminder: C++, C, Python: Row-Major, while Fortran: Column-Major. ADIOS 2 will handle interoperability between ordering. Remember that :ref:`bpls : Inspecting Data` is always a Row-Major reader so Fortran reader need to swap dimensions seen in bpls.  bpls: (slow, ...., fast) -> Fortran(fast,...,slow).

21. Reminder: C++, C, Python: Row-Major, while Fortran: Column-Major. ADIOS 2 will handle interoperability between ordering. Remember that :ref:`bpls : Inspecting Data` is always a Row-Major reader so Fortran reader need to swap dimensions seen in bpls.  bpls: (slow, ...., fast) -> Fortran(fast,...,slow).

21. Fortran API: use the type members (``var%valid``, ``var%name``, etc.) to get extra type information.

22. Fortran API: use the type members (``var%valid``, ``var%name``, etc.) to get extra type information.

22. Fortran C interoperability: Fortran bindings support the majority of applications using Fortran 90. We currently don't support the ``ISO_C_BINDING`` interoperability module in Fortran 2003. 

23. Fortran C interoperability: Fortran bindings support the majority of applications using Fortran 90. We currently don't support the ``ISO_C_BINDING`` interoperability module in Fortran 2003. 

23. Always keep the ``IO`` object self-contained keeping its own set of ``Variables``, ``Attributes`` and ``Engines``. Do not combine Variables with multiple Engines or multiple modes, unless it's 100% guaranteed to be safe in your program avoiding Variable access conflicts.

24. Always keep the ``IO`` object self-contained keeping its own set of ``Variables``, ``Attributes`` and ``Engines``. Do not combine Variables with multiple Engines or multiple modes, unless it's 100% guaranteed to be safe in your program avoiding Variable access conflicts.

24. Developers: explore the testing infrastructure ``ADIOS2/testing`` in ADIOS 2 as a starting point for using ADIOS 2 in your own testing environment. 

25. Developers: explore the testing infrastructure ``ADIOS2/testing`` in ADIOS 2 as a starting point for using ADIOS 2 in your own testing environment. 

25. Become a super-user of :ref:`bpls : Inspecting Data` to analyze datasets generated by ADIOS 2.

26. Become a super-user of :ref:`bpls : Inspecting Data` to analyze datasets generated by ADIOS 2.

        /** Put variables for buffering, template type is optional */

        bpFileWriter.Put<float>(bpFloats, myFloats.data());

        bpFileWriter.Put(bpInts, myInts.data());

        bpFileWriter.PerformPuts();

        /** Create bp file, engine becomes unreachable after this*/

        bpFileWriter.Close();

        else

        {

            writer.Put<float>(var, myFloats.data());

            writer.PerformPuts();

        }

        /** Engine becomes unreachable after this*/

        adios2::Engine writer = io.Open("testOperator.bp", adios2::Mode::Write);

        writer.Put<double>(var, myDoubles.data());

        writer.PerformPuts();

        /** Engine becomes unreachable after this*/

        writer.Close();