[LLLL114]

Description

TCP scatter currently creates one completion-tracking task per request, although MultiTransport already supports grouping adjacent requests from the same scatter operation. Large fragmented transfers therefore incur repeated per-task status checks.

Enable TCP's grouped-scatter capability, prepare every request in each grouped task, and accumulate the task's total byte count. Keep the existing TCP transfer sequence and wire protocol. Add tests for fragmented reads and writes, exactly-once callbacks, and preservation of individual fragment results when a peer rejects part of a group.

This is a focused TCP follow-up to #3310, which introduced grouped RDMA tasks while retaining TCP-local sequencing. The change reuses MultiTransport's existing grouping and completion machinery. Store get_into_ranges can benefit when it uses TCP scatter; no Store or KV reshard changes are required by this PR.

Performance

Configuration:

• One Linux host; two Transfer Engine instances in the same process, using real loopback TCP and CPU buffers.
• Release builds with identical options; TCP connection pooling enabled. Store, CUDA, TENT and event-driven completion disabled.
• READ transfers with 128-byte fragments, contiguous source ranges and gaps between destination ranges.
• Public submitScatter() plus wait() timed together; no Store/SGLang path.
• A–B–B–A execution order; one warm-up then seven samples per configuration per run. Values below are medians of 14 samples per version.
• Caller CPU uses CLOCK_THREAD_CPUTIME_ID; process CPU uses CLOCK_PROCESS_CPUTIME_ID and includes both endpoints' I/O threads. CPU time sums thread execution and may exceed wall time.

All times are milliseconds per operation. Each cell shows baseline → patched.

Fragments / payload	Actual scatter tasks	Caller-thread CPU	Process CPU	Wall time
1 / 128 B	1 → 1	0.010 → 0.010	0.037 → 0.036	0.072 → 0.072
4,096 / 512 KiB	4,096 → 1	77.840 → 2.995	178.668 → 105.162	77.903 → 78.800
32,768 / 4 MiB	32,768 → 1	623.128 → 18.926	1,426.123 → 822.338	623.195 → 618.878

For the 4 MiB case, caller-thread CPU fell by 96.96% and process CPU by 42.34%. This is a CPU-overhead reduction, not a claim of a material transfer-latency or throughput improvement.

Module

• Transfer Engine (mooncake-transfer-engine)
• Mooncake Store (mooncake-store)
• Mooncake Conductor (mooncake-conductor)
• Reshard (mooncake-reshard)
• Mooncake EP (mooncake-ep)
• Mooncake PG (mooncake-pg)
• Integration (mooncake-integration)
• P2P Store (mooncake-p2p-store)
• Python Wheel (mooncake-wheel)
• Common (mooncake-common)
• Mooncake RL (mooncake-rl)
• CI/CD
• Docs
• Other

Type of Change

• Bug fix
• New feature
• Refactor
• Breaking change
• Documentation update
• Performance improvement
• Other

How Has This Been Tested?

Test commands:

cmake --build build-tcp-probe \
  --target tcp_write_visibility_test transport_uint_test -j 8

build-tcp-probe/mooncake-transfer-engine/tests/tcp_write_visibility_test

build-tcp-probe/mooncake-transfer-engine/tests/transport_uint_test \
  --gtest_filter='*Batch*:*Scatter*:*Grouped*'

Test results:

• [] Unit tests pass
• Integration tests pass (if applicable)
• Manual testing done (describe below)

Checklist

• I have performed a self-review of my own code
• I have formatted my code using ./scripts/code_format.sh
• I have run pre-commit on the files changed in this PR and all hooks pass
• I have updated the documentation (if applicable)
• I have added tests to prove my changes are effective
• For changes >500 LOC: I have filed an RFC issue

AI Assistance Disclosure

• No AI tools were used
• AI tools were used (specify below)
  Codex assisted with implementation, regression tests, validation and PR preparation. The human submitter reviews the changes.

[Copilot]

🟡 Changes recommended

The tests do not verify that TCP requests are actually submitted as one grouped task, so the performance path could regress unnoticed.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Enables grouped TCP scatter tasks while preserving sequential transfer behavior and per-fragment completion results.

Changes:

• Advertises grouped-scatter support for TCP.
• Prepares all requests in grouped tasks and aggregates byte counts.
• Adds fragmented read/write and partial-failure tests.

File summaries

File	Description
tcp_transport.cpp	Processes every request in grouped TCP tasks.
tcp_transport.h	Enables TCP grouped-scatter capability.
tcp_write_visibility_test.cpp	Tests grouped transfers and fragment failures.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[alogfans]

LGTM