cuframes-docs/site/i18n/ru/docusaurus-plugin-content-docs/current/faq.md

title, sidebar_position

title	sidebar_position
FAQ	99

Частые вопросы

cuframes production-ready?

Честный ответ: ранняя стадия, но проверено в одном реальном развёртывании. v0.4 крутится 24+ часов в CCTV-сетапе (4 IP-камеры → publisher → 2 subscriber'а: NVR-запись + grid-composer → TV) без вмешательства. Это не «проверено в продакшене на масштабе» — это «домашний сетап одного инженера».

Рекомендуем cuframes если:

• Ты строишь свой video pipeline и понимаешь риски OSS-библиотеки на v0.x.
• Твоя команда сможет прочитать исходник если что-то сломается (это ≈ 2k строк C).
• Ты лучше запиннишь известный commit, чем будешь гоняться за semver-обещаниями.

Не рекомендуем cuframes если:

• Нужны контракты vendor support.
• Ты поставляешь клиентам, которые могут в 3 утра завести инцидент на email maintainer'а.
• Не можешь позволить себе писать workaround если фича придёт криво.

Как cuframes сравнить с DeepStream?

	cuframes	NVIDIA DeepStream
Scope	Library (только data plane)	Полный SDK + runtime
Лицензия	LGPL-2.1+	Проприетарный EULA
Footprint	~140 KB .so	Multi-GB runtime
Lock-in	Никакого — pipeline твой	Pipeline = DeepStream-плагины
Cross-process sharing	Native (в этом весь смысл)	Внутри одного процесс-дерева
Поддержка	Best-effort GitHub	Платная enterprise
Кривая обучения	Часы	Недели

cuframes не пытается заменить DeepStream. Решает одну конкретную задачу: «У меня есть один CUDA decoder и несколько процессов, которые хотят decoded frame'ы без re-decode».

Почему не GStreamer?

В GStreamer есть элементы cudaupload / cudadownload, но нет zero-copy cross-process модели — каждый consumer тянет свой pipeline. Можно нахачить с shmsink / shmsrc, но теряется CUDA-residency (frame'ы прыгают через CPU-память). cuframes именно этот roundtrip и избегает.

Почему не DMA-BUF + V4L2?

Это современный kernel-native путь, и он работает cross-vendor. Мы его рассматривали. Почему пошли через CUDA VMM:

• Целевая платформа — NVIDIA-only (существующий CUDA decode pipeline).
• Интеграция DMA-BUF с CUDA требует EGLStream-interop boilerplate — больше кода чем путь VMM + POSIX FD.
• Поддержка драйверами варьируется по возрасту GPU; CUDA VMM стабилен с CUDA 10.2.

Если твой проект cross-vendor — DMA-BUF правильный выбор, и cuframes тебе не подходит.

Можно использовать на Windows?

Нет. Реализация использует POSIX shared memory (shm_open), Unix sockets и передачу file descriptors через SCM_RIGHTS. Порт на Windows потребует:

• Windows-примитивы shared memory (CreateFileMapping).
• Другой механизм шаринга FD (DuplicateHandle через named pipe).
• CUDA VMM WIN32_HANDLE вместо POSIX_FILE_DESCRIPTOR.

В roadmap не стоит. PR'ы приветствуются.

Publisher и consumer могут быть на разных машинах?

Нет. POSIX file descriptors не ходят по сети. Для cross-host шаринга видео нужен другой transport: RTSP, SRT, NDI, или своя реализация через NIC RDMA. cuframes строго same-host.

Что если publisher упадёт пока consumer читает?

Следующий cuframes_subscriber_next() consumer'а вернёт CUFRAMES_ERR_DISCONNECTED. Consumer должен:

1. Вызвать cuframes_subscriber_destroy().
2. Подождать (например, 1–2 секунды back-off).
3. Попытаться cuframes_subscriber_create() снова с тем же key.

FFmpeg demuxer (cuframes://) делает это автоматически — каждые 2 секунды re-subscribe'ится и возвращает EAGAIN в avformat-слой вместо EOF. Смотри libavformat/cuframesdec.c если переписываешь это под другой framework.

Можно несколько publisher'ов на один key?

Нет. Каждый key (/run/cuframes/<key>.sock + /dev/shm/cuframes-<key>) маппится ровно в одного publisher'а. Publisher на create() детектит «уже работает» через shm header + проверку PID liveness и падает с CUFRAMES_ERR_ALREADY_EXISTS.

Для load balancing или HA-сценариев придётся накладывать свою схему именования сверху (например, cam1-primary, cam1-backup, и логика на стороне consumer'а выбирать к кому подписаться).

Сколько subscriber'ов держит publisher?

CUFRAMES_MAX_SUBSCRIBERS = 32 (ограничено bitmap'ом). Поднятие потребует протокольной смены версии, потому что bitmap лежит в SHM header.

На практике мы держим 2–3 subscriber'а на камеру (NVR + AI inference + grid-composer). 32 — с запасом.

Вопросы по лицензии

LGPL-2.1+. cuframes можно использовать в коммерческих закрытых продуктах при условии:

• Динамическая линковка (.so заменяема конечным пользователем).
• Любые модификации самого libcuframes публикуются под LGPL.

Static linking затягивает весь проект под LGPL — обычно не то что нужно.

Если LGPL несовместим с твоим use case'ом (например, embedded без возможности заменить library), напиши до того как форкнуть.

Куда репортить баги / контрибьютить?

• Source-репо: https://git.goldix.org/gx/cuframes
• Issues: тот же репо, /issues
• Гайд по контрибьюту: CONTRIBUTING.md в source-дереве

Этот документационный сайт живёт отдельно: https://git.goldix.org/gx/cuframes-docs — фиксы опечаток и контентные PR'ы — через ту же Gitea.