Crate rusteron_code_gen

Expand description

§rusteron-code-gen

rusteron-code-gen is an internal code generation tool used within the Rusteron project.
It automates the creation of Rust bindings from Aeron’s C APIs, reducing manual effort and ensuring consistent wrapper interfaces across the rusteron-* crates.

§Purpose

Aeron’s C APIs follow predictable structural patterns. This tool parses those C headers and uses templates to emit Rust wrappers around the raw FFI layer. It is primarily used to generate:

rusteron-client
rusteron-archive
rusteron-media-driver

By automating this step, we reduce maintenance cost and improve reliability when tracking upstream changes in Aeron.

Note: This crate is not intended for standalone use outside the Rusteron project.

§Sponsored by GSR

Rusteron is proudly sponsored and maintained by GSR, a global leader in algorithmic trading and market making in digital assets.

It powers mission-critical infrastructure in GSR’s real-time trading stack and is now developed under the official GSR GitHub organization as part of our commitment to open-source excellence and community collaboration.

We welcome contributions, feedback, and discussions. If you’re interested in integrating or contributing, please open an issue or reach out directly.

§Features

Automated Code Generation – Converts Aeron C headers into Rust-safe APIs.
Pattern-Based Templating – Leverages Aeron’s consistent structure to minimize boilerplate.
Integration-Friendly – Output is directly used in production modules of the Rusteron stack.

§Usage

This crate is used via internal tooling (e.g. in just scripts or CI pipelines) and is not meant to be added as a dependency in consumer projects.

§Safety Considerations

Generated code includes unsafe blocks where necessary to interface with Aeron’s low-level constructs.
While much of the generation is automated, occasional manual review and patching may be required to ensure correctness, especially when Aeron introduces API changes.

§License & Acknowledgments

Dual-licensed under MIT or Apache-2.0. See the root README.

Special thanks to:

@mimran1980, a core low-latency developer at GSR and the original creator of Rusteron - your work made this possible!
@bspeice for the original libaeron-sys
The Aeron community for open protocol excellence

Modules§

c_build: Release compiler flags for the vendored Aeron C build.
test_logger

Macros§

cformat: format! for C strings: builds the formatted String and converts it to a CString in one visibly-named step.

Structs§

AeronCError: Aeron C API error: code + optional message.
Arg
BackoffIdleStrategy: Adaptive backoff: spin a few times, then yield a few times, then sleep with an exponentially growing park up to a max. A good general-purpose strategy. (Aeron BackoffIdleStrategy.)
BusySpinIdleStrategy: Spin with a CPU pause hint. Lowest latency, pins a core. (Aeron BusySpinIdleStrategy.)
CBinding
CHandler
CWrapper
ChannelUri: Represents the Aeron URI parser and handler.
ClassifiedArg: One argument, classified once, with every emission fragment precomputed.
ClassifiedMethodArgs
Handler: Heap-allocated, reference-counted holder for a callback the C client keeps and fires later, possibly many times, from the conductor thread.
Handlers: Utility method for setting empty handlers
ManagedCResource: A custom struct for managing C resources with automatic cleanup.
Method
NoHandler: Type-level “no callback” sentinel.
NoOpIdleStrategy: No-op — never yields the core. (Aeron NoOpIdleStrategy.)
ReturnType
SleepingIdleStrategy: Sleep for a fixed duration when idle. (Aeron SleepingIdleStrategy.)
YieldingIdleStrategy: Yield the OS thread when idle. Lower CPU than busy-spin, slightly higher latency. (Aeron YieldingIdleStrategy.)

Enums§

AeronErrorType
AeronOfferError: Typed error for offer / try_claim on a publication.
ArgProcessing
ArgRole: Role of a C argument in the generated Rust wrapper method.
CResource
ControlMode: Enum for control modes.
Media: Enum for media types.

Constants§

AERON_DIR_PROP_NAME
AERON_IPC_MEDIA
AERON_UDP_MEDIA
ARCHIVE_BINDINGS
CLIENT_BINDINGS
COMMON_CODE
CUSTOM_AERON_CODE
CUSTOM_ARCHIVE_CODE
DRIVER_TIMEOUT_MS_DEFAULT
MEDIA_DRIVER_BINDINGS
SPY_PREFIX
TAG_PREFIX
UNWIND_HANDLER_TYPES: Handler types declared extern "C-unwind": the handler types UNWIND_POLL_FNS take. Needed before parsing, as bindgen sets the ABI; a test checks it matches the bindings
UNWIND_POLL_FNS: C functions a handler panic may pass through, checked by reading the Aeron C source: they save the position only after the handler returns, so the next poll redelivers from the last saved position. Not derivable from the headers. Any other C function gets trampolines that catch the panic, so a missing entry is safe, just not zero cost

Traits§

IdleStrategy: Back off a poll loop when the last cycle did no work. Mirrors Aeron’s IdleStrategy: idle(work_count) returns immediately when work_count > 0, otherwise spins / yields / sleeps depending on the implementation.
IntoCString

Functions§

append_to_file
classify_method_args: Classify every argument of method once. owned_retained mirrors the owned-setter rule: &self method, int return, exactly one retained handler, no &mut primitives.
find_unused_udp_port
format_token_stream
format_with_rustfmt
generate_handlers
generate_rust_code
get_possible_wrappers
is_sync_handler_type
is_udp_port_available
parse_bindings
parse_bindings_with_custom: Like parse_bindings, additionally scanning per-crate custom code (appended after the common aeron_custom.rs) so its hand-written methods are skipped during generation.
parse_custom_methods: Parse aeron_custom.rs source and return a map of ClassName -> {method_names} for every impl ClassName { fn method_name ... } block found. This lets the generator skip auto-generating methods that have hand-written overrides.
snake_to_pascal_case

Type Aliases§

CleanupBox
RcOrArc: Reference-counting smart pointer: Rc by default, Arc under the multi-threaded feature. Swap is transparent — RcOrArc::new, .clone(), strong_count all work on both.
RefCellOrMutex