Module box | Tarantool
Войти Регистрация
Download

Версия:

2.11
Документация на русском языке
поддерживается сообществом
Стать контрибьютором
Close banner
Close banner
Справочники Справочник по C API Module box

Module box

type box_function_ctx_t

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

int box_return_tuple(box_function_ctx_t *ctx, box_tuple_t *tuple)

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

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

Параметры:
  • ctx (box_function_ctx_t*) – непрозрачная структура, передаваемая Tarantool в хранимую процедуру на языке C
  • tuple (box_tuple_t*) – возвращаемый кортеж
Результат:

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

0 в остальных случаях
int box_return_mp(box_function_ctx_t *ctx, const char *mp, const char *mp_end)

Возврат указателя на серию байтов в формате 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.

uint32_t box_space_id_by_name(const char *name, uint32_t len)

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

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

Параметры:
  • name (const char*) – имя спейса
  • len (uint32_t) – длина имени name
Результат:

BOX_ID_NIL в случае ошибки или отсутствия (проверьте box_error_last())
Результат:

space_id в остальных случаях

См. также box_index_id_by_name

uint32_t box_index_id_by_name(uint32_t space_id, const char *name, uint32_t len)

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

Данная функция делает запрос выборки 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

int box_insert(uint32_t space_id, const char *tuple, const char *tuple_end, box_tuple_t **result)

Выполнение запроса вставки или замены (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 в остальных случаях

See also: space_object.insert()

int box_replace(uint32_t space_id, const char *tuple, const char *tuple_end, box_tuple_t **result)

Выполнение запроса замены (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 в остальных случаях

See also: space_object.replace()

int box_delete(uint32_t space_id, uint32_t index_id, const char *key, const char *key_end, box_tuple_t **result)

Выполнение запроса удаления (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 в остальных случаях

See also: space_object.delete()

int box_update(uint32_t space_id, uint32_t index_id, const char *key, const char *key_end, const char *ops, const char *ops_end, int index_base, box_tuple_t **result)

Выполнение запроса обновления (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, если идентификаторы полей field_id с основанием 0, как в C, 1, если идентификаторы полей с основанием 1, как в Lua
  • result (box_tuple_t**) – аргумент вывода. Старый кортеж. Можно задать значение NULL для сброса результата
Результат:

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

0 в остальных случаях

See also: space_object.update()

int box_upsert(uint32_t space_id, uint32_t index_id, const char *tuple, const char *tuple_end, const char *ops, const char *ops_end, int index_base, box_tuple_t **result)

Выполнение запроса обновления и вставки (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, если идентификаторы полей field_id с основанием 0, как в C, 1, если идентификаторы полей с основанием 1, как в Lua
  • result (box_tuple_t**) – аргумент вывода. Старый кортеж. Можно задать значение NULL для сброса результата
Результат:

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

0 в остальных случаях

See also: space_object.upsert()

int box_truncate(uint32_t space_id)

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

Параметры:
  • space_id (uint32_t) – идентификатор спейса
int box_session_push(const char *data, const char *data_end)

С версии 2.4.1. Передача данных в формате MessagePack в канал данных сеанса — сокет, консоль или то, что используется в сеансе. Работает, как box.session.push() в Lua.

Параметры:
  • data (const char*) – начало данных для передачи
  • data_end (const char*) – конец данных для передачи
Результат:

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

0 в остальных случаях
int box_sequence_current(uint32_t seq_id, int64_t *result)

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

Параметры:
  • seq_id (uint32_t) – идентификатор последовательности
  • result (int64_t) – указатель на переменную, где будет храниться значение последовательности в случае успеха.
Результат:

0 при успехе и -1 в обратном случае. В случае ошибки, ее можно получить с помощью box_error_last().
uint32_t box_schema_version(void)

Since version 2.11.0. Return the database schema version. A schema version is a number that indicates whether the database schema is changed. For example, the schema_version value grows if a space or index is added or deleted, or a space, index, or field name is changed.

Результат:the database schema version
Тип результата:number

See also: box.info.schema_version and IPROTO_SCHEMA_VERSION

uint64_t box_session_id(void)

Since version 2.11.0. Return the unique identifier (ID) for the current session.

Результат:the session identifier; 0 or -1 if there is no session
Тип результата:number

See also: box.session.id()

int box_iproto_send(uint64_t sid, char *header, char *header_end[, char *body, char *body_end])

Since version 2.11.0. Send an IPROTO packet over the session’s socket with the given MsgPack header and body. The function yields. The function works for binary sessions only. For details, see box.session.type().

Параметры:
  • sid (uint32_t) – the IPROTO session identifier (see box_session_id())
  • header (char*) – a MsgPack-encoded header
  • header_end (char*) – end of a header encoded as MsgPack
  • body (char*) – a MsgPack-encoded body. If the body and body_end parameters are omitted, the packet consists of the header only.
  • body_end (char*) – end of a body encoded as MsgPack
Результат:

0 on success; -1 on error (check box_error_last())
Тип результата:

number

See also: box.iproto.send()

Possible errors:

  • ER_SESSION_CLOSED – the session is closed.
  • ER_NO_SUCH_SESSION – the session does not exist.
  • ER_MEMORY_ISSUE – out-of-memory limit has been reached.
  • ER_WRONG_SESSION_TYPE – the session type is not binary.

For details, see src/box/errcode.h.

Example

/* 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 0x30

char 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);
void box_iproto_override(uint32_t request_type, iproto_handler_t handler, iproto_handler_destroy_t destroy, void *ctx)

Since version 2.11.0. Set a new IPROTO request handler with the provided context for the given request type. The function yields.

Параметры:
  • request_type (uint32_t) –

    IPROTO request type code (for example, IPROTO_SELECT). For details, check Client-server requests and responses.

    To override the handler of unknown request types, use the IPROTO_UNKNOWN type code.

  • handler (iproto_handler_t) – IPROTO request handler. To reset the request handler, set the handler parameter to NULL. See the full parameter description in the Handler function section.
  • destroy (iproto_handler_destroy_t) – IPROTO request handler destructor. The destructor is called when the corresponding handler is removed. See the full parameter description in the Handler destructor function section.
  • ctx (void*) – a context passed to the handler and destroy callbacks
Результат:

0 on success; -1 on error (check box_error_last())
Тип результата:

number

See also: box.iproto.override()

Possible errors:

If a Lua handler throws an exception, the behavior is similar to that of a remote procedure call. The following errors are returned to the client over IPROTO (see src/lua/utils.h):

  • ER_PROC_LUA – an exception is thrown from a Lua handler, diagnostic is not set.
  • diagnostics from src/box/errcode.h – an exception is thrown, diagnostic is set.

For details, see src/box/errcode.h.

Handler function

The signature of a handler function (the handler parameter):

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);

where:

  • header (const char*) – a MsgPack-encoded header
  • header_end (const char*) – end of a header encoded as MsgPack
  • body (const char*) – a MsgPack-encoded body
  • header_end (const char*) – end of a body encoded as MsgPack

The handler returns a status code. Possible statuses:

  • IPROTO_REQUEST_HANDLER_OK – success
  • IPROTO_REQUEST_HANDLER_ERROR – error, diagnostic must be set by handler (see box_error_set() and box_error_raise())
  • IPROTO_REQUEST_HANDLER_FALLBACK – fallback to the default handler

Handler destructor function

The destructor is called when the handler is reset. The signature of a destructor function (the destroy parameter):

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

where:

  • ctx (void*): the context provided by box_iproto_override() function.

Examples

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)
Нашли ответ на свой вопрос?
Обратная связь
Справочник по C API
Module clock
Single-page version