Skip to main content

mojentic/
async_dispatcher.rs

1//! Asynchronous event dispatcher.
2//!
3//! This module provides the `AsyncDispatcher` that manages event processing
4//! in a background task, routing events to registered agents via a router.
5
6use crate::event::{Event, TerminateEvent};
7use crate::router::Router;
8use crate::{MojenticError, Result};
9use std::collections::VecDeque;
10use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
11use std::sync::{Arc, Mutex};
12use std::time::Duration;
13use tokio::task::JoinHandle;
14use tracing::{debug, info};
15use uuid::Uuid;
16
17/// Asynchronous event dispatcher for agent systems.
18///
19/// The dispatcher manages a queue of events and routes them to registered
20/// agents via a router. It runs in a background task and can be stopped
21/// gracefully.
22///
23/// # Examples
24///
25/// ```ignore
26/// use mojentic::async_dispatcher::AsyncDispatcher;
27/// use mojentic::router::Router;
28///
29/// let router = Arc::new(Router::new());
30/// let mut dispatcher = AsyncDispatcher::new(router);
31///
32/// dispatcher.start().await.unwrap();
33/// dispatcher.dispatch(my_event);
34/// dispatcher.wait_for_empty_queue(Some(Duration::from_secs(10))).await.unwrap();
35/// dispatcher.stop().await.unwrap();
36/// ```
37pub struct AsyncDispatcher {
38    router: Arc<Router>,
39    event_queue: Arc<Mutex<VecDeque<Box<dyn Event>>>>,
40    stop_flag: Arc<AtomicBool>,
41    task_handle: Option<JoinHandle<()>>,
42    batch_size: usize,
43    /// Number of agent handler tasks currently executing.
44    in_flight: Arc<AtomicUsize>,
45}
46
47impl AsyncDispatcher {
48    /// Create a new AsyncDispatcher.
49    ///
50    /// # Arguments
51    ///
52    /// * `router` - The router to use for routing events to agents
53    pub fn new(router: Arc<Router>) -> Self {
54        Self {
55            router,
56            event_queue: Arc::new(Mutex::new(VecDeque::new())),
57            stop_flag: Arc::new(AtomicBool::new(false)),
58            task_handle: None,
59            batch_size: 5,
60            in_flight: Arc::new(AtomicUsize::new(0)),
61        }
62    }
63
64    /// Set the batch size (number of events to process per iteration).
65    ///
66    /// # Arguments
67    ///
68    /// * `size` - The batch size
69    pub fn with_batch_size(mut self, size: usize) -> Self {
70        self.batch_size = size;
71        self
72    }
73
74    /// Start the event dispatch task.
75    ///
76    /// This spawns a background task that processes events from the queue.
77    pub async fn start(&mut self) -> Result<()> {
78        if self.task_handle.is_some() {
79            return Err(MojenticError::DispatcherError("Dispatcher already started".to_string()));
80        }
81
82        debug!("Starting async dispatcher");
83        self.stop_flag.store(false, Ordering::Relaxed);
84
85        let router = self.router.clone();
86        let queue = self.event_queue.clone();
87        let stop_flag = self.stop_flag.clone();
88        let in_flight = self.in_flight.clone();
89        let batch_size = self.batch_size;
90
91        let handle = tokio::spawn(async move {
92            Self::dispatch_loop(router, queue, stop_flag, in_flight, batch_size).await;
93        });
94
95        self.task_handle = Some(handle);
96        info!("Async dispatcher started");
97
98        Ok(())
99    }
100
101    /// Stop the event dispatch task.
102    ///
103    /// This signals the background task to stop and waits for it to complete.
104    pub async fn stop(&mut self) -> Result<()> {
105        if let Some(handle) = self.task_handle.take() {
106            debug!("Stopping async dispatcher");
107            self.stop_flag.store(true, Ordering::Relaxed);
108            handle.await.map_err(|e| {
109                MojenticError::DispatcherError(format!("Failed to stop dispatcher: {}", e))
110            })?;
111            info!("Async dispatcher stopped");
112        }
113
114        Ok(())
115    }
116
117    /// Dispatch an event to the queue.
118    ///
119    /// The event will be processed asynchronously by the background task.
120    ///
121    /// # Arguments
122    ///
123    /// * `event` - The event to dispatch
124    pub fn dispatch(&self, mut event: Box<dyn Event>) {
125        // Assign correlation_id if not set
126        if event.correlation_id().is_none() {
127            event.set_correlation_id(Uuid::new_v4().to_string());
128        }
129
130        debug!("Dispatching event: {:?}", event);
131        let mut q = self.event_queue.lock().unwrap();
132        q.push_back(event);
133    }
134
135    /// Wait for the event queue to become empty **and** all in-flight agent
136    /// handlers to complete.
137    ///
138    /// # Arguments
139    ///
140    /// * `timeout` - Optional timeout duration
141    ///
142    /// # Returns
143    ///
144    /// `true` if both the queue is empty and no handlers are running,
145    /// `false` if the timeout was reached first
146    pub async fn wait_for_empty_queue(&self, timeout: Option<Duration>) -> Result<bool> {
147        let start = tokio::time::Instant::now();
148
149        loop {
150            let queue_len = self.event_queue.lock().unwrap().len();
151            let in_flight = self.in_flight.load(Ordering::Acquire);
152
153            if queue_len == 0 && in_flight == 0 {
154                return Ok(true);
155            }
156
157            if let Some(timeout_duration) = timeout {
158                if start.elapsed() > timeout_duration {
159                    return Ok(false);
160                }
161            }
162
163            tokio::time::sleep(Duration::from_millis(100)).await;
164        }
165    }
166
167    /// Get the current queue length.
168    pub fn queue_len(&self) -> usize {
169        self.event_queue.lock().unwrap().len()
170    }
171
172    /// Background dispatch loop.
173    async fn dispatch_loop(
174        router: Arc<Router>,
175        queue: Arc<Mutex<VecDeque<Box<dyn Event>>>>,
176        stop_flag: Arc<AtomicBool>,
177        in_flight: Arc<AtomicUsize>,
178        batch_size: usize,
179    ) {
180        while !stop_flag.load(Ordering::Relaxed) {
181            for _ in 0..batch_size {
182                let event = {
183                    let mut q = queue.lock().unwrap();
184                    q.pop_front()
185                };
186
187                if let Some(event) = event {
188                    debug!("Processing event: {:?}", event);
189
190                    // Check for terminate event
191                    if event.as_any().is::<TerminateEvent>() {
192                        info!("Received TerminateEvent, stopping dispatcher");
193                        stop_flag.store(true, Ordering::Relaxed);
194                        break;
195                    }
196
197                    // Get the event type
198                    let type_id = event.as_any().type_id();
199
200                    // Get agents for this event type
201                    let agents = router.get_agents(type_id);
202                    debug!("Found {} agents for event type", agents.len());
203
204                    // Process event through each agent serially (deterministic, no races on SharedWorkingMemory)
205                    for agent in agents {
206                        debug!("Sending event to agent");
207                        in_flight.fetch_add(1, Ordering::AcqRel);
208                        let event_box = event.clone_box();
209
210                        match agent.receive_event_async(event_box).await {
211                            Ok(new_events) => {
212                                debug!("Agent returned {} events", new_events.len());
213                                let mut q = queue.lock().unwrap();
214                                for new_event in new_events {
215                                    q.push_back(new_event);
216                                }
217                            }
218                            Err(e) => {
219                                tracing::error!("Agent error processing event: {}", e);
220                            }
221                        }
222                        in_flight.fetch_sub(1, Ordering::AcqRel);
223                    }
224                }
225            }
226
227            tokio::time::sleep(Duration::from_millis(100)).await;
228        }
229
230        debug!("Dispatch loop exiting");
231    }
232}
233
234impl Drop for AsyncDispatcher {
235    fn drop(&mut self) {
236        self.stop_flag.store(true, Ordering::Relaxed);
237    }
238}
239
240#[cfg(test)]
241mod tests {
242    use super::*;
243    use crate::agents::BaseAsyncAgent;
244    use async_trait::async_trait;
245    use serde::{Deserialize, Serialize};
246    use std::any::Any;
247
248    #[derive(Debug, Clone, Serialize, Deserialize)]
249    struct TestEvent {
250        source: String,
251        correlation_id: Option<String>,
252        data: String,
253    }
254
255    impl Event for TestEvent {
256        fn source(&self) -> &str {
257            &self.source
258        }
259        fn correlation_id(&self) -> Option<&str> {
260            self.correlation_id.as_deref()
261        }
262        fn set_correlation_id(&mut self, id: String) {
263            self.correlation_id = Some(id);
264        }
265        fn as_any(&self) -> &dyn Any {
266            self
267        }
268        fn clone_box(&self) -> Box<dyn Event> {
269            Box::new(self.clone())
270        }
271    }
272
273    struct CountingAgent {
274        count: Arc<Mutex<usize>>,
275    }
276
277    #[async_trait]
278    impl BaseAsyncAgent for CountingAgent {
279        async fn receive_event_async(&self, _event: Box<dyn Event>) -> Result<Vec<Box<dyn Event>>> {
280            let mut count = self.count.lock().unwrap();
281            *count += 1;
282            Ok(vec![])
283        }
284    }
285
286    #[tokio::test]
287    async fn test_dispatcher_new() {
288        let router = Arc::new(Router::new());
289        let dispatcher = AsyncDispatcher::new(router);
290        assert!(dispatcher.task_handle.is_none());
291        assert_eq!(dispatcher.batch_size, 5);
292    }
293
294    #[tokio::test]
295    async fn test_dispatcher_with_batch_size() {
296        let router = Arc::new(Router::new());
297        let dispatcher = AsyncDispatcher::new(router).with_batch_size(10);
298        assert_eq!(dispatcher.batch_size, 10);
299    }
300
301    #[tokio::test]
302    async fn test_start_and_stop() {
303        let router = Arc::new(Router::new());
304        let mut dispatcher = AsyncDispatcher::new(router);
305
306        dispatcher.start().await.unwrap();
307        assert!(dispatcher.task_handle.is_some());
308
309        dispatcher.stop().await.unwrap();
310        assert!(dispatcher.task_handle.is_none());
311    }
312
313    #[tokio::test]
314    async fn test_start_twice_fails() {
315        let router = Arc::new(Router::new());
316        let mut dispatcher = AsyncDispatcher::new(router);
317
318        dispatcher.start().await.unwrap();
319        let result = dispatcher.start().await;
320        assert!(result.is_err());
321
322        dispatcher.stop().await.unwrap();
323    }
324
325    #[tokio::test]
326    async fn test_dispatch_event() {
327        let mut router = Router::new();
328        let count = Arc::new(Mutex::new(0));
329        let agent = Arc::new(CountingAgent {
330            count: count.clone(),
331        });
332
333        router.add_route::<TestEvent>(agent);
334
335        let mut dispatcher = AsyncDispatcher::new(Arc::new(router));
336        dispatcher.start().await.unwrap();
337
338        let event = Box::new(TestEvent {
339            source: "Test".to_string(),
340            correlation_id: Some("test-123".to_string()),
341            data: "test".to_string(),
342        }) as Box<dyn Event>;
343
344        dispatcher.dispatch(event);
345
346        dispatcher.wait_for_empty_queue(Some(Duration::from_secs(2))).await.unwrap();
347
348        let final_count = *count.lock().unwrap();
349        assert_eq!(final_count, 1);
350
351        dispatcher.stop().await.unwrap();
352    }
353
354    #[tokio::test]
355    async fn test_dispatch_assigns_correlation_id() {
356        let router = Arc::new(Router::new());
357        let mut dispatcher = AsyncDispatcher::new(router);
358        dispatcher.start().await.unwrap();
359
360        let event = Box::new(TestEvent {
361            source: "Test".to_string(),
362            correlation_id: None,
363            data: "test".to_string(),
364        }) as Box<dyn Event>;
365
366        dispatcher.dispatch(event);
367
368        dispatcher.wait_for_empty_queue(Some(Duration::from_secs(2))).await.unwrap();
369
370        dispatcher.stop().await.unwrap();
371    }
372
373    #[tokio::test]
374    async fn test_wait_for_empty_queue() {
375        let mut router = Router::new();
376        let count = Arc::new(Mutex::new(0));
377        let agent = Arc::new(CountingAgent {
378            count: count.clone(),
379        });
380
381        router.add_route::<TestEvent>(agent);
382
383        let mut dispatcher = AsyncDispatcher::new(Arc::new(router));
384        dispatcher.start().await.unwrap();
385
386        let event = Box::new(TestEvent {
387            source: "Test".to_string(),
388            correlation_id: Some("test-456".to_string()),
389            data: "test".to_string(),
390        }) as Box<dyn Event>;
391
392        dispatcher.dispatch(event);
393
394        let result = dispatcher.wait_for_empty_queue(Some(Duration::from_secs(2))).await.unwrap();
395
396        assert!(result);
397        assert_eq!(*count.lock().unwrap(), 1, "event should have been processed");
398        dispatcher.stop().await.unwrap();
399    }
400
401    #[tokio::test]
402    async fn test_wait_for_empty_queue_timeout() {
403        use std::sync::atomic::{AtomicUsize, Ordering};
404
405        struct SlowAgent {
406            processing_count: Arc<AtomicUsize>,
407        }
408
409        #[async_trait]
410        impl BaseAsyncAgent for SlowAgent {
411            async fn receive_event_async(
412                &self,
413                _event: Box<dyn Event>,
414            ) -> Result<Vec<Box<dyn Event>>> {
415                // Simulate slow processing
416                tokio::time::sleep(Duration::from_millis(200)).await;
417                self.processing_count.fetch_add(1, Ordering::Relaxed);
418                Ok(vec![])
419            }
420        }
421
422        let mut router = Router::new();
423        let processing_count = Arc::new(AtomicUsize::new(0));
424        let agent = Arc::new(SlowAgent {
425            processing_count: processing_count.clone(),
426        });
427        router.add_route::<TestEvent>(agent);
428
429        let mut dispatcher = AsyncDispatcher::new(Arc::new(router));
430        dispatcher.start().await.unwrap();
431
432        // Dispatch a single event with a 200ms handler, then use a 50ms timeout.
433        // The handler will still be in-flight when the timeout expires.
434        let event = Box::new(TestEvent {
435            source: "Test".to_string(),
436            correlation_id: Some("slow-0".to_string()),
437            data: "test".to_string(),
438        }) as Box<dyn Event>;
439        dispatcher.dispatch(event);
440
441        // Give a moment for the event to be dequeued and the handler to start
442        tokio::time::sleep(Duration::from_millis(50)).await;
443
444        // Timeout is shorter than the 200ms handler, so it should return false
445        let result =
446            dispatcher.wait_for_empty_queue(Some(Duration::from_millis(50))).await.unwrap();
447
448        assert!(!result); // Should timeout while handler is still in-flight
449
450        dispatcher.stop().await.unwrap();
451    }
452
453    #[tokio::test]
454    async fn test_queue_len() {
455        let router = Arc::new(Router::new());
456        let mut dispatcher = AsyncDispatcher::new(router);
457
458        assert_eq!(dispatcher.queue_len(), 0);
459
460        dispatcher.start().await.unwrap();
461
462        let event = Box::new(TestEvent {
463            source: "Test".to_string(),
464            correlation_id: Some("len-test".to_string()),
465            data: "test".to_string(),
466        }) as Box<dyn Event>;
467
468        dispatcher.dispatch(event);
469
470        dispatcher.wait_for_empty_queue(Some(Duration::from_secs(2))).await.unwrap();
471
472        dispatcher.stop().await.unwrap();
473    }
474
475    #[tokio::test]
476    async fn test_terminate_event_stops_dispatcher() {
477        let mut router = Router::new();
478        let count = Arc::new(Mutex::new(0));
479        let agent = Arc::new(CountingAgent {
480            count: count.clone(),
481        });
482
483        router.add_route::<TestEvent>(agent.clone());
484        router.add_route::<TerminateEvent>(agent);
485
486        let mut dispatcher = AsyncDispatcher::new(Arc::new(router));
487        dispatcher.start().await.unwrap();
488
489        // Send normal event
490        let event = Box::new(TestEvent {
491            source: "Test".to_string(),
492            correlation_id: Some("before-stop".to_string()),
493            data: "test".to_string(),
494        }) as Box<dyn Event>;
495
496        dispatcher.dispatch(event);
497
498        // Send terminate event
499        let terminate = Box::new(TerminateEvent::new("System")) as Box<dyn Event>;
500        dispatcher.dispatch(terminate);
501
502        // Wait for dispatcher to process both events (TerminateEvent sets stop_flag)
503        dispatcher.wait_for_empty_queue(Some(Duration::from_secs(5))).await.unwrap();
504
505        // Dispatcher should have stopped
506        assert!(dispatcher.stop_flag.load(Ordering::Relaxed));
507
508        dispatcher.stop().await.unwrap();
509    }
510
511    #[tokio::test]
512    async fn test_multiple_agents_receive_event() {
513        let mut router = Router::new();
514        let count1 = Arc::new(Mutex::new(0));
515        let count2 = Arc::new(Mutex::new(0));
516
517        let agent1 = Arc::new(CountingAgent {
518            count: count1.clone(),
519        });
520        let agent2 = Arc::new(CountingAgent {
521            count: count2.clone(),
522        });
523
524        router.add_route::<TestEvent>(agent1);
525        router.add_route::<TestEvent>(agent2);
526
527        let mut dispatcher = AsyncDispatcher::new(Arc::new(router));
528        dispatcher.start().await.unwrap();
529
530        let event = Box::new(TestEvent {
531            source: "Test".to_string(),
532            correlation_id: Some("multi-agent".to_string()),
533            data: "test".to_string(),
534        }) as Box<dyn Event>;
535
536        dispatcher.dispatch(event);
537
538        dispatcher.wait_for_empty_queue(Some(Duration::from_secs(2))).await.unwrap();
539
540        assert_eq!(*count1.lock().unwrap(), 1);
541        assert_eq!(*count2.lock().unwrap(), 1);
542
543        dispatcher.stop().await.unwrap();
544    }
545
546    /// Verify that `wait_for_empty_queue` only resolves after spawned agent
547    /// handlers have finished, not just when the queue drains.
548    #[tokio::test]
549    async fn test_wait_for_empty_queue_waits_for_in_flight_handlers() {
550        use std::sync::atomic::{AtomicUsize, Ordering as AtomicOrdering};
551
552        struct SlowCountingAgent {
553            count: Arc<AtomicUsize>,
554            delay_ms: u64,
555        }
556
557        #[async_trait]
558        impl BaseAsyncAgent for SlowCountingAgent {
559            async fn receive_event_async(
560                &self,
561                _event: Box<dyn Event>,
562            ) -> Result<Vec<Box<dyn Event>>> {
563                tokio::time::sleep(Duration::from_millis(self.delay_ms)).await;
564                self.count.fetch_add(1, AtomicOrdering::Relaxed);
565                Ok(vec![])
566            }
567        }
568
569        let mut router = Router::new();
570        let count = Arc::new(AtomicUsize::new(0));
571        let agent = Arc::new(SlowCountingAgent {
572            count: count.clone(),
573            delay_ms: 200,
574        });
575        router.add_route::<TestEvent>(agent);
576
577        let mut dispatcher = AsyncDispatcher::new(Arc::new(router));
578        dispatcher.start().await.unwrap();
579
580        let event = Box::new(TestEvent {
581            source: "Test".to_string(),
582            correlation_id: Some("in-flight-test".to_string()),
583            data: "test".to_string(),
584        }) as Box<dyn Event>;
585
586        dispatcher.dispatch(event);
587
588        // Wait enough time for the event to be dequeued (queue drains) but NOT
589        // enough for the 200ms handler to finish.
590        tokio::time::sleep(Duration::from_millis(50)).await;
591
592        // Queue is now empty but the handler is still running.
593        // wait_for_empty_queue must block until the handler completes.
594        let result = dispatcher.wait_for_empty_queue(Some(Duration::from_secs(2))).await.unwrap();
595
596        assert!(result, "wait_for_empty_queue should return true");
597        // The handler must have completed before we returned.
598        assert_eq!(count.load(AtomicOrdering::Relaxed), 1, "Handler should have run exactly once");
599
600        dispatcher.stop().await.unwrap();
601    }
602}