HQQ: Изолиране на C Libraries от Go Чрез Cache-Line Shared Memory

gosuda.org/hqq е среда за изпълнение на междупроцесни комуникации без cgo (zero-cgo) и инструмент за генериране на код за Go и C11. Тя изолира нативни C библиотеки в отделни работни процеси на операционната система и ги свързва с Go извикващи обекти чрез мапнати в паметта, съобразени с кеш линията пръстени от споделена памет (shared-memory rings). Проектът съчетава две транспортни нива (StandardLink за специализирани сесии с един производител и един потребител и Advanced за разпределение тип многопроизводител-многопотребител между множество работници), компилатора на езика за описание на интерфейси (IDL) hqq-bindgen и защитен срещу подправяне процес-супервайзър (secureexec и launch).

1go get gosuda.org/hqq

Цената на споделянето на адресно пространство с C

Всеки системен инженер на Go в крайна сметка достига до същото кръстопът. Вие изграждате Go услуга, която се компилира за секунди с CGO_ENABLED=0, доставя се като един статичен бинарен файл, крос-компилира се от лаптоп към целеви платформи Linux или Windows без sysroot и работи вътре в безопасна за паметта гарабидж-колектирана купа (heap). След това имате нужда от зряла C библиотека: SQLite за вградено релационно съхранение, Zstandard (libzstd) за компресия с речник или хардуерно ускорена мултимедийна или криптографска библиотека.

Активирането на cgo, за да се свърже тази C библиотека в Go процеса, решава непосредствения проблем със свързването, като същевременно въвежда три структурни пасива:

Обвързване на инструменталната верига и крос-компилацията: CGO_ENABLED=1 изисква C компилатор, целеви хедъри на libc и системен линкер за всяка целева ОС и архитектура. Изграждането на артефакти за linux/arm64 или windows/arm64 от работна станция darwin/arm64 превръща една единствена команда go build в матрица от крос-компилатори и sysroot-ове.
Надстройка на планирането по време на изпълнение: всяко извикване на cgo преминава границата на Go средата за изпълнение, превключва от стек на горутина с възможност за разширяване към системен стек и фиксира нишка на ОС (M). За фино зърнести извиквания таксата за преход (~50 до 150 ns на извикване) и състезанието в планировчика се натрупват бързо.
Колапс на домейна на грешките: C кодът работи в същото виртуално адресно пространство като Go средата за изпълнение. Едно единствено записване извън границите, използване след освобождаване, препълване на стека или abort() в рамките на C функция поврежда метадантите на Go купата или прекратява целия сървърен процес незабавно, заобикаляйки recover() и водещ със себе си всяка текуща HTTP или RPC заявка.

Когато екипите се опитват да избегнат cgo, общите алтернативи налагат различен компромис. Чисто Go механичните преводи на C кодови бази запазват CGO_ENABLED=0, но често следват с изоставане upstream C версиите, носят емулиран слой на виртуална памет и заделят значителни ресурси под натоварване. Преместването на C библиотеката в помощтен процес през loopback TCP или Unix домейн сокети възстановява изолацията на грешките, но всяко извикване заплаща за две превключвания на контекста на ядрото, копирания на сокет буфери и сериализация по мрежата.

Ние изградихме HQQ, след като зададохме директен въпрос: какво ако C библиотеката живее в отделен процес на ОС със собствено виртуално адресно пространство, докато Go и C обменят фреймове директно през споделени CPU кеш линии без да влизат в ядрото по бързия път?

Модел на интеграция	`CGO_ENABLED=0`	Изолация на грешки	Системни извиквания по бързия път	Заделяния в купата за извикване	Точност спрямо Upstream C11
`cgo` In-Process линкване	Не	Няма (споделена купа)	0	0 до 1+	Точен upstream C
Сокет / Тръба Subprocess RPC	Да	Граница на процеса	2 до 4	Множество (фрейминг + I/O)	Точен upstream C
Механичен C-към-Go превод	Да	В процеса на Go	0	Висока при сложни извиквания	Емулирана C среда
HQQ Shared-Memory IPC	Да	Граница на процеса	0 (адаптивно въртене)	0 (`StandardLink`)	Точен upstream C

Архитектурен преглед: Четири слоя от двете страни на границите на процесите

HQQ разделя изолацията на процесите на четири композируеми слоя, така че механиката на пръстена със споделена памет, генерирането на типизиран RPC код, верификацията на бинарната цялост и надзорът на дъщерните процеси да останат независими.

 1+-------------------------------------------------------------------+
 2| Go Application Process (CGO_ENABLED=0)                            |
 3|                                                                   |
 4|  +-----------------------+     +-------------------------------+  |
 5|  | Generated Go Client   |     | Process Supervisor            |  |
 6|  | (gosuda.org/hqq/      |     | (gosuda.org/hqq/launch +      |  |
 7|  |  bindgen/rt)          |     |  gosuda.org/hqq/secureexec)   |  |
 8|  +-----------+-----------+     +---------------+---------------+  |
 9|              |                                 |                  |
10|  +-----------v-----------+                     | Anonymous Pipe   |
11|  | Transport Tier        |                     | Lifeline         |
12|  | (StandardLink /       |                     | (--parent-stdin) |
13|  |  Advanced MPMC)       |                     |                  |
14+--------------+---------------------------------+------------------+
15               |                                 |
16===============|========= Shared Memory =========|===================
17               |     (mmap / CreateFileMapping)  |
18+--------------v---------------------------------v------------------+
19| C11 Worker Process (Isolated Address Space)                       |
20|                                                                   |
21|  +-----------------------+     +-------------------------------+  |
22|  | Generated C11 Server  |---->| Generation-Checked Handle     |  |
23|  | & Batch Shims         |     | Table (hqq_rpc.c)             |  |
24|  +-----------+-----------+     +---------------+---------------+  |
25|              |                                 |                  |
26|              +----------------+----------------+                  |
27|                               |                                   |
28|                     +---------v---------+                         |
29|                     | Native C Library  |                         |
30|                     | (SQLite, Zstd...) |                         |
31|                     +-------------------+                         |
32+-------------------------------------------------------------------+

1. Транспорт със споделена памет (`gosuda.org/hqq` и `c/`)

Базовият пакет gosuda.org/hqq и неговият C11 еквивалент в c/ имплементират два транспортни режима със споделена памет чрез POSIX mmap (Linux и macOS) и Win32 CreateFileMappingW (Windows). Всеки споделен сегмент започва с верифициран суперблок HQQ_STL3, който фиксира версията на протокола, геометрията на буфера и PID на крайните точки, преди да бъде прочетен какъвто и да е индекс на пръстена.

Всички горещи контролни думи и хедъри на слотове са подравнени към граници на 64-байтови кеш линии, така че ядрите на производителя и потребителя никога да не се състезават за една и съща кеш линия чрез фалшиво споделяне (false sharing).

1StandardLink Slot Layout (64-Byte Cache-Line Aligned)
2Byte Offset:  0x00                0x08                0x10                          0x40
3              +-------------------+-------------------+-----------------------------+
4Header Line:  | seq (u64 atomic)  | len (u32) | flags | reserved (zero-padded)      |
5              +-------------------+-------------------+-----------------------------+
6Payload Area: | payload bytes [0 .. BufferSize - 1] (directly encoded / decoded)    |
7              +---------------------------------------------------------------------+

Поле	Отстъп (Offset)	Размер	Семантика
`seq`	`0x00`	8 Б	Монотонен брояч на последователността. Нечетните стойности бележат незавършено записване; четните стойности публикуват потвърден фрейм чрез store-release.
`len`	`0x08`	4 Б	Дължина на полезния товар в байтове, записана в слота (`0 <= len <= BufferSize`).
`flags`	`0x0C`	4 Б	Битове за управление на фрейма (продължение, статус на грешка или известие за изключване).
`payload`	`0x40`	`BufferSize`	Непрекъсната област за полезен товар, четена и записвана на място без междинни копия.

Извикващите обекти избират между две транспортни нива в зависимост от структурата на едновременната работа:

StandardLink (1:1 SPSC сесия): Свързва клиентска и сървърна сесия чрез посветени слотове за заявка и отговор, защитени с ключалка на последователността (SeqLock). По бързия път писателят сериализира директно в мапнатия слот и потвърждава с атомно store-release; четецът се върти за кратко в потребителското пространство, преди да премине към примитиви за събуждане на ОС (futex на Linux, __ulock_wait на macOS, WaitOnAddress на Windows). Кръговото пътуване с един фрейм завършва за ~200 ns с 0 allocs/op.
Advanced (MPMC диспечерски пръстен): Мултиплексира M едновременни Go извикващи обекти в N C работни нишки, използвайки пръстен за подаване без заключване за много производители и много потребители (multi-producer multi-consumer), споделен пул от слотове и индексирана таблица за завършване. Извикващите обекти резервират слот, публикуват индекса на слота в пръстена и изчакват в записа си за завършване, докато работните нишки изваждат от опашката и завършват заявки извън ред.

И двете нива проследяват непрекъснато живостта на партньора. Всяка крайна точка актуализира атомен монотонен времеви щампи чрез Heartbeat() и проверява PeerAlive(timeout) по време на изчакване. Ако работен процес се срине по време на извикване, партньорът открива остарелия сърдечен ритъм или мъртвия PID незабавно, прекъсва блокираните изчаквания с ErrPeerGone и поддържа атомно Takeover на сесията, без да оставя след себе си заседнали файлове в споделената памет.

2. RPC без заделяне на памет и дръжки с проверка на генерацията (`gosuda.org/hqq/bindgen`)

Ръчното писане на фрейминг със споделена памет за C библиотека с десетки функции е досадно и предразполага към грешки. hqq-bindgen е компилатор на схеми, който чете файл с език за описание на интерфейси (.idl) (или зарежда такъв директно от C .h хедър чрез hqq-bindgen init) и генерира Go клиентски пакет без cgo заедно със скелет на C11 сървър.

Най-опасната грешка във всяко C свързване е излагането на сурови C указатели (sqlite3*, sqlite3_stmt*, ZSTD_CCtx*) през границата на езиците. Ако извикващ обект подаде указател след освобождаването му, подаде указател, принадлежащ на друга сесия, или повреди цяло число адрес, C библиотеката дефференцира невалидна памет.

hqq-bindgen забранява суровите указатели по мрежата. Вместо това IDL моделира C ресурсите със състояние като типизирани декларации за handle:

1service sqlite3 {
2    handle Db;
3    handle Stmt @owned_by(Db);
4
5    fn open_v2(path: string, flags: i32) -> result<Db, i32>;
6    fn prepare_one(db: Db, sql: string) -> result<Stmt, i32>;
7    fn finalize(stmt: @consume Stmt) -> result<void, i32>;
8    fn close(db: @consume Db) -> result<void, i32>;
9}

По мрежата всяка дръжка (handle) е 64-битово цяло число, съдържащо 32-битов индекс в таблицата и 32-битов ненулев брояч на генерацията: (uint64_t)generation << 32 | index. C средата за изпълнение (c/src/hqq_rpc.c) поддържа таблица с дръжки за всяка сесия с три инварианта:

Валидация на генерацията: всяко търсене проверява, че слотът е зает, съхранената му генерация съвпада с горните 32 бита на дръжката и етикетът на типа на дръжката съвпада с типа на параметъра (Db срещу Stmt). Повторното използване на затворена дръжка се проваля незабавно с HQQRPC_E_BAD_HANDLE преди извикването към C библиотеката.
Йерархична собственост (@owned_by): Тъй като Stmt е анотиран с @owned_by(Db), затварянето на Db дръжка автоматично обхожда всички активни дъщерни Stmt дръжки, притежавани от този Db, и изпълнява техните деструктори в обратен ред на заделяне (sqlite3_finalize преди sqlite3_close_v2).
Почистване при прекратяване на сесията: Ако Go клиент се разкачи или срине, без да затвори дръжките си, деструкторът на сесията на C сървъра обхожда цялата таблица с дръжки на сесията в обратен ред, гарантирайки нула изтекли C заделяния на памет при рестартиране на клиента.

Преди сесията да обработи първото си RPC извикване, клиентът и сървърът обменят 32-байтов SHA-256 интерфейсен даун (digest), изчислен върху канонизирания IDL (с префикс HQQ-BINDGEN-IDL-V1\n). Ако Go клиентът и C работникът са били компилирани от несъвместими IDL схеми, ръкостискането отхвърля връзката при зареждане.

3. Бинарно изпълнение без подправяне (`gosuda.org/hqq/secureexec`)

Преместването на C код в работен бинарен файл повдига въпрос за веригата на доставки: как Go процесът знае, че работният бинарен файл на диска не е бил модифициран или заменен между верификацията и изпълнението?

Извикването на crypto/sha256 върху файлов път, последвано от os/exec.Command(path).Start(), оставя прозорец тип „време на проверка до време на използване“ (Time-of-Check to Time-of-Use - TOCTOU), в който друг процес може да презапише или замени файла, преди ядрото да го изпълни. gosuda.org/hqq/secureexec затваря този прозорец:

На Linux secureexec отваря бинарния файл, предава съдържанието му в анонимен файлов дескриптор на паметта, създаден чрез memfd_create(MFD_CLOEXEC | MFD_ALLOW_SEALING), докато изчислява неговия SHA-256 хеш, верифицира хеша спрямо фиксиран 32-байтов даун или подписан с Ed25519 манифест за пускане (cmd/hqq-manifest), прилага fcntl(F_ADD_SEALS, F_SEAL_SEAL | F_SEAL_SHRINK | F_SEAL_GROW | F_SEAL_WRITE), така че никой процес в системата да не може да променя страниците, и стартира детето от запечатания дескриптор.
На macOS и Windows secureexec материализира верифицирани бинарни файлове в защитени с разрешения кеш директории, индексирани по SHA-256 даун, и верифицира размера на файла и цялостта на дауна преди стартиране.

4. Надзор на процесите чрез родителска линия на живот (`gosuda.org/hqq/launch`)

Когато Go приложение стартира фонов C работен процес, работникът никога не трябва да надживее своя родител като сирак процес, дори ако Go родителят бъде прекратен със SIGKILL (kill -9) и не може да изпълни defer хедърите за почистване.

gosuda.org/hqq/launch налага обвързване на продължителността на живота чрез анонимна тръба на ОС (pipe), подадена към стандартния вход на работника с флаг --parent-stdin. Go родителят държи края за писане на тръбата и никога не пише в него; C работникът следи края за четене в специална нишка за линия на живот. Ако Go процесът излезе нормално, получи паника или бъде убит от ядрото на ОС (със SIGKILL или OOM killer), ядрото незабавно затваря дескриптора за писане. C работникът получава EOF на тръбата в рамките на микросекунди, прекъсва всички активни извиквания, стартира деструкторите на дръжките на сесията си, премахва връзките към файловете в споделената памет и излиза чисто.

Бърз старт: Извикване на генерирана услуга

С hqq-bindgen и launch извикването на изолиран C работник от Go изглежда като обикновен типизиран Go клиент, като същевременно се запазва CGO_ENABLED=0:

 1package main
 2
 3import (
 4	"context"
 5	"fmt"
 6	"log"
 7	"time"
 8
 9	"gosuda.org/hqq/bindgen/rt"
10	"gosuda.org/hqq/launch"
11	"gosuda.org/hqq/secureexec"
12)
13
14func main() {
15	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
16	defer cancel()
17
18	hash, err := secureexec.ParseHash("7649b1b45dacd934cde8149f35f4fcc3937f6486fbac23ce976466719b3752bb")
19	if err != nil {
20		log.Fatal(err)
21	}
22
23	listener, err := launch.NewListenerName("demo")
24	if err != nil {
25		log.Fatal(err)
26	}
27
28	srv, err := launch.Start(ctx, launch.Config{
29		Binary:   "/path/to/verified-worker",
30		SHA256:   hash,
31		Listener: listener,
32		Args:     []string{listener},
33	})
34	if err != nil {
35		log.Fatal(err)
36	}
37	defer srv.Close()
38
39	fmt.Printf("worker running on shared-memory listener %s (opts=%+v)\n", listener, rt.SessionOptions{})
40}

Структура на хранилището

Всяка подсистема в gosuda.org/hqq е организирана в фокусирани пакети с изрични граници:

 1gosuda.org/hqq
 2├── standard.go / ring.go      # StandardLink (SPSC) и нискочестотни примитиви за пръстен в споделена памет
 3├── advanced.go / slotpool.go  # Advanced (MPMC) диспечер, пул от слотове и таблица за завършване
 4├── shm_*.go / wait_*.go       # ОС-специфични mmap/CreateFileMapping и futex/ulock/WaitOnAddress
 5├── c/                         # C11 транспортна библиотека (hqq.c) и RPC сървърна среда за изпълнение (hqq_rpc.c)
 6├── bindgen/                   # hqq-bindgen IDL парсер, верификатор (V1-V41) и генератор на Go/C11 код
 7│   └── rt/                    # Go клиентска среда за изпълнение без заделяне на памет за генерирани услуги
 8├── secureexec/                # SHA-256 / Ed25519 верификация на манифест и изпълнение, запечатано с memfd
 9├── launch/                    # Супервайзър на работни процеси с управление на линията на живот --parent-stdin
10├── cmd/hqq-manifest/          # CLI инструмент за генериране и подписване на манифести на бинарни файлове за пускане
11└── spec/                      # Изпълними спецификации на мрежата и златни тестови вектори (BINDGEN.md)

За да видите как HQQ захранва готови за производство заместители за две от най-широко използваните cgo библиотеки в екосистемата на Go, разгледайте съпътстващите пакети, изградени върху този стек:

gosuda.org/sqlite3: Готов за директна употреба database/sql драйвер, съвместим с github.com/mattn/go-sqlite3, изпълняващ нативен C SQLite 3.54.1 през споделена памет с конвейерно предварително извличане на партиди.
gosuda.org/zstd: Готов за директна употреба заместител на github.com/DataDog/zstd, изпълняващ нативен C libzstd 1.5.7 в изолиран работен процес със споделена памет, контексти без заделяне на памет и масово пакетиране.
Хранилище в GitHub: https://github.com/gosuda/HQQ

Цената на споделянето на адресно пространство с C

Архитектурен преглед: Четири слоя от двете страни на границите на процесите

1. Транспорт със споделена памет (gosuda.org/hqq и c/)

2. RPC без заделяне на памет и дръжки с проверка на генерацията (gosuda.org/hqq/bindgen)

3. Бинарно изпълнение без подправяне (gosuda.org/hqq/secureexec)