Модуль box

Непрозрачная структура, передаваемая в хранимую процедуру на C

Возвращает кортеж из хранимой процедуры на C.

Для возвращаемого кортежа Tarantool автоматически ведёт счётчик ссылок. Пример программы, использующей box_return_tuple(), — write.c.

Параметры:

• ctx (box_function_ctx_t*) — непрозрачная структура, передаваемая Tarantool в хранимую процедуру на C

• tuple (box_tuple_t*) — кортеж, который нужно вернуть

Возвращает

-1 в случае ошибки (возможно, нехватка памяти; проверить box_error_last())

Возвращает

0 в противном случае

Возвращает указатель на последовательность байтов в формате MessagePack.

Эту функцию можно использовать вместо box_return_tuple() — она передаёт то же значение, но в виде MessagePack, а не объекта-кортежа. Она может быть проще, чем box_return_tuple(), если результат небольшой, например число, логическое значение или короткая строка. Она также работает быстрее, чем box_return_tuple(), поскольку не требуется создавать кортеж каждый раз, когда нужно вернуть что-либо из функции на C.

С другой стороны, если уже существующий кортеж получен из итератора, быстрее вернуть этот кортеж через box_return_tuple(), чем извлекать его части и передавать их через box_return_mp().

Параметры:

• ctx (box_function_ctx_t*) — непрозрачная структура, передаваемая Tarantool в хранимую процедуру на C

• mp (char*) — первый байт MessagePack

• mp_end (char*) — позиция после последнего байта MessagePack

Возвращает

-1 в случае ошибки (возможно, нехватка памяти; проверить box_error_last())

Возвращает

0 в противном случае

Например, если mp — это буфер, а mp_end — значение, полученное при кодировании одного скалярного значения MP_UINT с помощью mp_end=mp_encode_uint(mp,1);, то вызов box_return_mp(ctx,mp,mp_end); должен вернуть 0.

Находит идентификатор спейса по имени.

Эта функция выполняет запрос SELECT к системному спейсу _vspace.

Параметры:

• name (const char*) — имя спейса

• len (uint32_t) — длина name

Возвращает

BOX_ID_NIL в случае ошибки или если спейс не найден (проверить box_error_last())

Возвращает

space_id в противном случае

См. также: box_index_id_by_name

Находит идентификатор индекса по имени.

Эта функция выполняет запрос SELECT к системному спейсу _vindex.

Параметры:

• space_id (uint32_t) — идентификатор спейса

• name (const char*) — имя индекса

• len (uint32_t) — длина name

Возвращает

BOX_ID_NIL в случае ошибки или если индекс не найден (проверить box_error_last())

Возвращает

space_id в противном случае

См. также: box_space_id_by_name

Выполняет запрос INSERT/REPLACE.

Параметры:

• space_id (uint32_t) — идентификатор спейса

• tuple (const char*) — кортеж, закодированный в формате массива MsgPack ([ field1, field2, ...])

• tuple_end (const char*) — конец tuple

• result (box_tuple_t**) — выходной аргумент. Результирующий кортеж. Можно задать NULL, чтобы отбросить результат

Возвращает

-1 в случае ошибки (проверить box_error_last())

Возвращает

0 в противном случае

См. также: space_object.insert()

Выполняет запрос REPLACE.

Параметры:

• space_id (uint32_t) — идентификатор спейса

• tuple (const char*) — кортеж, закодированный в формате массива MsgPack ([ field1, field2, ...])

• tuple_end (const char*) — конец tuple

• result (box_tuple_t**) — выходной аргумент. Результирующий кортеж. Можно задать NULL, чтобы отбросить результат

Возвращает

-1 в случае ошибки (проверить box_error_last())

Возвращает

0 в противном случае

См. также: space_object.replace()

Выполняет запрос DELETE.

Параметры:

• space_id (uint32_t) — идентификатор спейса

• index_id (uint32_t) — идентификатор индекса

• key (const char*) — ключ, закодированный в формате массива MsgPack ([ field1, field2, ...])

• key_end (const char*) — конец key

• result (box_tuple_t**) — выходной аргумент. Прежний кортеж. Можно задать NULL, чтобы отбросить результат

Возвращает

-1 в случае ошибки (проверить box_error_last())

Возвращает

0 в противном случае

См. также: space_object.delete()

Выполняет запрос UPDATE.

Параметры:

• space_id (uint32_t) — идентификатор спейса

• index_id (uint32_t) — идентификатор индекса

• key (const char*) — ключ, закодированный в формате массива MsgPack ([ field1, field2, ...])

• key_end (const char*) — конец key

• ops (const char*) — операции, закодированные в формате массива MsgPack, например [[ '=', field_id, value ], ['!', 2, 'xxx']]

• ops_end (const char*) — конец раздела ops

• index_base (int) — 0, если идентификаторы полей начинаются с нуля, как в C; 1, если с единицы, как в Lua

• result (box_tuple_t**) — выходной аргумент. Прежний кортеж. Можно задать NULL, чтобы отбросить результат

Возвращает

-1 в случае ошибки (проверить box_error_last())

Возвращает

0 в противном случае

См. также: space_object.update()

Выполняет запрос UPSERT.

Параметры:

• space_id (uint32_t) — идентификатор спейса

• index_id (uint32_t) — идентификатор индекса

• tuple (const char*) — кортеж, закодированный в формате массива MsgPack ([ field1, field2, ...])

• tuple_end (const char*) — конец tuple

• ops (const char*) — операции, закодированные в формате массива MsgPack, например [[ '=', field_id, value ], ['!', 2, 'xxx']]

• ops_end (const char*) — конец ops

• index_base (int) — 0, если идентификаторы полей начинаются с нуля, как в C; 1, если с единицы, как в Lua

• result (box_tuple_t**) — выходной аргумент. Прежний кортеж. Можно задать NULL, чтобы отбросить результат

Возвращает

-1 в случае ошибки (проверить box_error_last())

Возвращает

0 в противном случае

См. также: space_object.upsert()

Очищает спейс.

Параметры:

• space_id (uint32_t) — идентификатор спейса

Устарело с версии 3.0.0.

Начиная с версии 2.4.1. Отправляет данные MessagePack в канал данных сессии — сокет, консоль или что-либо иное, стоящее за сессией. Работает так же, как Lua-функция box.session.push().

Параметры:

• data (const char*) — начало MessagePack для отправки

• data_end (const char*) — конец MessagePack для отправки

Возвращает

-1 в случае ошибки (проверить box_error_last())

Возвращает

0 в противном случае

Начиная с версии 2.4.1. Возвращает последнее полученное значение указанной последовательности.

Параметры:

• seq_id (uint32_t) — идентификатор последовательности

• result (int64_t) — указатель на переменную, в которой при успешном выполнении будет сохранено текущее значение последовательности.

Возвращает

0 в случае успеха и -1 в противном случае. В случае ошибки её можно получить через box_error_last().

Начиная с версии 2.11.0. Возвращает версию схемы базы данных. Версия схемы — это число, которое показывает, изменялась ли схема базы данных. Например, значение schema_version увеличивается при добавлении или удалении спейса или индекса, а также при изменении имени спейса, индекса или поля.

Возвращает

версию схемы базы данных

Тип возвращаемого значения

number

См. также: box.info.schema_version и IPROTO_SCHEMA_VERSION

Начиная с версии 2.11.0. Возвращает уникальный идентификатор (ID) текущей сессии.

Возвращает

идентификатор сессии; 0 или -1, если сессии нет

Тип возвращаемого значения

number

См. также: box.session.id()

Начиная с версии 2.11.0. Отправляет пакет IPROTO через сокет сессии с заданными заголовком и телом в формате MsgPack. Функция передаёт управление (yield). Функция работает только для бинарных сессий. Подробнее см. box.session.type().

Параметры:

• sid (uint32_t) — идентификатор сессии IPROTO (см. box_session_id())

• header (char*) — заголовок, закодированный в MsgPack

• header_end (char*) — конец заголовка, закодированного в MsgPack

• body (char*) — тело, закодированное в MsgPack. Если параметры body и body_end опущены, пакет состоит только из заголовка.

• body_end (char*) — конец тела, закодированного в MsgPack

Возвращает

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

Тип возвращаемого значения

number

См. также: box.iproto.send()

Возможные ошибки:

• ER_SESSION_CLOSED – сессия закрыта.
• ER_NO_SUCH_SESSION – сессия не существует.
• ER_MEMORY_ISSUE – достигнут предел по памяти.
• ER_WRONG_SESSION_TYPE – тип сессии не является бинарным.

Подробнее см. src/box/errcode.h.

Пример

 
/* IPROTO constants are not exported to C.* That is, the user encodes them by himself.*/#define IPROTO_REQUEST_TYPE 0x00#define IPROTO_OK 0x00#define IPROTO_SYNC 0x01#define IPROTO_SCHEMA_VERSION 0x05#define IPROTO_DATA 0x30char buf[256] = {};char *header = buf;char *header_end = header;header_end = mp_encode_map(header_end, 3);header_end = mp_encode_uint(header_end, IPROTO_REQUEST_TYPE);header_end = mp_encode_uint(header_end, IPROTO_OK);header_end = mp_encode_uint(header_end, IPROTO_SYNC);header_end = mp_encode_uint(header_end, 10);header_end = mp_encode_uint(header_end, IPROTO_SCHEMA_VERSION);header_end = mp_encode_uint(header_end, box_schema_version());char *body = header_end;char *body_end = body;body_end = mp_encode_map(body_end, 1);body_end = mp_encode_uint(body_end, IPROTO_DATA);body_end = mp_encode_uint(body_end, 1);/* The packet contains both the header and body. */box_iproto_send(box_session_id(), header, header_end, body, body_end);/* The packet contains the header only. */box_iproto_send(box_session_id(), header, header_end, NULL, NULL);

Начиная с версии 2.11.0. Устанавливает новый обработчик запросов IPROTO с указанным контекстом для заданного типа запроса. Функция передаёт управление (yield).

Параметры:

• request_type (uint32_t) — код типа запроса IPROTO (например, IPROTO_SELECT). Подробнее см. Клиент-серверные запросы и ответы.

  Чтобы переопределить обработчик неизвестных типов запросов, использовать код типа IPROTO_UNKNOWN.

• handler (iproto_handler_t) — обработчик запросов IPROTO. Чтобы сбросить обработчик запросов, задать параметру handler значение NULL. Полное описание параметра приведено в разделе Функция-обработчик.

• destroy (iproto_handler_destroy_t) — деструктор обработчика запросов IPROTO. Деструктор вызывается, когда соответствующий обработчик удаляется. Полное описание параметра приведено в разделе Функция-деструктор обработчика.

• ctx (void*) — контекст, передаваемый в колбэки handler и destroy

Возвращает

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

Тип возвращаемого значения

number

См. также: box.iproto.override()

Возможные ошибки:

Если Lua-обработчик выбрасывает исключение, поведение аналогично удалённому вызову процедуры. Клиенту по IPROTO возвращаются следующие ошибки (см. src/lua/utils.h):

• ER_PROC_LUA – исключение выброшено из Lua-обработчика, диагностика не задана.
• диагностика из src/box/errcode.h – исключение выброшено, диагностика задана.

Подробнее см. src/box/errcode.h.

Функция-обработчик

Сигнатура функции-обработчика (параметр handler):

 
enum iproto_handler_status {        IPROTO_HANDLER_OK,        IPROTO_HANDLER_ERROR,        IPROTO_HANDLER_FALLBACK,}typedef enum iproto_handler_status(*iproto_handler_t)(const char *header, const char *header_end,                    const char *body, const char *body_end, void *ctx);

где:

• header (const char*) – заголовок, закодированный в MsgPack
• header_end (const char*) – конец заголовка, закодированного в MsgPack
• body (const char*) – тело, закодированное в MsgPack
• header_end (const char*) – конец тела, закодированного в MsgPack

Обработчик возвращает код состояния. Возможные состояния:

• IPROTO_REQUEST_HANDLER_OK – успешное выполнение
• IPROTO_REQUEST_HANDLER_ERROR – ошибка, диагностика должна быть задана обработчиком (см. box_error_set() и box_error_raise())
• IPROTO_REQUEST_HANDLER_FALLBACK – переход к обработчику по умолчанию

Функция-деструктор обработчика

Деструктор вызывается при сбросе обработчика. Сигнатура функции-деструктора (параметр destroy):

 
typedef void (*iproto_handler_destroy_t)(void *ctx);

где:

• ctx (void*): контекст, предоставленный функцией box_iproto_override().

Примеры

 
box_iproto_override(1000, iproto_request_handler_с, NULL)box_iproto_override(IPROTO_SELECT, iproto_request_handler_с, (uintptr_t)23)box_iproto_override(IPROTO_SELECT, NULL, NULL)box_iproto_override(IPROTO_UNKNOWN, iproto_unknown_request_handler_с, &ctx)