Read views: C API
Enterprise Edition
This API is available in the Enterprise Edition only.
This topic describes the C API for working with read views. The C API is MT-safe and provides the ability to use a read view from any thread, not only from the main (TX) thread.
The C API has the following specifics:
- The space.upgrade function is not applied to retrieved tuples even if a space upgrade is in progress.
- Tuples stored in compressed spaces are not decompressed - they are returned as raw MessagePack (
MP_EXT/MP_COMPRESSION
).
Note
You can learn how to call C code using stored procedures in the C tutorial.
The opaque data types below represent raw read views and an iterator over data in a raw read view.
Note that there is no special data type for tuples retrieved from a read view.
Tuples are returned as raw MessagePack data (const char *
).
-
typedef box_raw_read_view
box_raw_read_view_t
¶ A raw database read view.
-
typedef box_raw_read_view_space
box_raw_read_view_space_t
¶ A space in a raw read view.
-
typedef box_raw_read_view_index
box_raw_read_view_index_t
¶ An index in a raw read view.
-
typedef box_raw_read_view_iterator
box_raw_read_view_iterator_t
¶ An iterator over data in a raw read view.
To create or destroy a read view, use the functions below.
-
box_raw_read_view_t *
box_raw_read_view_new
(const char *name)¶ Open a raw read view with the specified name and get a pointer to this read view. In the case of error, returns
NULL
and sets box_error_last(). This function may be called from the main (TX) thread only.Parameters: - *name (const char) –
(optional) a read view name; if
name
is not specified, a read view name is set tounknown
Returns: a pointer to a read view
- *name (const char) –
-
void
box_raw_read_view_delete
(box_raw_read_view_t *rv)¶ Close a raw read view and release all resources associated with it. This function may be called from the main (TX) thread only.
Parameters: - *rv (box_raw_read_view_t) –
a pointer to a read view
- *rv (box_raw_read_view_t) –
Note
Read views created using box_raw_read_view_new
are displayed in box.read_view.list() along with read views created in Lua.
To fetch data from a read view, you need to specify an index to fetch the data from. The following functions are available for looking up spaces and indexes in a read view object.
-
box_raw_read_view_space_t *
box_raw_read_view_space_by_id
(const box_raw_read_view_t *rv, uint32_t space_id)¶ Find a space by ID in a raw read view. If not found, returns
NULL
and sets box_error_last().Parameters: - *rv (const box_raw_read_view_t) –
a pointer to a read view
- space_id (uint32_t) – a space identifier
Returns: a pointer to a space
- *rv (const box_raw_read_view_t) –
-
box_raw_read_view_space_t *
box_raw_read_view_space_by_name
(const box_raw_read_view_t *rv, const char *space_name, uint32_t space_name_len)¶ Find a space by name in a raw read view. If not found, returns
NULL
and sets box_error_last().Parameters: - *rv (const box_raw_read_view_t) –
a pointer to a read view
- *space_name (const char) –
a space name
- space_name_len (uint32_t) – a space name length
Returns: a pointer to a space
- *rv (const box_raw_read_view_t) –
-
box_raw_read_view_index_t *
box_raw_read_view_index_by_id
(const box_raw_read_view_space_t *space, uint32_t index_id)¶ Find an index by ID in a read view’s space. If not found, returns
NULL
and sets box_error_last().Parameters: - *space (const box_raw_read_view_space_t) –
a pointer to a read view’s space
- space_id (uint32_t) – a space identifier
Returns: a pointer to an index
- *space (const box_raw_read_view_space_t) –
-
box_raw_read_view_index_t *
box_raw_read_view_index_by_name
(const box_raw_read_view_space_t *space, const char *index_name, uint32_t index_name_len)¶ Find an index by name in a read view’s space. If not found, returns
NULL
and sets box_error_last().Parameters: - *space (const box_raw_read_view_space_t) –
a pointer to a space
- *index_name (const char) –
an index name
- index_name_len (uint32_t) – an index name length
Returns: a pointer to an index
- *space (const box_raw_read_view_space_t) –
The functions below provide the ability to look up a tuple by the key or create an iterator over a read view index.
Note
Methods of the read view iterator are safe to call from any thread, but they may be used in one thread at the same time. This means that an iterator should be thread-local.
-
int
box_raw_read_view_get
(const box_raw_read_view_index_t *index, const char *key, const char *key_end, const char **data, uint32_t *size)¶ Look up a tuple in a read view’s index. If found, the
data
andsize
out arguments return a pointer to and the size of tuple data. If not found,*data
is set toNULL
and*size
is set to0
.Parameters: - *index (const box_raw_read_view_index_t) –
a pointer to a read view’s index
- *key (const char) –
a pointer to the first byte of the MsgPack data that represents the search key
- *key_end (const char) –
a pointer to the byte following the last byte of the MsgPack data that represents the search key
- **data (const char) –
a pointer to the tuple data
- *size (uint32_t) –
the size of tuple data
Returns: 0
on success; in the case of error, returns-1
and sets box_error_last()- *index (const box_raw_read_view_index_t) –
-
int
box_raw_read_view_iterator_create
(box_raw_read_view_iterator_t *it, const box_raw_read_view_index_t *index, int type, const char *key, const char *key_end)¶ Create an iterator over a raw read view index. The initialized iterator object returned by this function remains valid and may be safely used until it’s destroyed or the read view is closed. When the iterator object is no longer needed, it should be destroyed using box_raw_read_view_iterator_destroy().
Parameters: - *it (box_raw_read_view_iterator_t) –
an iterator over a raw read view index
- *index (const box_raw_read_view_index_t) –
a pointer to a read view index
- type (int) – an iteration direction represented by the iterator_type
- *key (const char) –
a pointer to the first byte of the MsgPack data that represents the search key
- *key_end (const char) –
a pointer to the byte following the last byte of the MsgPack data that represents the search key
Returns: 0
on success; in the case of error, returns-1
and sets box_error_last()- *it (box_raw_read_view_iterator_t) –
-
int
box_raw_read_view_iterator_next
(box_raw_read_view_iterator_t *it, const char **data, uint32_t *size)¶ Retrieve the current tuple and advance the given iterator over a raw read view index. The pointer to and the size of tuple data are returned in the
data
and thesize
out arguments. The data returned by this function remains valid and may be safely used until the read view is closed.Parameters: - *it (box_raw_read_view_iterator_t) –
an iterator over a read view index
- **data (const char) –
a pointer to the tuple data; at the end of iteration,
*data
is set toNULL
- *size (uint32_t) –
the size of tuple data; at the end of iteration,
*size
is set to0
Returns: 0
on success; in the case of error, returns-1
and sets box_error_last()- *it (box_raw_read_view_iterator_t) –
-
void
box_raw_read_view_iterator_destroy
(box_raw_read_view_iterator_t *it)¶ Destroy an iterator over a raw read view index. The iterator object should not be used after calling this function, but the data returned by the iterator may be safely dereferenced until the read view is closed.
Parameters: - *it (box_raw_read_view_iterator_t) –
an iterator over a read view index
- *it (box_raw_read_view_iterator_t) –
A space object’s methods below provide the ability to get names and types of space fields.
-
uint32_t
box_raw_read_view_space_field_count
(const box_raw_read_view_space_t *space)¶ Get the number of fields defined in the format of a read view space.
Parameters: - *space (const box_raw_read_view_space_t) –
a pointer to a read view space
Returns: the number of fields
- *space (const box_raw_read_view_space_t) –
-
const char *
box_raw_read_view_space_field_name
(const box_raw_read_view_space_t *space, uint32_t field_no)¶ Get the name of a field defined in the format of a read view space. If the field number is greater than the total number of fields defined in the format,
NULL
is returned. The string returned by this function is guaranteed to remain valid until the read view is closed.Parameters: - *space (const box_raw_read_view_space_t) –
a pointer to a read view space
- field_no (uint32_t) – the field number (starts with
0
)
Returns: the name of a field
- *space (const box_raw_read_view_space_t) –
-
const char *
box_raw_read_view_space_field_type
(const box_raw_read_view_space_t *space, uint32_t field_no)¶ Get the type of a field defined in the format of a read view space. If the field number is greater than the total number of fields defined in the format,
NULL
is returned. The string returned by this function is guaranteed to remain valid until the read view is closed.Parameters: - *space (const box_raw_read_view_space_t) –
a pointer to a read view space
- field_no (uint32_t) – the field number (starts with
0
)
Returns: the type of a field
- *space (const box_raw_read_view_space_t) –