Vortex FFI API

Warning

This API should be considered entirely unstable. It _will_ change. Please reach out if a stable FFI API is important for your use-case and we can accelerate the process of stabilizing it.

• DTypes
• Arrays

Session

While not all parts of Vortex require a session, many do. A Vortex session object holds registries of extensible types, such as array encodings, layout encodings, extension dtypes, compute functions, and more.

type vx_session

A Vortex session stores registries of extensible types, various caches, and other top-level configuration.

Extensible types include array encodings, layouts, extension dtypes, compute functions, etc.

Multiple sessions may be created in a single process, and individual arrays are not tied to a specific session.

void vx_session_free(vx_session *ptr)

Free an owned vx_session object.

vx_session *vx_session_new(void)

Create a new Vortex session.

The caller is responsible for freeing the session with vx_session_free().

Logging

void vx_set_log_level(vx_log_level level)

Set the stderr logger to output at the specified level.

This function is optional, if it is not called then no logger will be installed.

enum vx_log_level

Log levels for the Vortex library.

enumerator LOG_LEVEL_OFF = 0

No logging will be performed.

enumerator LOG_LEVEL_ERROR = 1

Only error messages will be logged.

enumerator LOG_LEVEL_WARN = 2

Warnings and error messages will be logged.

enumerator LOG_LEVEL_INFO = 3

Informational messages, warnings, and error messages will be logged.

enumerator LOG_LEVEL_DEBUG = 4

Debug messages, informational messages, warnings, and error messages will be logged.

enumerator LOG_LEVEL_TRACE = 5

All messages, including trace messages, will be logged.

Errors

Errors are passed out of many function in the Vortex C API. Each time they will be heap-allocated and the caller is responsible for freeing them.

type vx_error

The error structure populated by fallible Vortex C functions.

void vx_error_free(vx_error *ptr)

Free an owned vx_error object.

const vx_string *vx_error_get_message(const vx_error *error)

Returns a borrowed reference to the error message from the given Vortex error.

Strings

Vortex strings wrap a Rust Arc<str>, and therefore are reference-counted, UTF-8 encoded, and not null-terminated.

type vx_string

Strings for use within Vortex.

const vx_string *vx_string_clone(const vx_string *ptr)

Clone a borrowed vx_string, returning an owned vx_string.

Must be released with vx_string_free().

void vx_string_free(const vx_string *ptr)

Free an owned vx_string object.

const vx_string *vx_string_new(const char *ptr, size_t len)

Create a new Vortex UTF-8 string by copying from a pointer and length.

const vx_string *vx_string_new_from_cstr(const char *ptr)

Create a new Vortex UTF-8 string by copying from a null-terminated C-style string.

size_t vx_string_len(const vx_string *ptr)

Return the length of the string in bytes.

const char *vx_string_ptr(const vx_string *ptr)

Return the pointer to the string data.