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 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(const vx_error *ptr)#

Free an owned vx_error object.

vx_view vx_error_message(const vx_error *error)#

Return error message for this error. Returned view is valid while “error” is valid.