BP5: thread-safe context-bearing Get/PerformGets pipeline

NewGetContext returns a per-caller GetContext; Get(ctx, var, data, sel)
and PerformGets(ctx) operate on independent queues, so concurrent reads
on one engine no longer race.  NewGetContext returns nullptr unless the
engine is ReadRandomAccess on a reentrant Read transport (POSIX) — the
default acts as a feature probe.

Core:
  * core::GetContext polymorphic base.
  * Engine::NewGetContext (virtual, nullptr default), PerformGets(ctx),
    Get(ctx, ...) template, DoGetContextDeferred typeless virtual.
  * Same surface exposed through the CXX binding.

BP5:
  * BP5GetContext (nested in BP5Deserializer) owns what was
    BP5Deserializer::PendingGetRequests.
  * QueueGet, GenerateReadRequests, FinalizeGet/Gets/DerivedGets gain
    ctx-bearing forms; legacy forms forward via m_DefaultGetContext.
  * BP5Reader overrides NewGetContext (guarded on ReadRandomAccess +
    cached m_HasReentrantReadTransport), PerformGets(ctx) (local only —
    remote throws), DoGetContextDeferred.

XRootD plugin:
  * SubPool dual mode: first Open probes NewGetContext; if non-null,
    one engine is shared across concurrent users (in_use_count =
    refcount); otherwise legacy per-user exclusive borrow.
  * Single-get and batch handlers build per-request Selection inline
    (no Variable mutation) and use the ctx form when supported, with
    a single PerformGets(ctx) per batch for coalescing.

Tests (testing/adios2/engine/bp/TestBPGetContextIsolation):
  * TwoIndependentContexts: PerformGets(ctxA) fills only ctxA, leaves
    ctxB at sentinel; context reusable; empty-queue PerformGets no-op.
  * ConcurrentGetsOnSameEngine: TSan-validated.
  * NonReentrantTransportRejected: fstream transport => NewGetContext
    returns nullptr.

Author: eisenhauer

bindings/CXX/adios2/cxx/Engine.cpp

@@ -89,6 +89,18 @@ void Engine::PerformGets()
     m_Engine->PerformGets();
 }
 
+std::unique_ptr<core::GetContext> Engine::NewGetContext()
+{
+    helper::CheckForNullptr(m_Engine, "in call to Engine::NewGetContext");
+    return m_Engine->NewGetContext();
+}
+
+void Engine::PerformGets(core::GetContext &ctx)
+{
+    helper::CheckForNullptr(m_Engine, "in call to Engine::PerformGets(GetContext&)");
+    m_Engine->PerformGets(ctx);
+}
+
 void Engine::LockWriterDefinitions()
 {
     helper::CheckForNullptr(m_Engine, "in call to Engine::LockWriterDefinitions");
@@ -334,6 +346,7 @@ Engine::AllStepsBlocksInfo(const VariableNT &variable) const
     template void Engine::Get<T>(const std::string &, std::vector<T> &, const Mode);               \
                                                                                                    \
     template void Engine::Get<T>(Variable<T>, T *, const Selection &, const Mode);                 \
+    template void Engine::Get<T>(core::GetContext &, Variable<T>, T *, const Selection &);         \
     template void Engine::Get<T>(Variable<T>, std::vector<T> &, const Selection &, const Mode);    \
                                                                                                    \
     template void Engine::Get<T>(Variable<T>, typename Variable<T>::Info & info, const Mode);      \

bindings/CXX/adios2/cxx/Engine.h

@@ -26,6 +26,7 @@ class Selection; // for selection-based Get()
 namespace core
 {
 class Engine; // private implementation
+class GetContext;
 
 }
 /// \endcond
@@ -448,6 +449,15 @@ class Engine
     /** Perform all Get calls in Deferred mode up to this point */
     void PerformGets();
 
+    // Context-bearing Get / PerformGets — thread-safe pipeline (BP5 reader only).
+    // Returns nullptr if the engine doesn't support concurrent contexts.
+    std::unique_ptr<core::GetContext> NewGetContext();
+
+    template <class T>
+    void Get(core::GetContext &ctx, Variable<T> variable, T *data, const Selection &selection);
+
+    void PerformGets(core::GetContext &ctx);
+
     /**
      * Ends current step, by default calls PerformsPut/Get internally
      * For most engines, this is an MPI collective function.

bindings/CXX/adios2/cxx/Engine.tcc

@@ -305,6 +305,17 @@ void Engine::Get(Variable<T> variable, std::vector<T> &dataV, const Selection &s
                   selection.GetCoreSelection(), launch);
 }
 
+template <class T>
+void Engine::Get(core::GetContext &ctx, Variable<T> variable, T *data, const Selection &selection)
+{
+    using IOType = typename TypeInfo<T>::IOType;
+    adios2::helper::CheckForNullptr(m_Engine, "in call to Engine::Get(GetContext &, ...)");
+    adios2::helper::CheckForNullptr(variable.m_Variable,
+                                    "for variable in call to Engine::Get(GetContext &, ...)");
+    m_Engine->Get(ctx, *variable.m_Variable, reinterpret_cast<IOType *>(data),
+                  selection.GetCoreSelection());
+}
+
 } // end namespace adios2
 
 #endif /* ADIOS2_BINDINGS_CXX_CXX_ENGINE_TCC_ */

docs/user_guide/source/components/engine.rst

@@ -472,6 +472,11 @@ PerformGets
 
    Executes all pending ``Get`` calls in deferred mode.
 
+   A second overload, ``PerformGets(GetContext&)``, drains only the requests
+   queued on the supplied context, supporting concurrent ``Get`` pipelines on
+   a single engine. See `Thread-Safe Concurrent Reads with GetContext`_ in
+   the Selection chapter.
+
 
 Engine usage example
 --------------------

docs/user_guide/source/components/selection.rst

@@ -183,6 +183,46 @@ Selection-based ``Get()`` is currently supported by the **BP5** and **SST**
 (with BP5 marshalling) engines. Other engines will throw a runtime error if a
 ``Selection`` is passed to ``Get()``.
 
+Thread-Safe Concurrent Reads with GetContext
+--------------------------------------------
+
+The Selection-based ``Get()`` shown above shares per-engine queue state with
+every other ``Get()`` call on the same engine, so concurrent calls from
+multiple threads are not safe. A second overload takes an explicit
+``GetContext`` so each thread (or each independent reader) can queue and drain
+``Get()`` requests on its own:
+
+.. code-block:: c++
+
+   auto ctx = engine.NewGetContext();
+   if (!ctx) {
+       // Engine does not support concurrent contexts; fall back to the
+       // single-threaded Selection-based Get above.
+   }
+
+   auto sel = adios2::Selection::BoundingBox({0, 0}, {10, 20}).WithSteps(0, 1);
+   engine.Get(*ctx, var, data, sel);
+   engine.PerformGets(*ctx);
+
+Each ``GetContext`` owns its own queue of pending requests, so
+``PerformGets(ctxA)`` drains only ``ctxA`` and leaves any requests queued on
+``ctxB`` untouched. A context is reusable after ``PerformGets``; the queue is
+cleared on the success path. Calls in ctx-form are always deferred — there is
+no ``Mode::Sync`` variant.
+
+``NewGetContext()`` is a feature probe: it returns ``nullptr`` if the engine
+does not support concurrent contexts. Currently only the **BP5** reader
+supports them, and only when:
+
+- the engine was opened in ``Mode::ReadRandomAccess`` (no step lifecycle to
+  race on), and
+- the underlying file transport is reentrant for ``Read`` (the POSIX
+  transport is; ``fstream`` and others are not).
+
+The legacy ``Selection``-less ``Get()``/``PerformGets()`` API and the
+single-threaded Selection-based ``Get()`` are unchanged; the ctx-form is an
+additional API for callers that need concurrency.
+
 Compatibility
 -------------
 

docs/user_guide/source/introduction/whatsnew.rst

@@ -2,6 +2,30 @@
 What's new in Development
 ==============================
 
+Thread-Safe Get with GetContext
+-------------------------------
+
+A new ``GetContext`` API extends the Selection-based ``Get()`` to support
+concurrent read pipelines on a single engine. Each caller allocates its own
+``GetContext`` via ``Engine::NewGetContext()`` and uses it as the first
+argument to ``Get()`` and ``PerformGets()``; per-context queues mean two
+threads can drive independent ``Get`` batches against the same open engine
+without racing.
+
+.. code-block:: c++
+
+   auto ctx = engine.NewGetContext();
+   if (ctx) {
+       engine.Get(*ctx, var, data, adios2::Selection::BoundingBox(start, count));
+       engine.PerformGets(*ctx);
+   }
+
+``NewGetContext()`` returns ``nullptr`` when the engine does not support
+concurrent contexts; callers feature-probe with the null check. Currently
+only the **BP5** reader supports them, and only when opened in
+``Mode::ReadRandomAccess`` with a reentrant file transport (POSIX). See the
+Selection chapter for full details.
+
 SST Mercury Data Plane
 -----------------------
 

source/adios2/core/Engine.cpp

@@ -83,6 +83,14 @@ void Engine::PerformPuts() { ThrowUp("PerformPuts"); }
 void Engine::PerformGets() { ThrowUp("PerformGets"); }
 void Engine::PerformDataWrite() { return; }
 
+// Feature probe: null => engine doesn't support the ctx-form pipeline.
+std::unique_ptr<GetContext> Engine::NewGetContext() { return nullptr; }
+void Engine::PerformGets(GetContext &) { ThrowUp("PerformGets(GetContext&)"); }
+void Engine::DoGetContextDeferred(GetContext &, VariableBase &, void *, const Selection &)
+{
+    ThrowUp("DoGetContextDeferred");
+}
+
 void Engine::Close(const int transportIndex)
 {
     if (m_IsOpen)
@@ -375,6 +383,8 @@ std::vector<VariableStruct::BPInfo> Engine::BlocksInfoStruct(const VariableStruc
     template void Engine::Get<T>(Variable<T> &, T *, const Selection &, const Mode);               \
     template void Engine::Get<T>(Variable<T> &, std::vector<T> &, const Selection &, const Mode);  \
                                                                                                    \
+    template void Engine::Get<T>(GetContext &, Variable<T> &, T *, const Selection &);             \
+                                                                                                   \
     template typename Variable<T>::BPInfo *Engine::Get<T>(Variable<T> &, const Mode);              \
     template typename Variable<T>::BPInfo *Engine::Get<T>(const std::string &, const Mode);        \
                                                                                                    \

source/adios2/core/Engine.h

@@ -23,6 +23,7 @@
 #include "adios2/common/ADIOSMacros.h"
 #include "adios2/common/ADIOSTypes.h"
 #include "adios2/common/Selection.h"
+#include "adios2/core/GetContext.h"
 #include "adios2/core/IO.h"
 #include "adios2/core/Variable.h"
 #include "adios2/core/VariableStruct.h"
@@ -387,6 +388,15 @@ class Engine
     void Get(Variable<T> &variable, std::vector<T> &dataV, const Selection &selection,
              const Mode launch = Mode::Deferred);
 
+    // Context-bearing thread-safe Get pipeline (BP5 only).
+    // NewGetContext returns nullptr if the engine doesn't support it.
+    virtual std::unique_ptr<GetContext> NewGetContext();
+
+    template <class T>
+    void Get(GetContext &ctx, Variable<T> &variable, T *data, const Selection &selection);
+
+    virtual void PerformGets(GetContext &ctx);
+
     /**
      * Reader application indicates that no more data will be read from the
      * current stream before advancing.
@@ -610,6 +620,8 @@ class Engine
     ADIOS2_FOREACH_STDTYPE_1ARG(declare_type)
 #undef declare_type
 
+    virtual void DoGetContextDeferred(GetContext &, VariableBase &, void *, const Selection &);
+
     virtual void DoGetStructSync(VariableStruct &, void *);
     virtual void DoGetStructDeferred(VariableStruct &, void *);
 

source/adios2/core/Engine.tcc

@@ -179,6 +179,14 @@ void Engine::Get(Variable<T> &variable, T *data, const Selection &selection, con
     }
 }
 
+template <class T>
+void Engine::Get(GetContext &ctx, Variable<T> &variable, T *data, const Selection &selection)
+{
+    CommonChecks(variable, data, {Mode::Read, Mode::ReadRandomAccess},
+                 "in call to Get(GetContext &, Variable, T*, Selection)");
+    DoGetContextDeferred(ctx, variable, data, selection);
+}
+
 template <class T>
 void Engine::Get(Variable<T> &variable, std::vector<T> &dataV, const Selection &selection,
                  const Mode launch)

source/adios2/core/GetContext.h

@@ -0,0 +1,25 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Oak Ridge National Laboratory and Contributors
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ADIOS2_CORE_GETCONTEXT_H_
+#define ADIOS2_CORE_GETCONTEXT_H_
+
+namespace adios2
+{
+namespace core
+{
+
+// Opaque per-caller state for thread-safe Get/PerformGets.
+class GetContext
+{
+public:
+    virtual ~GetContext() = default;
+};
+
+} // end namespace core
+} // end namespace adios2
+
+#endif /* ADIOS2_CORE_GETCONTEXT_H_ */