pip/doc/pages/chunk_stream.md

~english \page chunk_stream Chunk stream and versioned serialization ~russian \page chunk_stream Поток чанков и версионная сериализация

~english

\a PIChunkStream is a binary stream where data is stored as chunks: each chunk has an integer \e id and a value. Reading is id-based, so you can add or reorder fields over time and stay backward compatible: old readers ignore unknown ids, new readers can skip optional ids.

Two format versions exist (\a PIChunkStream::Version_1 and \a Version_2); the writer chooses the version, the reader detects it automatically. By default new data is written in Version_2.

When to use

Use chunk streams when:

• You need to extend structures without breaking existing stored data (add new fields with new ids).
• You want optional or reordered fields in a single stream.
• You use \ref code_model to generate serialization: with default (chunk) mode, \c pip_cmg emits operators that read/write via \a PIChunkStream and field ids (see \ref code_model "code_model" for PIMETA \c id and \c simple-stream / \c no-stream).

For fixed, non-extensible layouts, plain \a PIBinaryStream operators (see \ref iostream) are enough.

Usage

Build a \a PIChunkStream from a \a PIByteArray (read or read-write). Write with \c cs << cs.chunk(id, value) or \c add(id, value); read with \c read() to get the next id, then \c get(value). Call \c data() to get the byte buffer for storing or sending. Example (conceptually as in code_model output):

\code{.cpp} PIByteArray buf; PIChunkStream cs(&buf); cs << cs.chunk(1, i) << cs.chunk(2, s); // later: PIChunkStream reader(buf); while (!reader.atEnd()) { switch (reader.read()) { case 1: reader.get(i); break; case 2: reader.get(s); break; } } \endcode

Generated operators for structs use the same pattern; see \ref code_model.

~russian

\a PIChunkStream — бинарный поток, в котором данные хранятся чанками: у каждого чанка целочисленный \e id и значение. Чтение идёт по id, поэтому можно добавлять или менять порядок полей с сохранением обратной совместимости: старые читатели игнорируют неизвестные id, новые могут пропускать необязательные.

Есть две версии формата (\a PIChunkStream::Version_1 и \a Version_2); версию выбирает запись, при чтении она определяется автоматически. По умолчанию запись идёт в Version_2.

Когда использовать

Имеет смысл использовать поток чанков, когда:

• Нужно расширять структуры без поломки уже сохранённых данных (новые поля — новые id).
• Нужны необязательные или переставляемые поля в одном потоке.
• Используется \ref code_model для генерации сериализации: в режиме по умолчанию (chunk) \c pip_cmg выдаёт операторы через \a PIChunkStream и id полей (см. \ref code_model по PIMETA \c id и \c simple-stream / \c no-stream).

Для фиксированных неизменяемых форматов достаточно обычных операторов \a PIBinaryStream (см. \ref iostream).

Использование

Создают \a PIChunkStream из \a PIByteArray (чтение или чтение/запись). Запись: \c cs << cs.chunk(id, value) или \c add(id, value); чтение: \c read() — следующий id, затем \c get(value). \c data() возвращает буфер для сохранения или передачи. Примеры генерации операторов — в \ref code_model.