Crate of_ffi_c

Expand description

§of_ffi_c

of_ffi_c exposes a stable C ABI for embedding the Orderflow runtime in non-Rust environments. It is the native interface used by Python (ctypes), Java (JNA), and any C-compatible host runtime.

§ABI Surface

Engine lifecycle: of_engine_create, of_engine_start, of_engine_stop, of_engine_destroy
Subscription: of_subscribe, of_unsubscribe, of_unsubscribe_symbol, of_reset_symbol_session
External ingest and supervision: of_ingest_trade, of_ingest_book, of_configure_external_feed, of_external_set_reconnecting, of_external_health_tick
Polling and snapshots: of_engine_poll_once, of_get_book_snapshot, of_get_analytics_snapshot, of_get_derived_analytics_snapshot, of_get_session_candle_snapshot, of_get_interval_candle_snapshot, of_get_signal_snapshot
Metrics and memory management: of_get_metrics_json, of_string_free

§New In 0.4.0

0.4.0 keeps all existing analytics/runtime C ABI symbols valid and adds a separate execution ABI family. Existing hosts that only call of_engine_create, subscribe, poll, ingest, and read snapshots do not need to change those call sites.

New execution ABI concepts:

of_execution_engine_t: synchronous simulated execution handle
of_execution_engine_create and of_execution_engine_create_multi: single-route and multi-route construction
of_execution_submit_order, of_execution_cancel_order, of_execution_amend_order, and of_execution_poll
of_execution_order_state, of_execution_health, and of_execution_metrics
of_execution_concurrent_engine_t: bounded worker for many command producers and one deterministic execution owner
of_execution_command_report_t: typed command completion report with a caller-owned event buffer

The execution ABI is additive and intentionally separate from the market-data engine ABI. That separation lets C, Python, Java, and other FFI users adopt OMS workflows without destabilizing existing analytics deployments.

Version policy:

of_ffi_c publishes as 0.4.0 with the established native library line;
the Rust execution crates behind the ABI publish as 0.1.0;
native headers and libraries should still be upgraded together.

§Public ABI Inventory

Public C structs/types:

of_engine_config_t
of_symbol_t
of_trade_t
of_book_t
of_external_feed_policy_t
of_error_t
of_engine
of_subscription
of_event_t
of_event_cb

Exported C functions:

of_api_version
of_build_info
of_engine_create
of_engine_start
of_engine_stop
of_engine_destroy
of_subscribe
of_unsubscribe
of_unsubscribe_symbol
of_reset_symbol_session
of_ingest_trade
of_ingest_book
of_configure_external_feed
of_external_set_reconnecting
of_external_health_tick
of_get_book_snapshot
of_get_analytics_snapshot
of_get_derived_analytics_snapshot
of_get_session_candle_snapshot
of_get_interval_candle_snapshot
of_get_signal_snapshot
of_get_metrics_json
of_string_free
of_engine_poll_once

of_get_book_snapshot returns a materialized JSON snapshot with:

venue
symbol
bids
asks
last_sequence
ts_exchange_ns
ts_recv_ns

of_get_derived_analytics_snapshot returns additive session metrics with:

total_volume
trade_count
vwap
average_trade_size
imbalance_bps

of_get_session_candle_snapshot returns candle-style session state with:

open
high
low
close
trade_count
first_ts_exchange_ns
last_ts_exchange_ns

of_get_interval_candle_snapshot returns rolling-window candle state for a caller-supplied window_ns with:

window_ns
open
high
low
close
trade_count
total_volume
vwap
first_ts_exchange_ns
last_ts_exchange_ns

Subscription stream ids:

1: BOOK raw book updates
2: TRADES raw trade prints
3: ANALYTICS snapshot callbacks
4: SIGNALS snapshot callbacks
5: HEALTH transition callbacks
6: BOOK_SNAPSHOT materialized book snapshot callbacks after book changes
7: DERIVED_ANALYTICS session-derived analytics callbacks after trade changes

§C Struct Reference

of_engine_config_t:

instance_id: optional runtime instance id override
config_path: optional .toml or .json runtime config path
log_level: reserved for host integrations
enable_persistence: non-zero enables persistence
audit_max_bytes: audit rotation size
audit_max_files: audit retention count
audit_redact_tokens_csv: comma-separated audit redaction tokens
data_retention_max_bytes: persistence byte cap
data_retention_max_age_secs: persistence age cap in seconds

of_symbol_t:

venue: venue/exchange name
symbol: normalized symbol string
depth_levels: requested book depth for subscribe calls

of_trade_t:

symbol: embedded of_symbol_t
price, size: integer-normalized trade values
aggressor_side: one of OF_SIDE_BID or OF_SIDE_ASK
sequence: venue sequence or 0 when unavailable
ts_exchange_ns, ts_recv_ns: exchange and local timestamps

of_book_t:

symbol: embedded of_symbol_t
side: one of OF_SIDE_BID or OF_SIDE_ASK
level: top-of-book-relative depth index
price, size: integer-normalized book values
action: one of OF_BOOK_ACTION_UPSERT or OF_BOOK_ACTION_DELETE
sequence: venue sequence or 0 when unavailable
ts_exchange_ns, ts_recv_ns: exchange and local timestamps

of_external_feed_policy_t:

stale_after_ms: max allowed ingest silence before stale status
enforce_sequence: non-zero enables sequence-gap/out-of-order checks

of_event_t callback envelope:

kind: stream kind id
payload / payload_len: UTF-8 JSON payload bytes
schema_id: payload schema id, currently 1
quality_flags: OF_DQ_* bits associated with the event
timestamps are copied from the underlying event when available

§Function Family Reference

Lifecycle:

of_engine_create
of_engine_start
of_engine_stop
of_engine_destroy

Subscription:

of_subscribe
of_unsubscribe
of_unsubscribe_symbol
of_reset_symbol_session

External ingest and supervision:

of_ingest_trade
of_ingest_book
of_configure_external_feed
of_external_set_reconnecting
of_external_health_tick

Polling and snapshots:

of_engine_poll_once
of_get_book_snapshot
of_get_analytics_snapshot
of_get_derived_analytics_snapshot
of_get_session_candle_snapshot
of_get_interval_candle_snapshot
of_get_signal_snapshot

When the runtime backpressure limit is enabled through OF_RUNTIME_MAX_EVENTS_PER_POLL, of_engine_poll_once returns OF_ERR_BACKPRESSURE if a poll drains more events than the configured limit.

Metadata and ownership helpers:

of_api_version
of_build_info
of_get_metrics_json
of_string_free

§Safety Contract

Callers must:

pass valid non-null pointers for required pointer arguments
pass UTF-8 char* values where strings are expected
preserve pointer validity for the full duration of each call
free owned strings returned by the API using of_string_free

Additional ownership rules:

snapshot getters that write into caller buffers do not allocate for the caller
functions returning owned char* require of_string_free
callback payload pointers are only valid for the duration of the callback
opaque of_engine_t* and of_subscription_t* handles must be destroyed/unsubscribed only through exported API calls

§Minimal C Example

#include "orderflow.h"

int main(void) {
    of_engine_t* engine = NULL;
    of_engine_config_t cfg = {0};
    cfg.instance_id = "demo";

    int32_t rc = of_engine_create(&cfg, &engine);
    if (rc != OF_OK) return 1;

    rc = of_engine_start(engine);
    if (rc != OF_OK) {
        of_engine_destroy(engine);
        return 2;
    }

    of_engine_stop(engine);
    of_engine_destroy(engine);
    return 0;
}

§Error Semantics

Most functions return int32_t values mapped from of_error_t:

OF_OK for success
OF_ERR_INVALID_ARG for invalid pointers/inputs
OF_ERR_STATE for lifecycle misuse or invalid runtime state
OF_ERR_IO, OF_ERR_DATA_QUALITY, and other domain-specific failures

§Snapshot and Callback Payload Contracts

of_get_book_snapshot(...) and BOOK_SNAPSHOT callbacks share the same JSON schema
of_get_derived_analytics_snapshot(...) and DERIVED_ANALYTICS callbacks share the same JSON schema
of_get_session_candle_snapshot(...) and of_get_interval_candle_snapshot(...) are additive snapshot families and do not alter the older analytics/signal contracts
inout_len is both input capacity and output required size; if the buffer is too small, retry with the returned byte count
payload field names are treated as stable once published; new fields are added additively

§Integration Notes

Treat engine and subscription handles as opaque; do not cast or inspect internals.
Keep ABI structs initialized (zero-init is recommended before setting fields).
Prefer explicit timestamps and sequence numbers for external ingest to maximize quality checks.
Snapshot functions write the required byte length back through inout_len; if the caller buffer is too small, retry with the returned size.
BOOK_SNAPSHOT callbacks emit the same JSON shape as of_get_book_snapshot(...), but only when book state changes for the subscribed symbol.
DERIVED_ANALYTICS callbacks emit the same JSON shape as of_get_derived_analytics_snapshot(...), but only when trade-driven analytics change for the subscribed symbol.

§Real-World Use Cases

§1. Embed the runtime in a C or C++ trading host

Use the lifecycle, subscription, and polling APIs directly from a native host process that already owns process supervision and deployment.

§2. Drive Python or Java bindings from the same native ABI

The Python and Java packages both rely on this ABI, so host-side operators can reason about one native contract instead of three unrelated APIs.

§3. Build a custom host-side event pump

Use callbacks for snapshot/event delivery and poll-driven control for host-side scheduling.

§Detailed Example: Poll And Read Snapshots

#include "orderflow.h"
#include <stdint.h>
#include <stdio.h>

int main(void) {
  of_engine_t* engine = NULL;
  of_engine_config_t cfg = {0};
  cfg.instance_id = "native-demo";

  if (of_engine_create(&cfg, &engine) != OF_OK) return 1;
  if (of_engine_start(engine) != OF_OK) return 2;

  of_symbol_t symbol = {0};
  symbol.venue = "SIM";
  symbol.symbol = "ESM6";
  symbol.depth_levels = 10;

  if (of_subscribe(engine, &symbol, OF_STREAM_ANALYTICS, NULL, NULL, NULL) != OF_OK) return 3;

  if (of_engine_poll_once(engine, OF_DQ_NONE) != OF_OK) return 4;

  char buf[2048];
  uint32_t len = (uint32_t)sizeof(buf);
  if (of_get_analytics_snapshot(engine, &symbol, buf, &len) == OF_OK) {
    printf("analytics: %.*s\n", (int)len, buf);
  }

  len = (uint32_t)sizeof(buf);
  if (of_get_book_snapshot(engine, &symbol, buf, &len) == OF_OK) {
    printf("book: %.*s\n", (int)len, buf);
  }

  of_engine_stop(engine);
  of_engine_destroy(engine);
  return 0;
}

Prefer explicit timestamps and sequence numbers for external ingest to maximize quality checks.
Snapshot functions write the required byte length back through inout_len; if the caller buffer is too small, retry with the returned size.
BOOK_SNAPSHOT callbacks emit the same JSON shape as of_get_book_snapshot(...), but only when book state changes for the subscribed symbol.
DERIVED_ANALYTICS callbacks emit the same JSON shape as of_get_derived_analytics_snapshot(...), but only when trade-driven analytics change for the subscribed symbol.

Structs§

of_analytics_config_t: Analytics configuration passed to of_engine_set_analytics_config.
of_book_t: External order-book payload accepted by of_ingest_book.
of_engine: Opaque engine handle.
of_engine_config_t: Engine configuration passed to of_engine_create.
of_event_t: Event envelope dispatched to subscription callbacks.
of_execution_amend_request_t: Execution amend request.
of_execution_cancel_request_t: Execution cancel request.
of_execution_command_report_t: Concurrent execution command report.
of_execution_concurrent_config_t: Concurrent execution worker configuration.
of_execution_concurrent_engine: Opaque concurrent execution engine handle.
of_execution_engine: Opaque execution engine handle.
of_execution_event_t: Execution event returned by execution C APIs.
of_execution_health_t: Execution health snapshot.
of_execution_metrics_t: Execution metrics snapshot.
of_execution_order_request_t: Execution order request.
of_execution_order_state_t: Execution order state returned by state query.
of_execution_route_config_t: Execution route and risk configuration.
of_external_feed_policy_t: External-feed quality policy configured via of_configure_external_feed.
of_subscription: Opaque subscription token.
of_symbol_t: Symbol descriptor used by subscription and snapshot functions.
of_trade_t: External trade payload accepted by of_ingest_trade.

Enums§

of_error_t: Error codes returned by C ABI functions.

Functions§

of_api_version: Returns ABI version (major << 16 | minor style encoding).
of_build_info: Returns build/version info as a static NUL-terminated C string.
of_compute_depth_slope: Computes depth slope for the first levels price levels and writes JSON result.
of_compute_lob_features: Computes LOB feature snapshot from engine book state and caller-provided flow metrics.
of_compute_weighted_average_price: Computes weighted average price for an order of qty and writes JSON result.
of_configure_external_feed: Configures stale/sequence policy for external ingest mode.
of_engine_create: Creates a runtime engine and stores it in out_engine.
of_engine_destroy: Destroys an engine created by of_engine_create.
of_engine_poll_once: Polls adapter once and dispatches subscription callbacks.
of_engine_set_analytics_config: Override analytics thresholds and buffer sizes at runtime. Pass a pointer to a populated analytics config. Passing NULL resets to defaults.
of_engine_set_tickbar_interval: Sets the tickbar aggregation interval for new per-symbol accumulators.
of_engine_start: Starts adapter polling/session for a created engine.
of_engine_stop: Stops adapter polling/session for an engine.
of_execution_amend_order: Amends an execution order.
of_execution_api_version: Returns execution ABI version (major << 16 | minor style encoding).
of_execution_cancel_order: Cancels an execution order.
of_execution_concurrent_amend_order: Sends a non-blocking amend command to a concurrent execution worker.
of_execution_concurrent_cancel_order: Sends a non-blocking cancel command to a concurrent execution worker.
of_execution_concurrent_engine_create_multi: Creates and starts a concurrent simulated execution engine.
of_execution_concurrent_engine_destroy: Destroys a concurrent execution engine.
of_execution_concurrent_poll: Sends a non-blocking poll command to a concurrent execution worker.
of_execution_concurrent_stop: Requests graceful concurrent execution worker stop.
of_execution_concurrent_submit_order: Sends a non-blocking submit command to a concurrent execution worker.
of_execution_concurrent_try_recv_report: Attempts to receive one concurrent command report without blocking.
of_execution_engine_create: Creates a simulated execution engine and stores it in out_engine.
of_execution_engine_create_multi: Creates a simulated execution engine from multiple route configs.
of_execution_engine_destroy: Destroys an execution engine.
of_execution_engine_start: Starts an execution engine.
of_execution_engine_stop: Stops an execution engine.
of_execution_get_order_state: Gets current order state for a client order id.
of_execution_health: Gets execution health.
of_execution_metrics: Gets execution metrics.
of_execution_poll: Polls execution events.
of_execution_submit_order: Submits an execution order.
of_external_health_tick: Re-evaluates external feed health without ingesting new events.
of_external_set_reconnecting: Marks external feed reconnecting state.
of_get_acd_snapshot: Writes an analytics snapshot JSON payload into the caller-provided buffer.
of_get_agent_type_snapshot: Writes an analytics snapshot JSON payload into the caller-provided buffer.
of_get_almgren_chriss_snapshot: Writes an analytics snapshot JSON payload into the caller-provided buffer.
of_get_amihud_snapshot: Writes Amihud illiquidity snapshot JSON.
of_get_analytics_snapshot: Writes current analytics snapshot JSON into caller buffer.
of_get_bar_series: Writes completed bar series JSON array into caller buffer.
of_get_book_analytics_snapshot: Writes current book analytics snapshot JSON into caller buffer.
of_get_book_event_analytics: Writes book-event analytics snapshot JSON over window_ns.
of_get_book_snapshot: Writes current book snapshot JSON into caller buffer.
of_get_cvd_enhancement_snapshot: Writes CVD enhancement snapshot JSON.
of_get_dark_lit_correlation_snapshot: Writes an analytics snapshot JSON payload into the caller-provided buffer.
of_get_dark_pool_snapshot: Writes an analytics snapshot JSON payload into the caller-provided buffer.
of_get_derived_analytics_snapshot: Writes current derived analytics snapshot JSON into caller buffer.
of_get_effective_spread_bps: Writes last effective spread in bps as JSON: {"bps": N}, or {}.
of_get_futures_snapshot: Writes an analytics snapshot JSON payload into the caller-provided buffer.
of_get_half_spread_cost_bps: Writes average half-spread cost over window trades: {"bps": N}.
of_get_hasbrouck_snapshot: Writes an analytics snapshot JSON payload into the caller-provided buffer.
of_get_institutional_flow_snapshot: Writes an analytics snapshot JSON payload into the caller-provided buffer.
of_get_interval_candle_snapshot: Writes rolling interval candle snapshot JSON into caller buffer.
of_get_kinetic_energy_snapshot: Writes an analytics snapshot JSON payload into the caller-provided buffer.
of_get_kyle_lambda_snapshot: Writes Kyle’s Lambda snapshot JSON.
of_get_metrics_json: Allocates and returns metrics JSON (*out) plus byte length (*out_len).
of_get_mid_price: Writes mid price as JSON: {"mid": N}, or {} if no book data.
of_get_noise_snapshot: Writes an analytics snapshot JSON payload into the caller-provided buffer.
of_get_oi_analysis_snapshot: Writes an analytics snapshot JSON payload into the caller-provided buffer.
of_get_options_flow_snapshot: Writes an analytics snapshot JSON payload into the caller-provided buffer.
of_get_pattern_snapshot: Writes pattern detection snapshot JSON into caller buffer.
of_get_realised_spread_bps: Writes realised spread over hold_ticks ticks ago: {"bps": N}.
of_get_regime_snapshot: Writes an analytics snapshot JSON payload into the caller-provided buffer.
of_get_resiliency_snapshot: Writes resiliency snapshot JSON.
of_get_session_candle_snapshot: Writes current session candle snapshot JSON into caller buffer.
of_get_signal_snapshot: Writes current signal snapshot JSON into caller buffer.
of_get_spread_decomp_snapshot: Writes an analytics snapshot JSON payload into the caller-provided buffer.
of_get_vol_signature_snapshot: Writes an analytics snapshot JSON payload into the caller-provided buffer.
of_get_volatility_snapshot: Writes an analytics snapshot JSON payload into the caller-provided buffer.
of_get_vpin_snapshot: Writes VPIN snapshot JSON.
of_ingest_book: Injects one external book event into runtime processing.
of_ingest_trade: Injects one external trade event into runtime processing.
of_reset_symbol_session: Resets per-symbol analytics session state.
of_string_free: Frees a C string returned by this library.
of_subscribe: Subscribes to a symbol stream and returns a subscription token.
of_unsubscribe: Unsubscribes and destroys a subscription token.
of_unsubscribe_symbol: Unsubscribes all active streams for a symbol on this engine.

Type Aliases§

of_event_cb: C callback signature for subscription delivery.

Crate of_ffi_c

Crate of_ffi_c Copy item path

§of_ffi_c

§ABI Surface

§New In 0.4.0

§Public ABI Inventory

§C Struct Reference

§Function Family Reference

§Safety Contract

§Minimal C Example

§Error Semantics

§Snapshot and Callback Payload Contracts

§Integration Notes

§Real-World Use Cases

§1. Embed the runtime in a C or C++ trading host

§2. Drive Python or Java bindings from the same native ABI

§3. Build a custom host-side event pump

§Detailed Example: Poll And Read Snapshots

Structs§

Enums§

Functions§

Type Aliases§

Crate of_ffi_c