Module box

Opaque structure passed to a C stored procedure

Return a tuple from a C stored procedure.

The returned tuple is automatically reference-counted by Tarantool. An example program that uses box_return_tuple() is write.c.

Parameters:

• ctx (box_function_ctx_t*) — an opaque structure passed to the C stored procedure by Tarantool

• tuple (box_tuple_t*) — a tuple to return

Returns

-1 on error (perhaps, out of memory; check box_error_last())

Returns

0 otherwise

Return a pointer to a series of bytes in MessagePack format.

This can be used instead of box_return_tuple() – it can send the same value, but as MessagePack instead of as a tuple object. It may be simpler than box_return_tuple() when the result is small, for example a number or a boolean or a short string. It will also be faster than box_return_tuple(), if the result is that users save time by not creating a tuple every time they want to return something from a C function.

On the other hand, if an already-existing tuple was obtained from an iterator, then it would be faster to return the tuple via box_return_tuple() rather than extracting its parts and sending them via box_return_mp().

• ctx (box_function_ctx_t*) — an opaque structure passed to the C stored procedure by Tarantool

• mp (char*) — the first MessagePack byte

• mp_end (char*) — after the last MessagePack byte

Returns

-1 on error (perhaps, out of memory; check box_error_last())

Returns

0 otherwise

For example, if mp is a buffer, and mp_end is a return value produced by encoding a single MP_UINT scalar value with mp_end=mp_encode_uint(mp,1);, then box_return_mp(ctx,mp,mp_end); should return 0.

Find space id by name.

This function performs a SELECT request on the _vspace system space.

• name (const char*) — space name

• len (uint32_t) — length of name

Returns

BOX_ID_NIL on error or if not found (check box_error_last())

Returns

space_id otherwise

See also: box_index_id_by_name

Find index id by name.

This function performs a SELECT request on the _vindex system space.

• space_id (uint32_t) — space identifier

• name (const char*) — index name

• len (uint32_t) — length of name

Returns

BOX_ID_NIL on error or if not found (check box_error_last())

Returns

space_id otherwise

See also: box_space_id_by_name

Execute an INSERT/REPLACE request.

• space_id (uint32_t) — space identifier

• tuple (const char*) — encoded tuple in MsgPack Array format ([ field1, field2, ...])

• tuple_end (const char*) — end of a tuple

• result (box_tuple_t**) — output argument. Resulting tuple. Can be set to NULL to discard result

Returns

-1 on error (check box_error_last())

Returns

0 otherwise

See also: space_object.insert()

Execute a REPLACE request.

• space_id (uint32_t) — space identifier

• tuple (const char*) — encoded tuple in MsgPack Array format ([ field1, field2, ...])

• tuple_end (const char*) — end of a tuple

• result (box_tuple_t**) — output argument. Resulting tuple. Can be set to NULL to discard result

Returns

-1 on error (check box_error_last())

Returns

0 otherwise

See also: space_object.replace()

Execute a DELETE request.

• space_id (uint32_t) — space identifier

• index_id (uint32_t) — index identifier

• key (const char*) — encoded key in MsgPack Array format ([ field1, field2, ...])

• key_end (const char*) — end of a key

• result (box_tuple_t**) — output argument. An old tuple. Can be set to NULL to discard result

Returns

-1 on error (check box_error_last())

Returns

0 otherwise

See also: space_object.delete()

Execute an UPDATE request.

• space_id (uint32_t) — space identifier

• index_id (uint32_t) — index identifier

• key (const char*) — encoded key in MsgPack Array format ([ field1, field2, ...])

• key_end (const char*) — end of a key

• ops (const char*) — encoded operations in MsgPack Array format, e.g. [[ '=', field_id, value ], ['!', 2, 'xxx']]

• ops_end (const char*) — end of an ops section

• index_base (int) — 0 if field_ids are zero-based as in C, 1 if field ids are 1-based as in Lua

• result (box_tuple_t**) — output argument. An old tuple. Can be set to NULL to discard result

Returns

-1 on error (check box_error_last())

Returns

0 otherwise

See also: space_object.update()

Execute an UPSERT request.

• space_id (uint32_t) — space identifier

• index_id (uint32_t) — index identifier

• tuple (const char*) — encoded tuple in MsgPack Array format ([ field1, field2, ...])

• tuple_end (const char*) — end of a tuple

• ops (const char*) — encoded operations in MsgPack Array format, e.g. [[ '=', field_id, value ], ['!', 2, 'xxx']]

• ops_end (const char*) — end of a ops

• index_base (int) — 0 if field_ids are zero-based as in C, 1 if field ids are 1-based as in Lua

• result (box_tuple_t**) — output argument. An old tuple. Can be set to NULL to discard result

Returns

-1 on error (check box_error_last())

Returns

0 otherwise

See also: space_object.upsert()

Truncate a space.

• space_id (uint32_t) — space identifier

Deprecated since 3.0.0.

Since version 2.4.1. Push MessagePack data into a session data channel – socket, console or whatever is behind the session. Behaves just like Lua box.session.push().

• data (const char*) — begin of MessagePack to push

• data_end (const char*) — end of MessagePack to push

Returns

-1 on error (check box_error_last())

Returns

0 otherwise

Since version 2.4.1. Return the last retrieved value of the specified sequence.

• seq_id (uint32_t) — sequence identifier

• result (int64_t) — pointer to a variable where the current sequence value will be stored on success.

Returns

0 on success and -1 otherwise. In case of an error user could get it via box_error_last().

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.

Returns

the database schema version

Return type

number

See also: box.info.schema_version and IPROTO_SCHEMA_VERSION

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

Returns

the session identifier; 0 or -1 if there is no session

Return type

number

See also: box.session.id()

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

Returns

0 on success; -1 on error (check box_error_last())

Return type

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

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

Returns

0 on success; -1 on error (check box_error_last())

Return type

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)