Module box | Tarantool
Sign in Sign up
Download

Version:

latest (3.x)
Reference C API reference Module box

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.

Parameters:
Returns:

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

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 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().

Parameters:
  • 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.

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.

Parameters:
  • 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

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.

Parameters:
  • 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

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

Execute an INSERT/REPLACE request.

Parameters:
  • 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()

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

Execute a REPLACE request.

Parameters:
  • 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()

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.

Parameters:
  • 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()

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.

Parameters:
  • 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()

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.

Parameters:
  • 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()

int box_truncate(uint32_t space_id)

Truncate a space.

Parameters:
  • space_id (uint32_t) – space identifier
int box_session_push(const char *data, const char *data_end)

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().

Parameters:
  • 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
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.

Parameters:
  • 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().
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.

Returns:the database schema version
Return type: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.

Returns:the session identifier; 0 or -1 if there is no session
Return type: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().

Parameters:
  • 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 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.

Parameters:
  • 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)
Found what you were looking for?
Feedback
C API reference
Module clock
Single-page version