Read views: C API

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

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

A raw database read view.

A space in a raw read view.

An index in a raw read view.

An iterator over data in a raw read view.

To create or destroy a read view, use the functions below.

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

Close a raw read view and release all resources associated with it. This function may be called from the main (TX) thread only.

• *rv (box_raw_read_view_t) — a pointer to a read view

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.

Find a space by ID in a raw read view. If not found, returns NULL and sets box_error_last().

• *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

Find a space by name in a raw read view. If not found, returns NULL and sets box_error_last().

• *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

Find an index by ID in a read view's space. If not found, returns NULL and sets box_error_last().

• *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

Find an index by name in a read view's space. If not found, returns NULL and sets box_error_last().

• *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

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

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.

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

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

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

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.

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

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.

• *it (box_raw_read_view_iterator_t) — an iterator over a read view index

A space object's methods below provide the ability to get names and types of space fields.

Get the number of fields defined in the format of a read view space.

• *space (const box_raw_read_view_space_t) — a pointer to a read view space

Returns

the number of fields

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.

• *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

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.

• *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