Payload

Payload представляет собой структуру индексированных полей фиксированного типа. Внутренний API Payload представлен тремя классами верхнего уровня:

• PayloadValue — shared-копия структуры полей записи. Размер структуры равен сумме размера полей + 16 байт заголовка.

• PayloadType — определение структуры Payload. Содержит вектор полей (имена, типы, размеры, смещения). На один неймспейс существует только одна копия PayloadType. Она изменяема и потокобезопасна. Изменяемость и потокобезопасность обеспечиваются за счёт COW-семантики. При изменении или добавлении полей создаётся новая копия PayloadType.

• PayloadIface — шаблон интерфейса для управления Payload.

• Выполняет всю низкоуровневую работу над PayloadValue. Содержит указатели на PayloadValue и PayloadType. Существует в двух экземплярах:

  1. Payload — может изменять PayloadValue.
  2. ConstPayload — интерфейс только для чтения, не может изменять PayloadValue.

API Payload схож с обычным Reflection API и содержит методы Set и Get для управления полями (см. payloadiface.h для получения подробной информации).

Структура PayloadValue

PayloadValue в каждом объекте Payload имеет следующую структуру:

Формат хранения данных полей PayloadValue

Тривиальные типы данных, такие как int32, int64, double, хранятся в PayloadValue в нативном формате:

Для хранения строк используется 8-байтовый слабый указатель на строку reindexer::p_string. Важно, что само значение PayloadValue не содержит строки.

p_string

p_string — это оболочка указателя. Она использует 59-й, 60-й и 61-й биты указателя в качестве тега строкового типа (предполагается, что размер адресного пространства x86_64 равен 2^48: https://en.wikipedia.org/wiki/X86-64#Virtual_address_space_details).

key_string

reindexer::key_string является производным от std::string и, кроме того, содержит счетчик ссылок и экспортированный заголовок с полями указатель + размер.

Экспортированный заголовок используется для прямого доступа к Payload из приложения, написанного не на c++ (например, когда Reindexer — часть golang-приложения). Данные в key_string доступны для изменения.

Хранение массивов в PayloadValue

Массивы хранятся в виде заголовка массива (ArrayHeader), который содержит 4-байтовое начальное смещение, и 4-байтового количества элементов в массиве.

Пример структуры:

struct
{
   int64_t f1 = 5;
   int f2[] = {6,7,8};
   int f3 = 10;
   string f4 = "abc";
}

PayloadValue для данного примера:

Жизненный цикл и владение

Поведение PayloadValue похоже на поведение умного указателя std::shared_ptr. PayloadValue увеличивает внутренний счетчик ссылок при копировании, уменьшает этот счетчик в деструкторе и удаляет хранимые данные, если значение счетчика ссылок равно 0. Счетчик ссылок PayloadValue потокобезопасен.

PayloadValue может быть в одном из трех состояний:

• Free: структура данных не выделена.
• Non Shared: данные структуры принадлежат исключительно PayloadValue.
• Shared: данные структуры совместно используются с другими PayloadValue.

PayloadValue в состоянии Shared не допускает модификации. Перед любой модификацией код должен создать его копию путем вызова PayloadValue::Clone (). Clone проверит состояние PayloadValue и при необходимости выделит новую структуру либо создаст эксклюзивную копию.

PayloadValue не владеет своими строками по умолчанию. Для контроля владения строками существуют 2 метода: PayloadIface::AddRefStrings () и PayloadIface::ReleaseStrings ().

AddRefStrings и ReleaseStrings не работают по идиоме RAII, поэтому код должен сам контролировать баланс их вызовов. Если код не вызовет ReleaseStrings, возникнет утечка памяти.

Пример типового использования

	PayloadType type = ns->payloadType_;
	PayloadValue value = ns->items_[index];

	// Create control object
	ConstPayload payload(type, value);

	VariantArray keyRefs;

	// Dump all fields to stdout
	for (int i = 0; i < payload.NumFields(); i++) {
		auto &field = payload.Type().Field(i);
		printf("\n%s=", field.Name().c_str());
		for (auto &elem : payload.Get (i,keyRefs)) {
			printf("%s", Variant(elem).toString().c_str());
		}
	}