Skip to main content

rusteron_media_driver/
lib.rs

1#![allow(improper_ctypes_definitions)]
2#![allow(non_upper_case_globals)]
3#![allow(non_camel_case_types)]
4#![allow(non_snake_case)]
5#![allow(clippy::all)]
6#![allow(unused_unsafe)]
7#![allow(unused_variables)]
8#![allow(unsafe_op_in_unsafe_fn)]
9#![doc = include_str!("../README.md")]
10//! # Features
11//!
12//! - **`static`**: Statically links the Aeron C code.
13//!   By default, the library links the Aeron C libraries dynamically
14//! - **`backtrace`**: Logs a backtrace for each `AeronCError`
15//! - **`extra-logging`**: Logs when a resource is created and destroyed. Useful if you're seeing a segfault due to a resource being closed
16//! - **`log-c-bindings`**: Logs every C binding call with arguments and return values. Useful for debugging FFI interactions
17//! - **`precompile`**: Uses precompiled C code instead of requiring cmake and java to be installed
18
19#[allow(improper_ctypes_definitions)]
20#[allow(unpredictable_function_pointer_comparisons)]
21// Preserve upstream Doxygen markup and bracketed IPv6 examples in the raw C comments.
22#[allow(rustdoc::broken_intra_doc_links, rustdoc::invalid_html_tags)]
23pub mod bindings {
24    include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
25}
26
27use bindings::*;
28use log::info;
29use std::path::Path;
30use std::sync::Arc;
31use std::sync::atomic::{AtomicBool, Ordering};
32use std::thread::{JoinHandle, sleep};
33
34include!(concat!(env!("OUT_DIR"), "/aeron.rs"));
35include!(concat!(env!("OUT_DIR"), "/aeron_custom.rs"));
36
37unsafe impl Sync for AeronDriverContext {}
38unsafe impl Send for AeronDriverContext {}
39unsafe impl Sync for AeronDriver {}
40unsafe impl Send for AeronDriver {}
41
42/// RAII guard for an embedded media driver launched via
43/// [`AeronDriver::launch_embedded_guard`]. Signals stop on drop so the driver
44/// thread always joins even on panic / early return.
45pub struct EmbeddedMediaDriver {
46    stop: Option<Arc<AtomicBool>>,
47    handle: Option<JoinHandle<Result<(), AeronCError>>>,
48}
49
50impl EmbeddedMediaDriver {
51    /// Signal the driver thread to stop (idempotent; the thread exits on its next
52    /// idle cycle). Blocks until it joins when consumed by [`Self::join`].
53    pub fn stop(&self) {
54        if let Some(stop) = &self.stop {
55            stop.store(true, Ordering::SeqCst);
56        }
57    }
58
59    /// Whether the driver thread has finished.
60    pub fn is_finished(&self) -> bool {
61        self.handle.as_ref().map_or(true, |h| h.is_finished())
62    }
63
64    /// Signal stop and block until the driver thread joins, returning its result.
65    pub fn join(mut self) -> Result<(), AeronCError> {
66        self.stop();
67        if let Some(h) = self.handle.take() {
68            // Flatten JoinHandle<Result<..>>: a panic becomes an AeronCError,
69            // the inner AeronCError is propagated.
70            return h.join().map_err(|_| AeronCError::from_code(-1)).and_then(|r| r);
71        }
72        Ok(())
73    }
74}
75
76impl Drop for EmbeddedMediaDriver {
77    fn drop(&mut self) {
78        if let Some(stop) = &self.stop {
79            stop.store(true, Ordering::SeqCst);
80        }
81        if let Some(h) = self.handle.take() {
82            let _ = h.join();
83        }
84    }
85}
86
87pub mod testing;
88
89impl AeronDriverContext {
90    /// Typed variant of [`Self::set_conductor_idle_strategy`].
91    pub fn set_conductor_idle_strategy_kind(&self, kind: AeronIdleStrategyKind) -> Result<i32, AeronCError> {
92        self.set_conductor_idle_strategy(kind.name_c())
93    }
94
95    /// Typed variant of [`Self::set_sender_idle_strategy`].
96    pub fn set_sender_idle_strategy_kind(&self, kind: AeronIdleStrategyKind) -> Result<i32, AeronCError> {
97        self.set_sender_idle_strategy(kind.name_c())
98    }
99
100    /// Typed variant of [`Self::set_receiver_idle_strategy`].
101    pub fn set_receiver_idle_strategy_kind(&self, kind: AeronIdleStrategyKind) -> Result<i32, AeronCError> {
102        self.set_receiver_idle_strategy(kind.name_c())
103    }
104
105    /// Typed variant of [`Self::set_sharednetwork_idle_strategy`].
106    pub fn set_sharednetwork_idle_strategy_kind(&self, kind: AeronIdleStrategyKind) -> Result<i32, AeronCError> {
107        self.set_sharednetwork_idle_strategy(kind.name_c())
108    }
109
110    /// Typed variant of [`Self::set_shared_idle_strategy`].
111    pub fn set_shared_idle_strategy_kind(&self, kind: AeronIdleStrategyKind) -> Result<i32, AeronCError> {
112        self.set_shared_idle_strategy(kind.name_c())
113    }
114
115    /// Validates and applies the driver's affinity configuration, as `aeronmd` does.
116    /// On Linux, configured affinities are CPU IDs unless cpuset offsets are enabled
117    /// (`AERON_THREAD_AFFINITY_USE_CPUSET_OFFSETS` or
118    /// [`Self::set_thread_affinity_use_cpuset_offsets`]).
119    /// Call once, before the driver starts.
120    ///
121    /// # Errors
122    ///
123    /// On Linux, affinity validation failed or the cpuset could not be read.
124    /// On other platforms this is a no-op, matching Aeron's standalone driver.
125    pub fn apply_cgroup_cpuset_affinity(&self) -> Result<(), AeronCError> {
126        // SAFETY: the context is live, and the driver has not started reading it.
127        let result = unsafe { aeron_driver_validate_and_apply_affinity_configuration(self.get_inner()) };
128        if result < 0 {
129            return Err(AeronCError::from_code(result).capture_errmsg());
130        }
131        Ok(())
132    }
133
134    /// Pins each driver agent thread, as it starts, to the CPU set for its role
135    /// (`AERON_CONDUCTOR_CPU_AFFINITY` and the like, or [`Self::set_conductor_cpu_affinity`]
136    /// and its siblings), as `aeronmd` does. An on-start function already set still runs
137    /// after it, so set any other one first. Call before [`AeronDriver::new`] or
138    /// [`AeronDriver::launch_embedded`], which hand the on-start function to the agents.
139    pub fn set_thread_affinity_on_start(&self) {
140        let context = self.get_inner();
141        // SAFETY: the context is live and its agents have not started, so nothing else reads
142        // these fields; Aeron's affinity function takes the driver context as its state.
143        unsafe {
144            // installing it again would make it its own delegate, which calls itself forever
145            if (*context).agent_on_start_func.map(|f| f as *const ())
146                == Some(aeron_set_thread_affinity_on_start as *const ())
147            {
148                return;
149            }
150            (*context).agent_on_start_func_delegate = (*context).agent_on_start_func;
151            (*context).agent_on_start_state_delegate = (*context).agent_on_start_state;
152            aeron_driver_context_set_agent_on_start_function(
153                context,
154                Some(aeron_set_thread_affinity_on_start),
155                context.cast(),
156            );
157        }
158    }
159}
160
161impl AeronDriver {
162    pub fn launch_embedded(
163        aeron_context: AeronDriverContext,
164        register_sigint: bool,
165    ) -> (Arc<AtomicBool>, JoinHandle<Result<(), AeronCError>>) {
166        AeronDriver::wait_for_previous_media_driver_to_timeout(&aeron_context);
167
168        let stop = Arc::new(AtomicBool::new(false));
169        let stop_copy = stop.clone();
170        // Register signal handler for SIGINT (Ctrl+C)
171        if register_sigint {
172            let stop_copy2 = stop.clone();
173            ctrlc::set_handler(move || {
174                stop_copy2.store(true, Ordering::SeqCst);
175            })
176            .expect("Error setting Ctrl-C handler");
177        }
178
179        let started = Arc::new(AtomicBool::new(false));
180        let started2 = started.clone();
181
182        let dir = aeron_context.get_dir().to_string();
183        info!("Starting media driver [dir={}]", dir);
184        let handle = std::thread::spawn(move || {
185            let aeron_context = aeron_context.clone();
186            let aeron_driver = AeronDriver::new(&aeron_context)?;
187            aeron_driver.start(true)?;
188
189            info!("Aeron driver started [dir={}]", aeron_driver.context().get_dir());
190
191            started2.store(true, Ordering::SeqCst);
192
193            // Poll for work until Ctrl+C is pressed
194            while !stop.load(Ordering::Acquire) {
195                aeron_driver.main_idle_strategy(aeron_driver.main_do_work()?);
196            }
197
198            info!("stopping media driver");
199
200            Ok::<_, AeronCError>(())
201        });
202
203        while !started.load(Ordering::SeqCst) && !handle.is_finished() {
204            sleep(Duration::from_millis(100));
205        }
206
207        if handle.is_finished() {
208            panic!("failed to start media driver {:?}", handle.join())
209        }
210        info!("started media driver [dir={}]", dir);
211
212        (stop_copy, handle)
213    }
214
215    /// Launch an embedded media driver, returning a RAII guard that stops the
216    /// driver on drop (so a panic or early return can't leak a driver process).
217    ///
218    /// Prefer this over [`Self::launch_embedded`], which returns a raw
219    /// `(Arc<AtomicBool>, JoinHandle)` tuple the caller must remember to drive.
220    /// `register_sigint` is `true` to mirror the standalone binary.
221    pub fn launch_embedded_guard(aeron_context: AeronDriverContext, register_sigint: bool) -> EmbeddedMediaDriver {
222        let (stop, handle) = Self::launch_embedded(aeron_context, register_sigint);
223        EmbeddedMediaDriver {
224            stop: Some(stop),
225            handle: Some(handle),
226        }
227    }
228
229    /// If existing shm files are still within the driver timeout, a new driver tries to reuse them and fails.
230    /// This waits in that case and otherwise proceeds
231    pub fn wait_for_previous_media_driver_to_timeout(aeron_context: &AeronDriverContext) {
232        if !aeron_context.get_dir_delete_on_start() {
233            let cnc_file = Path::new(aeron_context.get_dir()).join("cnc.dat");
234
235            if cnc_file.exists() {
236                let timeout = Duration::from_millis(aeron_context.get_driver_timeout_ms() * 2).as_nanos() as i64;
237
238                let mut duration = timeout;
239
240                if let Ok(md) = cnc_file.metadata() {
241                    if let Ok(modified_time) = md.modified() {
242                        if let Ok(took) = modified_time.elapsed() {
243                            duration = took.as_nanos() as i64;
244                        }
245                    }
246                }
247
248                let delay = timeout - duration;
249
250                if delay > 0 {
251                    let sleep_duration = Duration::from_nanos((delay + 1_000_000) as u64);
252                    info!(
253                        "cnc file already exists, will need to wait {sleep_duration:?} for timeout [file={cnc_file:?}]"
254                    );
255                    sleep(sleep_duration);
256                }
257            }
258        }
259    }
260}
261
262#[cfg(test)]
263mod tests {
264    use super::*;
265    use log::error;
266    use std::os::raw::c_int;
267    use std::sync::atomic::Ordering;
268    use std::time::Duration;
269
270    #[test]
271    fn driver_idle_strategy_kinds_round_trip() {
272        let ctx = AeronDriverContext::new().unwrap();
273        for (kind, name) in [
274            (AeronIdleStrategyKind::Sleeping, "sleeping"),
275            (AeronIdleStrategyKind::Yielding, "yield"),
276            (AeronIdleStrategyKind::BusySpin, "spin"),
277            (AeronIdleStrategyKind::NoOp, "noop"),
278            (AeronIdleStrategyKind::Backoff, "backoff"),
279        ] {
280            ctx.set_conductor_idle_strategy_kind(kind).unwrap();
281            assert_eq!(name, ctx.get_conductor_idle_strategy(), "conductor {kind:?}");
282            ctx.set_sender_idle_strategy_kind(kind).unwrap();
283            ctx.set_receiver_idle_strategy_kind(kind).unwrap();
284            ctx.set_sharednetwork_idle_strategy_kind(kind).unwrap();
285            ctx.set_shared_idle_strategy_kind(kind).unwrap();
286        }
287    }
288
289    #[test]
290    fn driver_rejects_a_send_batch_larger_than_its_vector_capacity() -> Result<(), AeronCError> {
291        let context = AeronDriverContext::new()?;
292        let dir = std::env::temp_dir().join(format!("rusteron-invalid-send-batch-{}", Aeron::nano_clock()));
293        context.set_dir(&dir.to_string_lossy().into_c_string())?;
294        context.set_dir_delete_on_shutdown(true)?;
295        context.set_sender_io_vector_capacity(2)?;
296        context.set_network_publication_max_messages_per_send(5)?;
297        let error = AeronDriver::new(&context).unwrap_err().capture_errmsg();
298        assert!(
299            error.to_string().contains(
300                "network_publication_max_messages_per_send may not exceed sender_io_vector_capacity (2): value=5"
301            ),
302            "{error}"
303        );
304        Ok(())
305    }
306
307    #[test]
308    fn version_check() {
309        let major = unsafe { crate::aeron_version_major() };
310        let minor = unsafe { crate::aeron_version_minor() };
311        let patch = unsafe { crate::aeron_version_patch() };
312
313        let aeron_version = format!("{}.{}.{}", major, minor, patch);
314        let cargo_version = include_str!("../aeron/version.txt").trim().split('-').next().unwrap();
315        assert_eq!(aeron_version, cargo_version);
316    }
317
318    #[cfg(target_os = "linux")]
319    #[test]
320    fn socket_bindings_match_the_native_library() {
321        let address = SockaddrStorage::new_zeroed_on_heap();
322        address.aeron_set_ipv4_wildcard_host_and_port();
323        // Linux writes a 16-bit AF_INET at offset zero. Darwin bindings read
324        // an 8-bit family at offset one and return zero.
325        assert_eq!(address.ss_family(), 2);
326    }
327
328    #[test]
329    fn send_message() -> Result<(), AeronCError> {
330        rusteron_code_gen::test_logger::init(log::LevelFilter::Info);
331        let topic = AERON_IPC_STREAM;
332        let stream_id = 32;
333
334        let aeron_context = AeronDriverContext::new()?;
335        aeron_context.set_dir_delete_on_shutdown(true)?;
336        aeron_context.set_dir_delete_on_start(true)?;
337
338        let (stop, _driver_handle) = AeronDriver::launch_embedded(aeron_context.clone(), false);
339
340        // aeron_driver
341        //     .conductor()
342        //     .context()
343        //     .print_configuration();
344        // aeron_driver.main_do_work()?;
345        info!("aeron dir: {:?}", aeron_context.get_dir());
346
347        let dir = aeron_context.get_dir().to_string();
348        let ctx = AeronContext::new()?;
349        ctx.set_dir(&dir.into_c_string())?;
350
351        let client = Aeron::new(&ctx)?;
352
353        #[derive(Default, Debug)]
354        struct ErrorCount {
355            error_count: usize,
356        }
357
358        impl AeronErrorHandlerCallback for ErrorCount {
359            fn handle_aeron_error_handler(&mut self, error_code: c_int, msg: &str) {
360                error!("Aeron error {}: {}", error_code, msg);
361                self.error_count += 1;
362            }
363        }
364
365        let error_handler = Handler::new(ErrorCount::default());
366        ctx.set_error_handler(Some(error_handler.clone()))?;
367
368        struct Test {}
369        impl AeronAvailableCounterCallback for Test {
370            fn handle_aeron_on_available_counter(
371                &mut self,
372                counters_reader: &AeronCountersReader,
373                registration_id: i64,
374                counter_id: i32,
375            ) -> () {
376                info!(
377                    "new counter counters_reader={counters_reader:?} registration_id={registration_id} counter_id={counter_id}"
378                );
379            }
380        }
381
382        impl AeronNewPublicationCallback for Test {
383            fn handle_aeron_on_new_publication(
384                &mut self,
385                channel: &str,
386                stream_id: i32,
387                session_id: i32,
388                correlation_id: i64,
389            ) -> () {
390                info!("on new publication {channel} {stream_id} {session_id} {correlation_id}")
391            }
392        }
393        let handler = Handler::new(Test {});
394        ctx.set_on_available_counter(Some(handler.clone()))?;
395        ctx.set_on_new_publication(Some(handler.clone()))?;
396
397        client.start()?;
398        info!("aeron driver started");
399        assert!(Aeron::epoch_clock() > 0);
400        assert!(Aeron::nano_clock() > 0);
401
402        let counter_async = AeronAsyncAddCounter::new(&client, 2543543, "12312312".as_bytes(), "abcd")?;
403
404        let counter = counter_async.poll_blocking(Duration::from_secs(15))?;
405        unsafe {
406            *counter.addr() += 1;
407        }
408
409        let result = AeronAsyncAddPublication::new(&client, topic, stream_id)?;
410
411        let publication = result.poll_blocking(std::time::Duration::from_secs(15))?;
412
413        info!("publication channel: {:?}", publication.channel());
414        info!("publication stream_id: {:?}", publication.stream_id());
415        info!("publication status: {:?}", publication.channel_status());
416
417        drop(publication);
418        drop(counter);
419        drop(client);
420        stop.store(true, Ordering::SeqCst);
421
422        Ok(())
423    }
424
425    #[test]
426    pub fn test_debug() -> Result<(), Box<dyn std::error::Error>> {
427        let ctx = AeronDriverContext::new()?;
428
429        println!("{:#?}", ctx);
430
431        // Capture the raw context pointer, NOT a context clone: the handler is
432        // owned by `ctx` (set_agent_on_start_function stores it as a dependency),
433        // so a clone would form a strong-reference cycle (ctx -> handler -> ctx)
434        // that close_resource_deferred_if_shared can never drain, leaking the C
435        // context. The raw pointer is sound because the handler cannot outlive
436        // the context that owns it.
437        struct AgentStartHandler {
438            ctx_ptr: *mut aeron_driver_context_t,
439        }
440        // SAFETY: see comment above. The handler is owned by the context and only
441        // dereferenced on the driver agent thread while the context is alive.
442        unsafe impl Send for AgentStartHandler {}
443
444        impl AeronAgentStartFuncCallback for AgentStartHandler {
445            fn handle_aeron_agent_on_start_func(&mut self, role: &str) -> () {
446                unsafe {
447                    aeron_set_thread_affinity_on_start(
448                        self.ctx_ptr as *mut _,
449                        std::ffi::CString::new(role).unwrap().into_raw(),
450                    );
451                }
452            }
453        }
454
455        let agent_handler = Handler::new(AgentStartHandler {
456            ctx_ptr: ctx.get_inner(),
457        });
458        ctx.set_agent_on_start_function(Some(agent_handler.clone()))?;
459
460        println!("{:#?}", ctx);
461
462        Ok(())
463    }
464
465    /// Cpuset affinity is off by default, so applying it changes nothing.
466    #[test]
467    fn cgroup_cpuset_affinity_is_a_no_op_when_off() -> Result<(), AeronCError> {
468        AeronDriverContext::new()?.apply_cgroup_cpuset_affinity()
469    }
470
471    #[test]
472    fn new_driver_configuration_round_trips() -> Result<(), AeronCError> {
473        let context = AeronDriverContext::new()?;
474        for tos in [-1, 0, 128, 255] {
475            context.set_socket_tos(tos)?;
476            assert_eq!(context.get_socket_tos(), tos);
477        }
478        for invalid in [-2, 256] {
479            assert!(context.set_socket_tos(invalid).is_err());
480            assert_eq!(context.get_socket_tos(), 255);
481        }
482        context.set_receiver_poll_to_slow_work_ratio(11)?;
483        assert_eq!(context.get_receiver_poll_to_slow_work_ratio(), 11);
484        context.set_udp_channel_transport_poller_iteration_threshold(6)?;
485        assert_eq!(context.get_udp_channel_transport_poller_iteration_threshold(), 6);
486        context.set_udp_channel_transport_poller_socket_poll_limit(8)?;
487        assert_eq!(context.get_udp_channel_transport_poller_socket_poll_limit(), 8);
488        context.set_thread_affinity_use_cpuset_offsets(true)?;
489        assert!(context.get_thread_affinity_use_cpuset_offsets());
490        context.set_thread_affinity_fail_on_validation_errors(true)?;
491        assert!(context.get_thread_affinity_fail_on_validation_errors());
492        Ok(())
493    }
494
495    /// The default validators take an `int32_t` length, so this exercises the generated
496    /// `slice.len() as _` cast for a non-`usize` C length
497    #[test]
498    fn termination_validator_defaults_take_i32_length_slices() {
499        let mut token = *b"token";
500        assert!(AeronDriver::termination_validator_default_allow(
501            std::ptr::null_mut(),
502            &mut token
503        ));
504        assert!(!AeronDriver::termination_validator_default_deny(
505            std::ptr::null_mut(),
506            &mut token
507        ));
508        assert!(AeronDriver::termination_validator_default_allow(
509            std::ptr::null_mut(),
510            &mut []
511        ));
512    }
513
514    /// Affinity configuration is a no-op off Linux, including cpuset offsets.
515    #[test]
516    #[cfg(not(target_os = "linux"))]
517    fn cgroup_cpuset_affinity_is_a_no_op_off_linux() -> Result<(), AeronCError> {
518        let context = AeronDriverContext::new()?;
519        context.set_thread_affinity_use_cpuset_offsets(true)?;
520        context.apply_cgroup_cpuset_affinity()?;
521        Ok(())
522    }
523
524    /// Installing the affinity function again keeps the earlier on-start function as its
525    /// delegate, rather than making the affinity function call itself.
526    #[test]
527    fn thread_affinity_on_start_installs_once() -> Result<(), AeronCError> {
528        let context = AeronDriverContext::new()?;
529        context.set_thread_affinity_on_start();
530        context.set_thread_affinity_on_start();
531        // SAFETY: the context is live and no driver reads it.
532        let delegate = unsafe { (*context.get_inner()).agent_on_start_func_delegate }.map(|f| f as *const ());
533        assert_ne!(delegate, Some(aeron_set_thread_affinity_on_start as *const ()));
534        Ok(())
535    }
536
537    /// Aeron's affinity function runs as each agent starts, and still calls the on-start
538    /// function set before it.
539    #[test]
540    fn thread_affinity_on_start_keeps_the_previous_on_start_function() -> Result<(), Box<dyn std::error::Error>> {
541        struct Roles(Arc<std::sync::Mutex<Vec<String>>>);
542        impl AeronAgentStartFuncCallback for Roles {
543            fn handle_aeron_agent_on_start_func(&mut self, role: &str) {
544                self.0.lock().unwrap().push(role.to_owned());
545            }
546        }
547
548        let context = AeronDriverContext::new()?;
549        context.set_dir(&format!("{}{}", context.get_dir(), Aeron::nano_clock()).into_c_string())?;
550        context.set_dir_delete_on_start(true)?;
551        context.set_dir_delete_on_shutdown(true)?;
552        context.set_threading_mode(aeron_threading_mode_enum::AERON_THREADING_MODE_DEDICATED)?;
553        context.set_conductor_cpu_affinity(0)?;
554        let roles = Arc::new(std::sync::Mutex::new(Vec::new()));
555        context.set_agent_on_start_function(Some(Roles(Arc::clone(&roles))))?;
556        context.set_thread_affinity_on_start();
557        let installed = context.get_agent_on_start_function().map(|f| f as *const ());
558        assert_eq!(installed, Some(aeron_set_thread_affinity_on_start as *const ()));
559
560        let driver = AeronDriver::launch_embedded_guard(context.clone(), false);
561        let start = std::time::Instant::now();
562        while roles.lock().unwrap().len() < 4 && start.elapsed() < Duration::from_secs(5) {
563            sleep(Duration::from_millis(10));
564        }
565        driver.join()?;
566        let mut seen = roles.lock().unwrap().clone();
567        seen.sort();
568        assert_eq!(seen, ["aeron-md-nra", "conductor", "receiver", "sender"]);
569        Ok(())
570    }
571}