Обновлена 15 сентября 2026 г. в 08:55

Read views: C API

В данном разделе описывается C API для работы с представлениями чтения. C API является потокобезопасным (MT-safe) и предоставляет возможность использовать представление чтения из любого потока, а не только из основного потока (TX).

C API имеет следующие особенности:

Функция space.upgrade не применяется к извлекаемым кортежам, даже если выполняется обновление спейса.
Кортежи, хранящиеся в сжатых спейсах, не распаковываются — они возвращаются как сырой MessagePack (MP_EXT/MP_COMPRESSION).

Типы данных

Приведённые ниже непрозрачные типы данных представляют сырые представления чтения и итератор по данным в сыром представлении чтения. Обратите внимание, что для кортежей, извлекаемых из представления чтения, специального типа данных нет. Кортежи возвращаются как сырые данные MessagePack (const char *).

type box_raw_read_view box_raw_read_view_t

Сырое представление чтения базы данных.

type box_raw_read_view_space box_raw_read_view_space_t

Спейс в сыром представлении чтения.

type box_raw_read_view_index box_raw_read_view_index_t

Индекс в сыром представлении чтения.

type box_raw_read_view_iterator box_raw_read_view_iterator_t

Итератор по данным в сыром представлении чтения.

Создание и удаление представлений чтения

Для создания или удаления представления чтения используются приведённые ниже функции.

box_raw_read_view_t * box_raw_read_view_new(const char *name)

Открыть сырое представление чтения с указанным именем и получить указатель на это представление чтения. В случае ошибки возвращает NULL и устанавливает box_error_last(). Эта функция может вызываться только из основного потока (TX).

Параметры:

*name (const char) — (необязательный) имя представления чтения; если name не указано, имени представления чтения присваивается значение unknown

Возвращает

указатель на представление чтения

void box_raw_read_view_delete(box_raw_read_view_t *rv)

Закрыть сырое представление чтения и освободить все связанные с ним ресурсы. Эта функция может вызываться только из основного потока (TX).

Параметры:

*rv (box_raw_read_view_t) — указатель на представление чтения

Спейсы и индексы

Чтобы получить данные из представления чтения, необходимо указать индекс, из которого извлекаются данные. Для поиска спейсов и индексов в объекте представления чтения доступны следующие функции.

box_raw_read_view_space_t * box_raw_read_view_space_by_id(const box_raw_read_view_t *rv, uint32_t space_id)

Найти спейс по идентификатору в сыром представлении чтения. Если спейс не найден, возвращает NULL и устанавливает box_error_last().

Параметры:

*rv (const box_raw_read_view_t) — указатель на представление чтения
space_id (uint32_t) — идентификатор спейса

Возвращает

указатель на спейс

box_raw_read_view_space_t * box_raw_read_view_space_by_name(const box_raw_read_view_t rv, const char space_name, uint32_t space_name_len)

Найти спейс по имени в сыром представлении чтения. Если спейс не найден, возвращает NULL и устанавливает box_error_last().

Параметры:

*rv (const box_raw_read_view_t) — указатель на представление чтения
*space_name (const char) — имя спейса
space_name_len (uint32_t) — длина имени спейса

Возвращает

указатель на спейс

box_raw_read_view_index_t * box_raw_read_view_index_by_id(const box_raw_read_view_space_t *space, uint32_t index_id)

Найти индекс по идентификатору в спейсе представления чтения. Если индекс не найден, возвращает NULL и устанавливает box_error_last().

Параметры:

*space (const box_raw_read_view_space_t) — указатель на спейс представления чтения
space_id (uint32_t) — идентификатор спейса

Возвращает

указатель на индекс

box_raw_read_view_index_t * box_raw_read_view_index_by_name(const box_raw_read_view_space_t space, const char index_name, uint32_t index_name_len)

Найти индекс по имени в спейсе представления чтения. Если индекс не найден, возвращает NULL и устанавливает box_error_last().

Параметры:

*space (const box_raw_read_view_space_t) — указатель на спейс
*index_name (const char) — имя индекса
index_name_len (uint32_t) — длина имени индекса

Возвращает

указатель на индекс

Итерация и поиск

Приведённые ниже функции предоставляют возможность найти кортеж по ключу или создать итератор по индексу представления чтения.

int box_raw_read_view_get(const box_raw_read_view_index_t index, const char key, const char *key_end, const char **data, uint32_t *size)

Найти кортеж в индексе представления чтения. Если кортеж найден, выходные аргументы data и size возвращают указатель на данные кортежа и их размер. Если кортеж не найден, *data устанавливается в NULL, а *size — в 0.

Параметры:

*index (const box_raw_read_view_index_t) — указатель на индекс представления чтения
*key (const char) — указатель на первый байт данных MsgPack, представляющих ключ поиска
*key_end (const char) — указатель на байт, следующий за последним байтом данных MsgPack, представляющих ключ поиска
**data (const char) — указатель на данные кортежа
*size (uint32_t) — размер данных кортежа

Возвращает

0 в случае успеха; в случае ошибки возвращает -1 и устанавливает box_error_last()

int box_raw_read_view_iterator_create(box_raw_read_view_iterator_t it, const box_raw_read_view_index_t index, int type, const char key, const char key_end)

Создать итератор по индексу сырого представления чтения. Инициализированный объект итератора, возвращаемый этой функцией, остаётся действительным и может безопасно использоваться до его уничтожения или закрытия представления чтения. Когда объект итератора больше не нужен, его следует уничтожить с помощью box_raw_read_view_iterator_destroy().

Параметры:

*it (box_raw_read_view_iterator_t) — итератор по индексу сырого представления чтения
*index (const box_raw_read_view_index_t) — указатель на индекс представления чтения
type (int) — направление итерации, задаваемое типом iterator_type
*key (const char) — указатель на первый байт данных MsgPack, представляющих ключ поиска
*key_end (const char) — указатель на байт, следующий за последним байтом данных MsgPack, представляющих ключ поиска

Возвращает

0 в случае успеха; в случае ошибки возвращает -1 и устанавливает box_error_last()

int box_raw_read_view_iterator_next(box_raw_read_view_iterator_t *it, const char **data, uint32_t *size)

Получить текущий кортеж и переместить вперёд заданный итератор по индексу сырого представления чтения. Указатель на данные кортежа и их размер возвращаются в выходных аргументах data и size. Данные, возвращаемые этой функцией, остаются действительными и могут безопасно использоваться до закрытия представления чтения.

Параметры:

*it (box_raw_read_view_iterator_t) — итератор по индексу представления чтения
**data (const char) — указатель на данные кортежа; в конце итерации *data устанавливается в NULL
*size (uint32_t) — размер данных кортежа; в конце итерации *size устанавливается в 0

Возвращает

0 в случае успеха; в случае ошибки возвращает -1 и устанавливает box_error_last()

void box_raw_read_view_iterator_destroy(box_raw_read_view_iterator_t *it)

Уничтожить итератор по индексу сырого представления чтения. После вызова этой функции объект итератора использовать не следует, однако данные, возвращённые итератором, можно безопасно разыменовывать до закрытия представления чтения.

Параметры:

*it (box_raw_read_view_iterator_t) — итератор по индексу представления чтения

Формат спейса

Приведённые ниже методы объекта спейса предоставляют возможность получить имена и типы полей спейса.

uint32_t box_raw_read_view_space_field_count(const box_raw_read_view_space_t *space)

Получить количество полей, определённых в формате спейса представления чтения.

Параметры:

*space (const box_raw_read_view_space_t) — указатель на спейс представления чтения

Возвращает

количество полей

const char * box_raw_read_view_space_field_name(const box_raw_read_view_space_t *space, uint32_t field_no)

Получить имя поля, определённого в формате спейса представления чтения. Если номер поля больше общего количества полей, определённых в формате, возвращается NULL. Строка, возвращаемая этой функцией, гарантированно остаётся действительной до закрытия представления чтения.

Параметры:

*space (const box_raw_read_view_space_t) — указатель на спейс представления чтения
field_no (uint32_t) — номер поля (начинается с 0)

Возвращает

имя поля

const char * box_raw_read_view_space_field_type(const box_raw_read_view_space_t *space, uint32_t field_no)

Получить тип поля, определённого в формате спейса представления чтения. Если номер поля больше общего количества полей, определённых в формате, возвращается NULL. Строка, возвращаемая этой функцией, гарантированно остаётся действительной до закрытия представления чтения.

Параметры:

*space (const box_raw_read_view_space_t) — указатель на спейс представления чтения
field_no (uint32_t) — номер поля (начинается с 0)

Возвращает

тип поля

Была ли статья полезна?

Была ли статья полезна?

Read views: C API

Типы данных

type box_raw_read_view box_raw_read_view_t

type box_raw_read_view_space box_raw_read_view_space_t

type box_raw_read_view_index box_raw_read_view_index_t

type box_raw_read_view_iterator box_raw_read_view_iterator_t

Создание и удаление представлений чтения

box_raw_read_view_t * box_raw_read_view_new(const char *name)

void box_raw_read_view_delete(box_raw_read_view_t *rv)

Спейсы и индексы

box_raw_read_view_space_t * box_raw_read_view_space_by_id(const box_raw_read_view_t *rv, uint32_t space_id)

box_raw_read_view_space_t * box_raw_read_view_space_by_name(const box_raw_read_view_t *rv, const char *space_name, uint32_t space_name_len)

box_raw_read_view_index_t * box_raw_read_view_index_by_id(const box_raw_read_view_space_t *space, uint32_t index_id)

box_raw_read_view_index_t * box_raw_read_view_index_by_name(const box_raw_read_view_space_t *space, const char *index_name, uint32_t index_name_len)

Итерация и поиск

int box_raw_read_view_get(const box_raw_read_view_index_t *index, const char *key, const char *key_end, const char **data, uint32_t *size)

int box_raw_read_view_iterator_create(box_raw_read_view_iterator_t *it, const box_raw_read_view_index_t *index, int type, const char *key, const char *key_end)

int box_raw_read_view_iterator_next(box_raw_read_view_iterator_t *it, const char **data, uint32_t *size)

void box_raw_read_view_iterator_destroy(box_raw_read_view_iterator_t *it)

Формат спейса

uint32_t box_raw_read_view_space_field_count(const box_raw_read_view_space_t *space)

const char * box_raw_read_view_space_field_name(const box_raw_read_view_space_t *space, uint32_t field_no)

const char * box_raw_read_view_space_field_type(const box_raw_read_view_space_t *space, uint32_t field_no)

Была ли статья полезна?

Была ли статья полезна?

box_raw_read_view_space_t * box_raw_read_view_space_by_name(const box_raw_read_view_t rv, const char space_name, uint32_t space_name_len)

box_raw_read_view_index_t * box_raw_read_view_index_by_name(const box_raw_read_view_space_t space, const char index_name, uint32_t index_name_len)

int box_raw_read_view_get(const box_raw_read_view_index_t index, const char key, const char *key_end, const char **data, uint32_t *size)

int box_raw_read_view_iterator_create(box_raw_read_view_iterator_t it, const box_raw_read_view_index_t index, int type, const char key, const char key_end)