C API

The public C API is declared in api/c/include/drava/drava_c.h. It is the interface the SWIG Python bindings wrap, and can be used directly from C/C++.

Typedefs

typedef enum drava_rcode_t drava_rcode_t

Return codes for Drava C API functions.

DRAVA_SUCCESS is zero; all others are positive error codes.

typedef enum drava_transport_t drava_transport_t

Transport backend used to move frames between stages.

Selected via transport.type in pipeline.yaml.

typedef enum drava_verbose_t drava_verbose_t

Log verbosity levels, ordered from most to least severe.

A message is emitted when its level is at or below the runtime’s configured verbosity.

typedef struct drava_frame_t drava_frame_t

A single frame delivered to a stage callback.

typedef struct drava_frame_batch_t drava_frame_batch_t

A batch of frames passed to the stage callback.

base_index is the global 0-based index of the first frame in this batch across the whole stream (EOS markers excluded). It lets a callback compute per-frame stream positions without keeping its own counter, which is what makes callbacks safe to run concurrently and out of order.

typedef struct drava_stats_t drava_stats_t

Cumulative per-stage counters, as returned by drava_stats_snapshot().

Derived quantities (throughput, average latency, energy) are computed from these; see the metrics documentation.

typedef void *(*drava_frame_routine_t)(const drava_frame_batch_t *batch, void *user_data)

Application callback invoked once per batch of received frames.

user_data is the pointer passed to drava_register_frame_routine(). The return value is currently unused.

typedef void (*drava_eos_routine_t)(uint64_t expected_frames, void *user_data)

End-of-stream routine type.

Invoked once by the runtime after the EOS marker has been observed and all in-flight data callbacks have drained. expected_frames is the frame count carried by the EOS marker (0 if the marker had no/invalid count).

Enums

enum drava_rcode_t

Return codes for Drava C API functions.

DRAVA_SUCCESS is zero; all others are positive error codes.

Values:

enumerator DRAVA_SUCCESS

Operation succeeded.

enumerator DRAVA_ERROR

Unspecified error.

enumerator DRAVA_EINVAL

Invalid argument.

enumerator DRAVA_ENOTSUP

Operation not supported (e.g.

transport not built in).

enum drava_transport_t

Transport backend used to move frames between stages.

Selected via transport.type in pipeline.yaml.

Values:

enumerator DRAVA_TRANSPORT_SOCKET

Unix-domain socket transport.

enumerator DRAVA_TRANSPORT_NATS

NATS JetStream transport.

enum drava_verbose_t

Log verbosity levels, ordered from most to least severe.

A message is emitted when its level is at or below the runtime’s configured verbosity.

Values:

enumerator DRAVA_VERBOSE_FATAL

Fatal error.

enumerator DRAVA_VERBOSE_ERROR

Error.

enumerator DRAVA_VERBOSE_WARN

Warning.

enumerator DRAVA_VERBOSE_INFO

Informational.

enumerator DRAVA_VERBOSE_IMPL

Implementation detail.

enumerator DRAVA_VERBOSE_DEBUG

Debug.

Functions

int drava_register_frame_routine(drava_frame_routine_t routine, void *user_data)

Register the per-batch frame callback.

Returns DRAVA_SUCCESS on success.

int drava_register_eos_routine(drava_eos_routine_t routine, void *user_data)

Register the optional end-of-stream callback (see drava_eos_routine_t).

int drava_init(void)

Initialize the runtime: apply the stage configuration and start the task runtime.

Returns DRAVA_ENOTSUP if the configured transport is unavailable.

int drava_listen(void)

Run the stage: receive frames and dispatch batches until end-of-stream.

int drava_publish(const void *data, size_t data_len)

Publish one payload downstream through the configured transport.

int drava_deinit(void)

Shut down the runtime and release resources.

int drava_log(const drava_verbose_t verbose_level, const char *msg)

Emit a log message at the given verbosity level.

int drava_stats_snapshot(drava_stats_t *out_stats)

Copy the current cumulative counters into out_stats.

int drava_stats_reset(void)

Reset all cumulative counters to zero.

int drava_set_callback_batch(size_t batch_size)

Override the number of frames grouped into each callback batch.

int drava_set_callback_flush_timeout_ms(int timeout_ms)

Override the idle-flush timeout (ms) for partial callback batches.

int drava_set_callback_serialize(int enabled)

Enable (1) or disable (0) serialized, single-threaded callback dispatch.

int drava_set_forward_eos(int enabled)

When enabled (default), the runtime re-publishes the EOS marker to the configured egress once the stream drains.

Terminal stages set this to 0.

int drava_payload_parse_eos(const void *data, size_t data_len, uint64_t *out_count)

Return non-zero if the payload is an EOS marker.

When it is and out_count is non-NULL, *out_count receives the frame count encoded after the prefix (0 if absent/invalid).

struct drava_frame_t

#include <drava_c.h>

A single frame delivered to a stage callback.

Public Members

uint64_t frame_id

Runtime-assigned monotonic frame id.

uint64_t recv_ts_ns

Receive timestamp at Drava ingress (ns).

const void *data

Frame payload bytes (not owned by the callback).

size_t data_len

Length of data in bytes.

struct drava_frame_batch_t

#include <drava_c.h>

A batch of frames passed to the stage callback.

base_index is the global 0-based index of the first frame in this batch across the whole stream (EOS markers excluded). It lets a callback compute per-frame stream positions without keeping its own counter, which is what makes callbacks safe to run concurrently and out of order.

Public Members

uint64_t batch_id

Runtime-assigned monotonic batch id.

uint32_t count

Number of frames in frames.

uint64_t base_index

Global index of the first frame in the batch.

const drava_frame_t *frames

Array of count frames.

struct drava_stats_t

#include <drava_c.h>

Cumulative per-stage counters, as returned by drava_stats_snapshot().

Derived quantities (throughput, average latency, energy) are computed from these; see the metrics documentation.

Public Members

uint64_t rx_msgs

Transport messages received.

uint64_t rx_items

Frames received (excludes EOS markers).

uint64_t rx_bytes

Bytes received.

uint64_t tx_msgs

Messages published downstream.

uint64_t tx_bytes

Bytes published downstream.

uint64_t callback_batches

Number of callback batches dispatched.

uint64_t callback_ns_sum

Total time spent in the callback (ns).

uint64_t callback_ns_max

Longest single callback (ns).

uint64_t publish_ns_sum

Total time spent publishing (ns).

uint64_t publish_ns_max

Longest single publish (ns).

uint64_t stage_latency_samples

Number of per-frame latency samples.

uint64_t stage_latency_ns_sum

Sum of per-frame stage latencies (ns).

uint64_t stage_latency_ns_max

Maximum per-frame stage latency (ns).

uint64_t first_rx_ns

Timestamp of the first received frame (ns).

uint64_t last_stage_ns

Timestamp of the last stage completion (ns).