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

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

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

FloatVector

FloatVector/ConstFloatVector - отдельные типы для хранения float32-векторов. Внутри себя они содержат std::unique_ptr<float32[] для хранения данных вектора, а также поле с его размерностью.

Внутри PayloadValue вектора не хранятся. Вместо этого там сохраняются только их представления: FloatVectorView/ConstFloatVectorView. FloatVectorView реализован в виде одного 64-битного числа, в которое упакован невладеющий указатель на вектор (48 бит, опционально), а также его размерность (16 бит).

Особенностью FloatVectorView является то, что он может находиться в striped-состоянии и не указывать ни на какой реальный вектор вообще. Сам же вектор в этом случае будет храниться в соответсвующем индексе и будет доступен только по внутреннему ID документа.

В случаях, когда во время выборки пользователю требуется получить реальные значения векторных полей, используется вспомогательный контейнер FloatVectorsHolderMap или FloatVectorsHolderVector, а содержимое FloatVectorView внутри PayloadValue перезаписывается таким образом, чтобы указывать на извлечённый из индекса вектор.

Хранение массивов в 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());
		}
	}