From fe330ca279fd64dd5df8bd5f58691fa8c11625e7 Mon Sep 17 00:00:00 2001
From: Evgeny Demchenko <demchenkoev@gmail.com>
Date: Thu, 14 May 2026 23:00:40 +0100
Subject: [PATCH] =?UTF-8?q?arch:=20close=20open=20question=20=C2=A76.6=20?=
 =?UTF-8?q?=E2=80=94=20events=20as=20default=20for=20cross-process=20sync?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

См. spike-v2 (commit ad54305) + arch review 2026-05-15.

cudaStreamSynchronize-only фактически работает на single-host single-GPU
(0 torn в 4 scenarios PoC), но NVIDIA Programming Guide §3.2.8 не даёт
contractual гарантии. Переключаемся на cudaIpcEventHandle_t как default,
stream-sync остаётся опциональным fallback.

Net: +20µs mean latency, -3× max latency (predictable tail), future-proof
для multi-GPU.
---
 docs/architecture.md | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index 87a0c7b..0fb88a1 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -371,9 +371,16 @@ encoding между процессами. cuframes делает это zero-copy
 5. **Multi-GPU.** Producer и consumer на разных CUDA devices — CUDA IPC
    ограничивает same device. В v1 — ограничение, документировать.
 
-6. **Sync semantics.** `cudaStreamSynchronize` гарантирует correctness но
-   serialize'ит producer. CUDA IPC events дают overlap, но complicate API.
-   Default: stream sync. Advanced flag: events.
+6. **Sync semantics.** ✅ **РЕШЕНО** (architectural review 2026-05-15 + spike-v2):
+   Default — **CUDA IPC events** (`cudaIpcEventHandle_t`). Rationale:
+   - NVIDIA Programming Guide §3.2.8 явно требует cross-process sync на стороне
+     application; `cudaStreamSynchronize` producer'а гарантий не даёт contractually.
+   - Spike-v2 measurements (`docs/measurements/spike-v2/`) показали: на нашем
+     single-host single-GPU setup stream-only sync **работает** (0 torn frames
+     на 1500 frames × 4 scenarios), но это **happens-to-work**, не contract.
+   - Events добавляют mean +20µs overhead но дают **predictable tail latency**
+     (max 5.2ms vs 14.7ms для FHD@60fps) и future-proof для multi-GPU.
+   - API option `--sync=stream` оставлен как fallback для legacy / debugging.
 
 7. **Где хостить.** GitHub `<personal-org>/cuframes`. Возможно перенос в
    `frigate-community/cuframes` после adoption.