MORI-IO nixl-style cpp bench script

[amirakb89]

bench(io): nixlbench-matching C++ engine benchmark

Adds tests/cpp/io/bench_engine.cpp, a native C++ MORI-IO transfer benchmark
whose measurement loop matches nixlbench
(NVIDIA NIXL's xferbench), so MORI-IO and NIXL RDMA numbers are directly
comparable on the same fabric with no Python-interpreter overhead in the way.

Applies directly to main. The only files touched are the new benchmark, its
CMake target, and docs/MORI-IO-BENCHMARK.md; no existing source is modified,
and the Python benchmark is untouched.

What "nixl-matching" means here

• One whole-loop timer around the entire iteration loop (nixlbench's
  total_timer), not the per-iteration time.time() sum the Python bench uses,
  which silently drops the inter-iteration gap.
• Latency per single transfer: total_us / (iters x batch), matching nixl's
  avg_latency = total_duration / (per_thread_iter x batch_size).
• Bandwidth msg x batch x iters / 1e9 / (total_us / 1e6) — GB = 10^9, as in
  nixl.
• Inline spin-poll completion in the benchmark thread, mirroring nixl's
  getXferStatus scan, so no condition-variable wakeup latency lands in the
  measurement.
• Strict stop-and-wait: one request outstanding at a time, equivalent to
  nixl --pipeline_depth 1.
• Warmup excluded, and memory registered once during setup — the buffer
  is sized to the largest request in the whole sweep and reused across every
  size point, so no allocation or registration happens inside the timed loop.

Also included

• --backend rdma|xgmi, so the same harness covers intra-node GPU-to-GPU
  transfers, sized by --num-streams / --num-events.
• Built-in correctness check after the sweep, matching the Python benchmark,
  which always validates. Both ranks seed a rank- and offset-dependent pattern
  and exchange one FNV-1a checksum per transferred slot, so the check covers
  every transferred byte while staying O(batch) on the wire. --skip-validate
  opts out and is safe to pass on a single rank, since the exchange is a
  collective and an opted-out rank contributes an empty vector rather than
  returning early.
• Rendezvous over mori::application::SocketBootstrapNetwork rather than a
  second hand-rolled socket setup, so connect/accept retries, timeouts and
  barriers follow the library's policy.
• Python-parity flags so runs can be matched arg-for-arg against
  tests/python/io/benchmark.py: size and batch sweeps (--all, --all-batch,
  --buffer-size, --sweep-start/--sweep-max/--sweep-step),
  --enable-batch-transfer / --disable-batch-transfer, chunking, session
  fast path, per-side memory type, --target-dev-offset, and the QP tuning
  knobs.
• The buffer and its memory registration are owned by a scope guard and failures
  throw rather than calling std::exit(), so the MR is dropped before the pages
  it covers are released on every exit path.
• Unusable arguments are rejected up front instead of being read out of bounds,
  looped on forever or reported as a NaN, and -h/--help prints a grouped flag
  list.

Results

Broadcom Thor2 bnxt_re RoCE, 2 nodes, gfx950. VRAM->VRAM WRITE, 1 QP / 1
worker thread, chunking off, --batch-contiguous, session enabled. Bandwidth
in GB/s. Single run per point — small deltas are directional.

Harness	1 MiB x 1	4 KiB x 128	512 B x 128
Python benchmark.py	22.59	14.79	2.60
C++ bench_engine	24.64	16.46	2.98

The C++ tool reads +9.1% / +11.3% / +14.6% higher, and the gap widening as
messages shrink is what the methodology difference predicts: at 1 MiB the
transfer dominates, while at 512 B each iteration is mostly harness, so the
whole-loop timer, the absent interpreter overhead and the spin-poll instead of a
condition-variable wakeup all take a larger share. These are measurement
differences, not a claim that the transport got faster.

All C++ runs above passed the built-in validation.

Reproduce

cmake -B build -DBUILD_IO=ON -DBUILD_TESTS=ON -DBUILD_EXAMPLES=OFF
cmake --build build --target bench_engine -j
export LD_LIBRARY_PATH=$PWD/build/src/io:$PWD/build/src/application:$LD_LIBRARY_PATH

Start rank 1 (target) first, then rank 0, which drives the transfers and
prints the table. Both ranks take the same workload arguments:

# TARGET (rank 1) — first
build/tests/cpp/bench_engine --rank 1 --master-ip <RANK0_IP> --self-ip <RANK1_IP> \
    --port 18527 --mem-type gpu --op write --enable-sess \
    --num-qp-per-transfer 1 --num-worker-threads 1 --transfer-batch-size 1 \
    --all --sweep-start 1048576 --sweep-max 1048576 --iters 500 --warmup-iters 50

# INITIATOR (rank 0) — second, prints results
build/tests/cpp/bench_engine --rank 0 --master-ip <RANK0_IP> --self-ip <RANK0_IP> \
    --port 18527 --mem-type gpu --op write --enable-sess \
    --num-qp-per-transfer 1 --num-worker-threads 1 --transfer-batch-size 1 \
    --all --sweep-start 1048576 --sweep-max 1048576 --iters 500 --warmup-iters 50

bench_engine --help lists every flag, and docs/MORI-IO-BENCHMARK.md has the
full walkthrough plus the Python-to-C++ flag mapping.

Test plan

• Builds and links against libmori_io + libmori_application
  (-DBUILD_EXAMPLES=OFF skips the MPI-only examples target).
• 2-node VRAM WRITE run, batch 1 and batched, sane BW and latency, built-in
  validation passing across read and write, contiguous and strided offsets,
  chunking on and off, with a zero-iteration negative control confirming the
  check fails when nothing moves.
• Reviewer sanity-check on a second fabric (CX7/mlx5).

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c755fd822e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Deregister memory before freeing its backing buffer

Both this target exit and the initiator exit free buf while localMem remains registered with the RDMA backend; the initiator may also still have a session referencing it. Once a transfer has caused the region to be registered with a NIC, freeing the HIP allocation first leaves the backend with a registration for invalid storage and defers cleanup until engine destruction, which can cause teardown failures or stale DMA mappings. Destroy the session where applicable and call engine.DeregisterMemory(localMem) before hipHostFree/hipFree on both paths.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Declare or remove the new NumPy dependency

In an environment that previously had the documented benchmark prerequisites but not NumPy, the script now fails at startup on this import before it can parse any arguments. NumPy is not declared in pyproject.toml or requirements-build.txt, so users following the existing installation flow are not guaranteed to have it; add it to the applicable runtime/setup requirements or retain an implementation using the previously supported list inputs.

Useful? React with 👍 / 👎.

[maning00]

Could we reuse MORI's existing networking abstractions instead of introducing another raw-socket rendezvous implementation here?
mori::application::TCPContext and SocketBootstrapNetwork already provide connection lifecycle management, send/receive primitives, barriers, timeouts, and cleanup. This benchmark also links mori_application, so duplicating these responsibilities with raw file descriptors creates a second implementation with different retry, timeout, and error-handling behavior.
Please consider using the existing bootstrap layer, or extracting a small reusable rendezvous helper from it. That would also avoid manual close()/std::exit() paths and make resource ownership explicit.

[maning00]

Before continuing the review, I’d like to request two structural changes:

1. Preserve the existing RDMA path
   The current implementation refactors the regular RdmaBatchReadWrite path to share the new build/post logic. At this stage, prepared transfers should remain opt-in and isolated from the existing path, without adding overhead to normal Read/Write/BatchReadWrite calls.
   The existing RdmaBatchReadWrite implementation should therefore remain unchanged, while the prepared API should use a separate build/post path invoked only by --prepare-once. Only after prepared transfers have been thoroughly validated and shown not to regress the existing RDMA path should we consider refactoring the regular path to share this implementation.

2. Split this PR into two focused PRs

   • Baseline C++ benchmark: benchmark executable, CMake integration, rendezvous, XGMI support, validation, and documentation, without prepared-transfer or RDMA core changes.
   • Prepared transfers: prepared-transfer API and implementation, dedicated tests, --prepare-once benchmark integration, and benchmark results. This implementation should remain isolated from the existing RDMA path.

Please also rebase after #444 is merged so its commits are not duplicated, and reorganize the commit history around the final logical changes. This will make the performance-sensitive core changes easier to review and verify independently.