Expand description
§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()ortry_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*_initand*_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*_initmethod.- Automatic Cleanup (Partial): When possible,
Dropwill invoke the appropriate*_closeor*_destroymethods. - 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(...)andHandlers::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);
}
}§Features
static: When enabled, this feature statically links the Aeron C code. By default, the library uses dynamic linking to the Aeron C libraries.backtrace- When enabled will log a backtrace for each AeronCErrorextra-logging- When enabled will log when resource is created and destroyed. useful if your seeing a segfault due to a resource being closedprecompile- When enabled will use precompiled c code instead of requiring cmake and java to me installed
Modules§
Structs§
- Aeron
- Aeron
Agent Start Func Logger - Aeron
Async AddCounter - Aeron
Async AddExclusive Publication - Aeron
Async AddPublication - Aeron
Async AddSubscription - Aeron
Async Destination - Aeron
Async Destination ById - Aeron
Available Counter Logger - Aeron
Available Counter Pair - Aeron
Available Image Logger - Aeron
Block Handler Logger - Aeron
Buffer Claim - Structure used to hold information for a try_claim function call.
- AeronC
Error - Represents an Aeron-specific error with a code and an optional message.
- Aeron
Client Registering Resource - Aeron
Close Client Logger - Aeron
Close Client Pair - Aeron
Cnc - Aeron
CncConstants - Aeron
CncMetadata - Aeron
Context - Aeron
Controlled Fragment Assembler - Aeron
Controlled Fragment Handler Logger - Aeron
Counter - Aeron
Counter Constants - Configuration for a counter that does not change during it’s lifetime.
- Aeron
Counter Metadata Descriptor - Aeron
Counter Value Descriptor - Aeron
Counters Reader - Aeron
Counters Reader Buffers - Aeron
Counters Reader Foreach Counter Func Logger - Aeron
Data Header - Aeron
Data Header AsLongs - Aeron
Error - Aeron
Error Handler Logger - Aeron
Error LogReader Func Logger - Aeron
Error Logger - Aeron
Exclusive Publication - Aeron
Fragment Assembler - Aeron
Fragment Closure Assembler - Aeron
Fragment Handler Logger - Aeron
Frame Header - Aeron
Header - Aeron
Header Values - Aeron
Header Values Frame - Aeron
Idle Strategy Func Logger - Aeron
Image - Aeron
Image Constants - Configuration for an image that does not change during it’s lifetime.
- Aeron
Image Controlled Fragment Assembler - Aeron
Image Fragment Assembler - Aeron
Iovec - Aeron
IpcChannel Params - Aeron
LogBuffer - Aeron
Logbuffer Metadata - Aeron
Loss Reporter - Aeron
Loss Reporter Entry - Aeron
Loss Reporter Read Entry Func Logger - Aeron
Mapped Buffer - Aeron
Mapped File - Aeron
Mapped RawLog - Aeron
NakHeader - Aeron
NewPublication Logger - Aeron
NewSubscription Logger - Aeron
Notification Logger - Aeron
Option Header - Aeron
PerThread Error - Aeron
Publication - Aeron
Publication Constants - Configuration for a publication that does not change during it’s lifetime.
- Aeron
Publication Error Frame Handler Logger - Aeron
Publication Error Values - Aeron
Reserved Value Supplier Logger - Aeron
Resolution Header - Aeron
Resolution Header Ipv4 - Aeron
Resolution Header Ipv6 - Aeron
Response Setup Header - Aeron
Rttm Header - Aeron
Setup Header - Aeron
Status Message Header - Aeron
Status Message Optional Header - Aeron
StrTo PtrHash Map - Aeron
StrTo PtrHash MapKey - Aeron
Subscription - Aeron
Subscription Constants - Aeron
UdpChannel Params - Aeron
Unavailable Counter Logger - Aeron
Unavailable Counter Pair - Aeron
Unavailable Image Logger - Aeron
Uri - Aeron
UriParam - Aeron
UriParams - Aeron
UriParse Callback Logger - Aeron
UriString Builder - Channel
Uri - Represents the Aeron URI parser and handler.
- FnMut
Message Handler - Handler
- Handler
- Handlers
- Utility method for setting empty handlers
- ManagedC
Resource - A custom struct for managing C resources with automatic cleanup.
Enums§
- Aeron
Error Type - Aeron
System Counter Type - CResource
- Control
Mode - Enum for control modes.
- Media
- Enum for media types.
Constants§
Statics§
Traits§
- Aeron
Agent Start Func Callback - (note you must copy any arguments that you use afterwards even those with static lifetimes)
- Aeron
Available Counter Callback - Function called by aeron_client_t to deliver notifications that a counter has been added to the driver.
- Aeron
Available Image Callback - Function called by aeron_client_t to deliver notifications that an aeron_image_t was added.
- Aeron
Block Handler Callback - Callback for handling a block of messages being read from a log.
- Aeron
Close Client Callback - Function called by aeron_client_t to deliver notifications that the client is closing.
- Aeron
Controlled Fragment Handler Callback - Callback for handling fragments of data being read from a log.
- Aeron
Counters Reader Foreach Counter Func Callback - Function called by aeron_counters_reader_foreach_counter for each counter in the aeron_counters_reader_t.
- Aeron
Error Handler Callback - The error handler to be called when an error occurs.
- Aeron
Error LogReader Func Callback - (note you must copy any arguments that you use afterwards even those with static lifetimes)
- Aeron
Fragment Handler Callback - Callback for handling fragments of data being read from a log.
- Aeron
Idle Strategy Func Callback - (note you must copy any arguments that you use afterwards even those with static lifetimes)
- Aeron
Loss Reporter Read Entry Func Callback - (note you must copy any arguments that you use afterwards even those with static lifetimes)
- Aeron
NewPublication Callback - Function called by aeron_client_t to deliver notification that the media driver has added an aeron_publication_t or aeron_exclusive_publication_t successfully.
- Aeron
NewSubscription Callback - Function called by aeron_client_t to deliver notification that the media driver has added an aeron_subscription_t successfully.
- Aeron
Notification Callback - Generalised notification callback.
- Aeron
Publication Error Frame Handler Callback - The error frame handler to be called when the driver notifies the client about an error frame being received.
The data passed to this callback will only be valid for the lifetime of the callback. The user should use
aeron_publication_error_values_copyif they require the data to live longer than that. - Aeron
Reserved Value Supplier Callback - Function called when filling in the reserved value field of a message.
- Aeron
Unavailable Counter Callback - Function called by aeron_client_t to deliver notifications that a counter has been removed from the driver.
- Aeron
Unavailable Image Callback - Function called by aeron_client_t to deliver notifications that an aeron_image_t has been removed from use and should not be used any longer.
- Aeron
UriParse Callback Callback - (note you must copy any arguments that you use afterwards even those with static lifetimes)
- IntoC
String