Read views: C API | Tarantool
Reference C API reference Read views: C API

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:

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 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:

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

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:
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

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 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:

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:
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

Found what you were looking for?
Feedback