Read views: C API

Data types

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.

Creating and destroying read views

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 to unknown
Returns:	a pointer to a read view

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

Spaces and indexes

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

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

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

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

Iteration and lookup

The functions below provide the ability to look up a tuple by the key or create an iterator over a read view index.

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 and size out arguments return a pointer to and the size of tuple data. If not found, *data is set to NULL and *size is set to 0.

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

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

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 the size 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 to NULL *size (uint32_t) – the size of tuple data; at the end of iteration, *size is set to 0
Returns:	0 on success; in the case of error, returns -1 and sets box_error_last()

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

Space format

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

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

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