actor-lite 0.1.1

基于 tokio 的轻量 actor 抽象:一份核(命令通道 + 状态/进度 + 事件 + 取消)+ 异步壳(tokio::spawn)与线程壳(独占线程,可装 !Send 资源)
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
//! Actor 管理器模块。
//!
//! [`ActorManager`] 是一个特殊的 [`AsyncActor`],它管理一组同类型的子 actor,
//! 并聚合它们的状态、进度和事件,对外暴露为单一 actor 接口。
//!
//! # 架构
//!
//! ```text
//! ActorManager (本身也是 AsyncActor)
//! ├── Child Actor 0  (id=1)
//! ├── Child Actor 1  (id=2)
//! └── Child Actor 2  (id=3)
//! ```
//!
//! - 每个子 actor 由 [`ActorManager`] 启动并分配一个唯一 `id`。
//! - 管理器自动监听子 actor 的状态、进度和事件,并聚合到自身的 [`ManagerState`] 和 [`ManagerProgress`] 中。
//! - 外部通过 [`ManagerCmd`] 向管理器发送命令:启动/停止子 actor,或转发命令给某个子 actor。
//!
//! # 限制
//!
//! manager 及其子 actor 目前都要求异步壳([`AsyncActor`]):子 actor 走 `tokio::spawn`,
//! 聚合用的 `tokio::time::interval` 也依赖 runtime。因此整个 manager 必须跑在 tokio runtime 里。
//!
//! # 示例
//!
//! ```no_run
//! # use actor_lite::{ActorCore, AsyncActor, ActorContext, ActorHandle};
//! # use actor_lite::manager::{ActorManager, ManagerCmd, ManagerState, ManagerProgress, ManagerEvent};
//! # struct MyActor;
//! # impl ActorCore for MyActor {
//! #     type Cmd = ();
//! #     type Event = ();
//! #     type State = ();
//! #     type Progress = ();
//! #     fn init_state_and_progress(&self) -> (Self::State, Self::Progress) { ((), ()) }
//! # }
//! # impl AsyncActor for MyActor {
//! #     fn run(self, context: ActorContext<Self>) -> impl std::future::Future<Output = ()> + Send + 'static {
//! #         async {}
//! #     }
//! # }
//! # async fn example() {
//! // 创建并启动 manager
//! let manager = ActorManager::<MyActor>::new();
//! let handle = manager.spawn();
//!
//! let (id_tx,id_rx) = tokio::sync::oneshot::channel();
//! handle.send_cmd(ManagerCmd::SpawnActor{actor:MyActor,id_tx:Some(id_tx)}).unwrap();
//! let id = id_rx.await.unwrap();
//! // 读取所有子 actor 的状态
//! let state: ManagerState<()> = handle.get_state();
//! assert_eq!(state.len(), 1);
//!
//! // 向指定子 actor 转发命令
//! handle.send_cmd(ManagerCmd::Forward { id: 1, cmd: () }).unwrap();
//!
//! // 停止指定子 actor
//! handle.send_cmd(ManagerCmd::StopActor(1)).unwrap();
//! # }
//! ```
use crate::async_actor::AsyncActor;
use crate::core::{ActorContext, ActorCore, ActorHandle, CancelToken};
use std::collections::HashMap;
use std::sync::atomic::{AtomicUsize, Ordering};
use tokio::sync::{broadcast, mpsc, oneshot};
use tokio::time::Duration;
use tracing::{debug, warn};

/// 子 actor 管理器。
///
/// `ActorManager` 本身实现了 [`AsyncActor`],因此可以像普通 actor 一样被 [`AsyncActor::spawn`]
/// 启动和持有。
///
/// 它管理一组同类型的子 actor,对外提供:
/// - 启动/停止子 actor
/// - 向指定子 actor 转发命令
/// - 聚合所有子 actor 的状态、进度和事件
///
/// # 类型参数
///
/// - `A`: 子 actor 的类型,必须实现 [`AsyncActor`]。
/// - `E`: 管理器事件通道(`broadcast`)的容量。
///
/// # 示例
///
/// ```no_run
/// # use actor_lite::{ActorCore, AsyncActor, ActorContext};
/// # use actor_lite::manager::{ActorManager, ManagerCmd};
/// # struct MyActor;
/// # impl ActorCore for MyActor {
/// #     type Cmd = ();
/// #     type Event = ();
/// #     type State = ();
/// #     type Progress = ();
/// #     fn init_state_and_progress(&self) -> (Self::State, Self::Progress) { ((), ()) }
/// # }
/// # impl AsyncActor for MyActor {
/// #     fn run(self, context: ActorContext<Self>) -> impl std::future::Future<Output = ()> + Send + 'static {
/// #         async {}
/// #     }
/// # }
/// # async fn example() {
/// let manager = ActorManager::<MyActor>::new();
/// let handle = manager.spawn();
///
/// // 启动子 actor,返回分配的 id
/// let (id_tx,id_rx) = tokio::sync::oneshot::channel();
/// handle.send_cmd(ManagerCmd::SpawnActor{actor:MyActor,id_tx:Some(id_tx)}).unwrap();
/// let id = id_rx.await.unwrap();
///
/// # }
/// ```
pub struct ActorManager<A: AsyncActor, const E: usize = 256> {
    actors: HashMap<usize, ActorHandle<A>>,
    next_id: AtomicUsize,
    state: ManagerState<A::State>,
    progress: ManagerProgress<A::Progress>,
    listeners: HashMap<usize, CancelListeners>,
    update_interval: Duration,
}

impl<A: AsyncActor, const E: usize> Default for ActorManager<A, E> {
    fn default() -> Self {
        Self::new()
    }
}

impl<A: AsyncActor, const E: usize> ActorManager<A, E> {
    /// 创建一个空的 `ActorManager`。
    ///
    /// 初始时不管理任何子 actor,需要启动后通过 [`ManagerCmd::SpawnActor`] 添加。
    pub fn new() -> Self {
        Self {
            actors: HashMap::new(),
            next_id: AtomicUsize::new(1),
            state: ManagerState {
                actors: HashMap::new(),
            },
            progress: ManagerProgress {
                actors: HashMap::new(),
            },
            listeners: HashMap::new(),
            update_interval: Duration::from_millis(500),
        }
    }
    pub fn set_update_interval(&mut self, interval: Duration) {
        self.update_interval = interval;
    }
    fn get_id(&self) -> usize {
        self.next_id.fetch_add(1, Ordering::SeqCst)
    }
    fn spawn_actor(
        &mut self,
        actor: A,
        update_tx: mpsc::Sender<Update>,
        event_tx: broadcast::Sender<ManagerEvent<A::Event>>,
    ) -> usize {
        let id = self.get_id();
        let handle = actor.spawn();
        let progress = Self::listen_progress(&handle, id, update_tx.clone());
        let state = Self::listen_state(&handle, id, update_tx);
        let events = Self::listen_events(&handle, id, event_tx);
        self.actors.insert(id, handle);
        self.listeners.insert(
            id,
            CancelListeners {
                state,
                progress,
                events,
            },
        );
        id
    }

    fn stop_actor(&mut self, id: usize) {
        if let Some(handle) = self.actors.remove(&id) {
            handle.stop();
        };
        self.state.actors.remove(&id);
        self.progress.actors.remove(&id);
        if let Some(listeners) = self.listeners.remove(&id) {
            listeners.stop_all();
        }
    }

    fn listen_state(
        handle: &ActorHandle<A>,
        id: usize,
        update_tx: mpsc::Sender<Update>,
    ) -> CancelToken {
        handle.state_listen_async(move |_| {
            let state_tx = update_tx.clone();
            async move {
                let _ = state_tx.send(Update::State(id)).await;
            }
        })
    }

    fn listen_progress(
        handle: &ActorHandle<A>,
        id: usize,
        update_tx: mpsc::Sender<Update>,
    ) -> CancelToken {
        handle.progress_listen_async(move |_| {
            let progress_tx = update_tx.clone();
            async move {
                let _ = progress_tx.send(Update::Progress(id)).await;
            }
        })
    }
    fn listen_events(
        handle: &ActorHandle<A>,
        id: usize,
        event_tx: broadcast::Sender<ManagerEvent<A::Event>>,
    ) -> CancelToken {
        handle.events_listen_async(move |event| {
            let events_tx = event_tx.clone();
            async move {
                let _ = events_tx.send(ManagerEvent::ChildEvent { id, event });
            }
        })
    }
}

impl<A: AsyncActor, const E: usize> ActorCore for ActorManager<A, E> {
    type Cmd = ManagerCmd<A>;
    type State = ManagerState<A::State>;
    type Progress = ManagerProgress<A::Progress>;
    type Event = ManagerEvent<A::Event>;
    const EVENT_CAPACITY: usize = E;

    fn init_state_and_progress(&self) -> (Self::State, Self::Progress) {
        (self.state.clone(), self.progress.clone())
    }
}
impl<A: AsyncActor, const E: usize> AsyncActor for ActorManager<A, E> {
    fn run(self, context: ActorContext<Self>) -> impl Future<Output = ()> + Send + 'static {
        let mut context = context;
        let mut manager = self;
        let cancel = context.cancel_clone();

        async move {
            let (update_tx, mut update_rx) = mpsc::channel::<Update>(256);
            let mut push_interval = tokio::time::interval(manager.update_interval);
            push_interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
            loop {
                tokio::select! {
                    _ = cancel.cancelled() => { debug!("Manager 被 cancel 了!");break},
                    Some(cmd) = context.wait_for_cmd() => {
                        match cmd {
                            ManagerCmd::SpawnActor{actor, id_tx} => {
                                let id = manager.spawn_actor(actor, update_tx.clone(), context.get_events_clone());
                                if let Some(tx) = id_tx{
                                    let _ = tx.send(id);
                                }
                                context.send_event(ManagerEvent::Spawned { id });
                            }
                            ManagerCmd::StopActor(id) => {
                                manager.stop_actor(id);
                                context.update_state(manager.state.clone());
                                context.update_progress(manager.progress.clone());
                                context.send_event(ManagerEvent::Stopped { id });
                            }
                            ManagerCmd::Forward { id, cmd } => {
                                match manager.actors.get(&id) {
                                    Some(handle) => {
                                        if handle.send_cmd(cmd).is_err() {
                                            warn!("子Actor已经停止了: id={id}");
                                        }
                                    }
                                    None => warn!("没有找到id对应的子Actor: id={id}"),
                                }
                            }
                        }
                    }
                    Some(update) = update_rx.recv() => {
                        match update {
                            Update::State(id) => {
                                if let Some(handle) = manager.actors.get(&id) {
                                    let state = handle.get_state();
                                    manager.state.actors.insert(id, state);
                                    context.update_state(manager.state.clone());
                                }
                            }
                            Update::Progress(id) => {
                                if let Some(handle) = manager.actors.get(&id) {
                                    let progress = handle.get_progress();
                                    manager.progress.actors.insert(id, progress);
                                }
                            }
                        }
                        }
                    _ = push_interval.tick() => {
                        context.update_progress(manager.progress.clone());
                    }
                }
            }
        }
    }
}

enum Update {
    State(usize),
    Progress(usize),
}

struct CancelListeners {
    state: CancelToken,
    progress: CancelToken,
    events: CancelToken,
}

impl CancelListeners {
    fn stop_all(self) {
        self.state.cancel();
        self.progress.cancel();
        self.events.cancel();
    }
}

/// 管理器的命令枚举。
///
/// 通过 [`ActorHandle::send_cmd`] 发送给 [`ActorManager`],控制子 actor 的生命周期和通信。
///
/// # 变体
///
/// | 变体 | 说明 |
/// |------|------|
/// | [`ManagerCmd::SpawnActor`] | 启动一个新的子 actor,可以选择返回分配的 `id`(通过oneshot通道) |
/// | [`ManagerCmd::StopActor`] | 停止指定 `id` 的子 actor |
/// | [`ManagerCmd::Forward`] | 向指定 `id` 的子 actor 转发一条命令 |
///
/// # 示例
///
/// ```no_run
/// # use actor_lite::{ActorCore, AsyncActor, ActorContext};
/// # use actor_lite::manager::{ActorManager, ManagerCmd};
/// # struct MyActor;
/// # impl ActorCore for MyActor {
/// #     type Cmd = String;
/// #     type Event = ();
/// #     type State = ();
/// #     type Progress = ();
/// #     fn init_state_and_progress(&self) -> (Self::State, Self::Progress) { ((), ()) }
/// # }
/// # impl AsyncActor for MyActor {
/// #     fn run(self, context: ActorContext<Self>) -> impl std::future::Future<Output = ()> + Send + 'static {
/// #         async {}
/// #     }
/// # }
/// # async fn example() {
/// let handle = ActorManager::<MyActor>::new().spawn();
///
/// // 启动子 actor
/// let (id_tx,id_rx) = tokio::sync::oneshot::channel();
/// handle.send_cmd(ManagerCmd::SpawnActor{actor:MyActor,id_tx:Some(id_tx)}).unwrap();
/// let id = id_rx.await.unwrap();
/// // 转发命令给 id=1 的子 actor
/// handle.send_cmd(ManagerCmd::Forward { id: 1, cmd: "hello".into() }).unwrap();
///
/// // 停止 id=1 的子 actor
/// handle.send_cmd(ManagerCmd::StopActor(1)).unwrap();
/// # }
/// ```
pub enum ManagerCmd<A: AsyncActor> {
    /// 启动一个新的子 actor。
    ///
    /// 管理器会为其分配唯一 `id`,并通过 [`ManagerEvent::Spawned`] 事件通知。
    SpawnActor {
        actor: A,
        id_tx: Option<oneshot::Sender<usize>>,
    },
    /// 停止指定 `id` 的子 actor。
    ///
    /// 停止后通过 [`ManagerEvent::Stopped`] 事件通知。
    StopActor(usize),
    /// 向指定 `id` 的子 actor 转发一条命令。
    ///
    /// 若 `id` 不存在,命令会被静默丢弃。
    Forward { id: usize, cmd: A::Cmd },
}

/// 管理器聚合的所有子 actor 状态。
///
/// 以 `id` 为键,存储每个子 actor 的最新状态。
/// 通过 [`ActorHandle::get_state`] 获取。
///
/// # 示例
///
/// ```no_run
/// # use actor_lite::{ActorCore, AsyncActor, ActorContext};
/// # use actor_lite::manager::{ActorManager, ManagerState};
/// # struct MyActor;
/// # impl ActorCore for MyActor {
/// #     type Cmd = ();
/// #     type Event = ();
/// #     type State = u32;
/// #     type Progress = ();
/// #     fn init_state_and_progress(&self) -> (Self::State, Self::Progress) { (0, ()) }
/// # }
/// # impl AsyncActor for MyActor {
/// #     fn run(self, context: ActorContext<Self>) -> impl std::future::Future<Output = ()> + Send + 'static {
/// #         async {}
/// #     }
/// # }
/// # async fn example() {
/// # let handle = ActorManager::<MyActor>::new().spawn();
/// let state: ManagerState<u32> = handle.get_state();
///
/// // 按 id 读取
/// if let Some(&42) = state.get(1) {
///     println!("actor 1 的状态是 42");
/// }
///
/// // 遍历所有子 actor 状态
/// for (id, s) in state.iter() {
///     println!("actor {id}: {s}");
/// }
///
/// println!("共 {} 个子 actor", state.len());
/// # }
/// ```
#[derive(Debug, Clone)]
pub struct ManagerState<State> {
    actors: HashMap<usize, State>,
}

impl<State> ManagerState<State> {
    /// 按 `id` 读取某个子 actor 的状态。
    pub fn get(&self, id: usize) -> Option<&State> {
        self.actors.get(&id)
    }

    /// 遍历所有子 actor 的状态,返回 `(id, &state)` 迭代器。
    pub fn iter(&self) -> impl Iterator<Item = (usize, &State)> {
        self.actors.iter().map(|(&id, s)| (id, s))
    }

    /// 当前管理的子 actor 数量。
    pub fn len(&self) -> usize {
        self.actors.len()
    }

    /// 是否没有子 actor。
    pub fn is_empty(&self) -> bool {
        self.actors.is_empty()
    }
}

/// 管理器聚合的所有子 actor 进度。
///
/// 以 `id` 为键,存储每个子 actor 的最新进度。
/// 进度会定时(每秒)推送到管理器的 `progress` 通道。
///
/// # 示例
///
/// ```no_run
/// # use actor_lite::{ActorCore, AsyncActor, ActorContext};
/// # use actor_lite::manager::{ActorManager, ManagerProgress};
/// # struct MyActor;
/// # impl ActorCore for MyActor {
/// #     type Cmd = ();
/// #     type Event = ();
/// #     type State = ();
/// #     type Progress = f32;
/// #     fn init_state_and_progress(&self) -> (Self::State, Self::Progress) { ((), 0.0) }
/// # }
/// # impl AsyncActor for MyActor {
/// #     fn run(self, context: ActorContext<Self>) -> impl std::future::Future<Output = ()> + Send + 'static {
/// #         async {}
/// #     }
/// # }
/// # async fn example() {
/// # let handle = ActorManager::<MyActor>::new().spawn();
/// let progress: ManagerProgress<f32> = handle.get_progress();
///
/// for (id, p) in progress.iter() {
///     println!("actor {id} 进度: {:.1}%", p * 100.0);
/// }
/// # }
/// ```
#[derive(Debug, Clone)]
pub struct ManagerProgress<Progress> {
    actors: HashMap<usize, Progress>,
}

impl<Progress> ManagerProgress<Progress> {
    /// 按 `id` 读取某个子 actor 的进度。
    pub fn get(&self, id: usize) -> Option<&Progress> {
        self.actors.get(&id)
    }

    /// 遍历所有子 actor 的进度,返回 `(id, &progress)` 迭代器。
    pub fn iter(&self) -> impl Iterator<Item = (usize, &Progress)> {
        self.actors.iter().map(|(&id, s)| (id, s))
    }

    /// 当前管理的子 actor 数量。
    pub fn len(&self) -> usize {
        self.actors.len()
    }

    /// 是否没有子 actor。
    pub fn is_empty(&self) -> bool {
        self.actors.is_empty()
    }
}

/// 管理器发出的事件枚举。
///
/// 聚合了所有子 actor 的事件以及管理器自身的生命周期事件。
/// 通过 [`ActorHandle::get_events_rx`] 或 `events_listen_async` 订阅。
///
/// # 变体
///
/// | 变体 | 说明 |
/// |------|------|
/// | [`ManagerEvent::ChildEvent`] | 某个子 actor 发出的事件,附带其 `id` |
/// | [`ManagerEvent::Spawned`] | 新子 actor 已启动,附带分配的 `id` |
/// | [`ManagerEvent::Stopped`] | 子 actor 已停止,附带其 `id` |
///
/// # 示例
///
/// ```no_run
/// # use actor_lite::{ActorCore, AsyncActor, ActorContext};
/// # use actor_lite::manager::{ActorManager, ManagerEvent};
/// # struct MyActor;
/// # impl ActorCore for MyActor {
/// #     type Cmd = ();
/// #     type Event = String;
/// #     type State = ();
/// #     type Progress = ();
/// #     fn init_state_and_progress(&self) -> (Self::State, Self::Progress) { ((), ()) }
/// # }
/// # impl AsyncActor for MyActor {
/// #     fn run(self, context: ActorContext<Self>) -> impl std::future::Future<Output = ()> + Send + 'static {
/// #         async {}
/// #     }
/// # }
/// # async fn example() {
/// let handle = ActorManager::<MyActor>::new().spawn();
/// let mut rx = handle.get_events_rx();
///
/// while let Ok(event) = rx.recv().await {
///     match event {
///         ManagerEvent::ChildEvent { id, event } => {
///             println!("actor {id} 发出事件: {event}");
///         }
///         ManagerEvent::Spawned { id } => {
///             println!("新 actor 已启动,id={id}");
///         }
///         ManagerEvent::Stopped { id } => {
///             println!("actor {id} 已停止");
///         }
///     }
/// }
/// # }
/// ```
#[derive(Debug, Clone)]
pub enum ManagerEvent<Event> {
    /// 某个子 actor 发出的事件。
    ChildEvent { id: usize, event: Event },
    /// 新子 actor 已启动,`id` 为其分配的标识。
    Spawned { id: usize },
    /// 子 actor 已停止,`id` 为其标识。
    Stopped { id: usize },
}