Module box
-
type
box_function_ctx_t
¶ Opaque structure passed to a C stored procedure
-
int
box_return_tuple
(box_function_ctx_t *ctx, box_tuple_t *tuple)¶ 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.Параметры: - ctx (box_function_ctx_t*) – an opaque structure passed to the C stored procedure by Tarantool
- tuple (box_tuple_t*) – a tuple to return
Результат: -1 on error (perhaps, out of memory; check box_error_last())
Результат: 0 otherwise
-
int
box_return_mp
(box_function_ctx_t *ctx, const char *mp, const char *mp_end)¶ 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 thanbox_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 viabox_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
Результат: -1 on error (perhaps, out of memory; check box_error_last())
Результат: 0 otherwise
For example, if
mp
is a buffer, andmp_end
is a return value produced by encoding a single MP_UINT scalar value withmp_end=mp_encode_uint(mp,1);
, thenbox_return_mp(ctx,mp,mp_end);
should return0
.
-
uint32_t
box_space_id_by_name
(const char *name, uint32_t len)¶ 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
Результат: BOX_ID_NIL
on error or if not found (check box_error_last())Результат: space_id otherwise
See also:
box_index_id_by_name
-
uint32_t
box_index_id_by_name
(uint32_t space_id, const char *name, uint32_t len)¶ 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
Результат: BOX_ID_NIL
on error or if not found (check box_error_last())Результат: space_id otherwise
See also:
box_space_id_by_name
-
int
box_insert
(uint32_t space_id, const char *tuple, const char *tuple_end, box_tuple_t **result)¶ 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
Результат: -1 on error (check box_error_last())
Результат: 0 otherwise
See also: space_object.insert()
-
int
box_replace
(uint32_t space_id, const char *tuple, const char *tuple_end, box_tuple_t **result)¶ 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
Результат: -1 on error (check box_error_last())
Результат: 0 otherwise
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)¶ 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
Результат: -1 on error (check box_error_last())
Результат: 0 otherwise
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)¶ 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
Результат: -1 on error (check box_error_last())
Результат: 0 otherwise
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)¶ 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
Результат: -1 on error (check box_error_last())
Результат: 0 otherwise
See also: space_object.upsert()
-
int
box_truncate
(uint32_t space_id)¶ Truncate a space.
Параметры: - space_id (uint32_t) – space identifier
-
int
box_session_push
(const char *data, const char *data_end)¶ 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
Результат: -1 on error (check box_error_last())
Результат: 0 otherwise
-
int
box_sequence_current
(uint32_t seq_id, int64_t *result)¶ 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.
Результат: 0 on success and -1 otherwise. In case of an error user could get it via
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
andbody_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 toNULL
. 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
anddestroy
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.
- request_type (uint32_t) –
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 headerheader_end
(const char*) – end of a header encoded as MsgPackbody
(const char*) – a MsgPack-encoded bodyheader_end
(const char*) – end of a body encoded as MsgPackThe handler returns a status code. Possible statuses:
IPROTO_REQUEST_HANDLER_OK
– successIPROTO_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 bybox_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)