AyCode.Core/AyCode.Benchmark/Workloads/Scenarios/README.md

Workloads / Scenarios

Shared workload + scenario types used by both the Console runner (custom adaptive measure engine) and the BDN runner (AcBinaryVsMemPackBenchmark in the parent folder). Same wire payloads, same options, same round-trip-verify gate → Console and BDN cells are directly comparable.

Layout

Contract types

• ISerializerBenchmark.cs — common contract for every (Engine × IoMode × OptionsPreset) row. Serialize() / Deserialize() hot-path + warmup hooks + VerifyRoundTrip() for the pre-warmup correctness gate. Round-trip-only benchmarks (NamedPipe / in-memory Pipe) set IsRoundTripOnly = true and let the bench loop skip the Des-phase.
• BenchmarkEnums.cs — BenchmarkEngine / BenchmarkIoMode / BenchmarkDispatchMode / BenchmarkLayer / BenchmarkOpMode / SerializerSelectionMode + ToDisplay() extensions for the column-friendly rendering used by every output formatter.
• BenchmarkOptions.cs — per-engine options-formatting helpers + the cached AttrFlags aggregation (assembly-scan of [AcBinarySerializable] feature flags) + GetMemPack(WireMode) for the wire-mode-aligned MemoryPack-options selection.
• RoundTripValidator.cs — universal deep-equality oracle via canonical System.Text.Json. Called by every benchmark's VerifyRoundTrip() before warmup. AOT-skipped (STJ reflection path incompatible).

Concrete benchmarks (12 implementations)

AcBinary (7 variants — different I/O modes):

• AcBinaryBenchmark.cs — Byte[] API. Headline AcBinary row.
• AcBinaryBufferWriterBenchmark.cs — pre-allocated, reused ArrayBufferWriter<byte>.
• AcBinaryFreshBufferWriterBenchmark.cs — fresh ArrayBufferWriter per call (one-shot scenario, 4 KB chunk).
• AcBinaryNamedPipeBenchmark.cs — chunked-framed AsyncPipe over kernel NamedPipe (long-lived, multi-message, 2-task pipeline).
• AcBinaryNamedPipeRawByteArrayBenchmark.cs — raw byte[] over kernel NamedPipe (no chunk-framing, Read+Des sequential after Read completes).
• AcBinaryInMemoryPipeBenchmark.cs — chunked-framed AsyncPipe over in-memory System.IO.Pipelines.Pipe (zero kernel involvement, isolates streaming-framework CPU cost from kernel-pipe transport overhead).
• AcBinaryInMemoryRawByteArrayBenchmark.cs — raw byte[] over in-memory cross-thread handoff (no transport at all, completes the 2×2 [chunked|raw] × [kernel|memory] matrix).

MemoryPack (3 variants — apples-to-apples with the AcBinary I/O modes):

• MemoryPackBenchmark.cs — Byte[] API. SOTA baseline.
• MemoryPackBufferWriterBenchmark.cs — reused ArrayBufferWriter.
• MemoryPackFreshBufferWriterBenchmark.cs — fresh ArrayBufferWriter per call.

Other (reference comparison, typically disabled in active suite):

• MessagePackBenchmark.cs — JIT-only (AOT-incompatible — v3 StandardResolver falls back to Activator.CreateInstance on trimmed closed-generic types).
• SystemTextJsonBenchmark.cs — String I/O mode, reflection-based metadata. Far behind binary serializers on µs/op; useful as a JSON baseline when activated.

Convention

Every concrete benchmark:

1. Stores the test data graph + serializer options in its ctor and pre-computes a _serialized byte array for SerializedSize reporting.
2. Implements Serialize() / Deserialize() as [MethodImpl(NoInlining)] hot-paths — the bench loop drives these directly through warmup + adaptive-iter calibration + measurement.
3. Implements VerifyRoundTrip() by calling RoundTripValidator.DeepEqualsViaJson(original, roundTripped) on the result of a single Ser+Des pass.
4. Round-trip-only variants (NamedPipe / in-memory Pipe) override IsRoundTripOnly => true, route the full Ser+wire+Des roundtrip through Serialize(), and leave Deserialize() as a no-op.

The runner (Console BenchmarkLoop or BDN AcBinaryVsMemPackBenchmark) creates the appropriate concrete via factory helpers and drives the contract — no scenario-specific knowledge in the runner.