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(const vx_session *ptr)¶: Free a vx_session

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(const vx_error *ptr)¶: Free a vx_error

vx_view vx_error_message(const vx_error *error)¶: Return error message for this error. Returned view is valid while “error” is valid.