Top.Mail.Ru
Module box | Tarantool
 
Reference / C API reference / Module box
Reference / C API reference / Module box

Module box

Module box

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:
  • char* name (const) – 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
  • char* name (const) – 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
  • char* tuple (const) – encoded tuple in MsgPack Array format ([ field1, field2, …])
  • char* tuple_end (const) – 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
  • char* tuple (const) – encoded tuple in MsgPack Array format ([ field1, field2, …])
  • char* tuple_end (const) – 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
  • char* key (const) – encoded key in MsgPack Array format ([ field1, field2, …])
  • char* key_end (const) – 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
  • char* key (const) – encoded key in MsgPack Array format ([ field1, field2, …])
  • char* key_end (const) – end of a key
  • char* ops (const) – encoded operations in MsgPack Array format, e.g. [[ '=', field_id,  value ], ['!', 2, 'xxx']]
  • char* ops_end (const) – 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
  • char* tuple (const) – encoded tuple in MsgPack Array format ([ field1, field2, …])
  • char* tuple_end (const) – end of a tuple
  • char* ops (const) – encoded operations in MsgPack Array format, e.g. [[ '=', field_id,  value ], ['!', 2, 'xxx']]
  • char* ops_end (const) – 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)

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

Parameters:
  • char* data (const) – begin of MessagePack to push
  • char* data_end (const) – 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);

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