57 lines
3.9 KiB
Markdown
57 lines
3.9 KiB
Markdown
\~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.
|