rusteron-client

rusteron-client is a core component of the Rusteron project.
It provides a Rust wrapper around the Aeron C client API, enabling high-performance, low-latency communication in distributed systems built with Rust.

This crate supports publishing, subscribing, and managing Aeron resources, while exposing a flexible and idiomatic interface over unsafe C bindings.
Due to its reliance on raw FFI, developers must take care to manage resource lifetimes and concurrency correctly.

Features

• Client Setup – Create and start an Aeron client using Rust.
• Publications – Send messages via offer() or try_claim().
• Subscriptions – Poll for incoming messages and handle fragments.
• Callbacks & Handlers – React to driver events like availability, errors, and stream lifecycle changes.
• Cloneable Wrappers – All client types are cloneable and share ownership of the underlying C resources.
• Automatic Resource Management – Objects created with .new() automatically call *_init and *_close, where supported.
• Result-Focused API – Methods returning primitive C results return Result<T, AeronCError> for ergonomic error handling.
• Efficient String Interop – Inputs use &CStr, outputs return &str, giving developers precise allocation control.

General Patterns

• new() Initialization: Automatically calls the corresponding *_init method.
• Automatic Cleanup (Partial): When possible, Drop will invoke the appropriate *_close or *_destroy methods.
• Manual Resource Responsibility: For methods like set_aeron() or where lifetimes aren't managed internally, users are responsible for safety.
• Handlers Must Be Leaked and Released: Callbacks passed to the C layer require explicit memory management using Handlers::leak(...) and Handlers::release(...).

Handlers and Callbacks

Handlers allow users to customize responses to Aeron events (errors, image availability, etc). There are two ways to use them:

1. Implementing a Trait (Recommended)

This is the most performant and idiomatic approach.

use rusteron_client::*;

pub struct MyErrorHandler;

impl AeronErrorHandlerCallback for MyErrorHandler {
    fn handle_aeron_error_handler(&mut self, code: i32, msg: &str) {
        eprintln!("Aeron error ({}): {}", code, msg);
    }
}