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: - 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
-
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()
.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, 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.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)¶ 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()
.