C API#

The Vortex C API provides a low-level FFI interface to the Vortex library. It is the foundation for other language bindings (including C++) and is suitable for embedding Vortex into C applications or building higher-level wrappers.

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.

Installation#

The C API is provided as a static or shared library built from the vortex-ffi crate. To build it:

cargo build -p vortex-ffi

The generated header file vortex.h and compiled library can then be linked into your C project.

Compatibility#

The C bindings are supported on the following architectures:

x86_64 Linux
ARM64 Linux
Apple Silicon macOS

They support any Linux distribution with a GLIBC version >= 2.31. This includes

Amazon Linux 2022 or newer
Ubuntu 20.04 or newer

API Reference#

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 handle to a Vortex 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.

The logger will only be installed on the first call.

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 the error message from the given Vortex error.

The returned pointer is valid as long as the error is valid. Do NOT free the returned string pointer - it shares the lifetime of the 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.