Skip to main content

Actor

Trait Actor 

Source
pub trait Actor:
    Sized
    + Send
    + 'static {
    type Cmd: Send + 'static;
    type Event: Clone + Send + 'static;
    type State: Clone + Send + Sync + 'static;
    type Progress: Clone + Send + Sync + 'static;

    const CMD_CAPACITY: usize = 16;
    const EVENT_CAPACITY: usize = 16;

    // Required methods
    fn init_state_and_progress(&self) -> (Self::State, Self::Progress);
    fn run(
        self,
        context: ActorContext<Self>,
    ) -> impl Future<Output = ()> + Send + 'static;

    // Provided methods
    fn channel(
        init_state: Self::State,
        init_progress: Self::Progress,
    ) -> (ActorContext<Self>, ActorHandle<Self>) { ... }
    fn spawn(self) -> ActorHandle<Self> { ... }
}
Expand description

Actor 模型的核心 trait。

实现此 trait 来定义一个 actor 的行为。每个 actor 有四个关联类型:

类型说明
Cmd命令枚举,外部通过它向 actor 发送指令
Event事件类型,actor 对外广播的异步消息
State低频状态,变化不频繁,可随时读取最新值
Progress高频进度,适合进度条、实时指标等场景

§生命周期

  1. 调用 Actor::spawn 启动 actor,得到 ActorHandle
  2. 通过 ActorHandle 发送命令、读取状态/进度、订阅事件
  3. 调用 ActorHandle::stop 或 drop handle 来停止 actor

§示例

struct Counter {
    target: u32,
}

enum CounterCmd {
    Reset,
}

impl Actor for Counter {
    type Cmd = CounterCmd;
    type Event = u32;
    type State = u32;
    type Progress = f32;

    fn init_state_and_progress(&self) -> (Self::State, Self::Progress) {
        (0, 0.0)
    }

    fn run(self, context: ActorContext<Self>) -> impl std::future::Future<Output = ()> + Send + 'static {
        let mut context = context;
        async move {
            let mut count = 0u32;
            loop {
                if let Some(cmd) = context.check_cmd() {
                    match cmd {
                        CounterCmd::Reset => {
                            count = 0;
                            context.update_state(count);
                            context.update_progress(0.0);
                        }
                    }
                }
                if count >= self.target {
                    break;
                }
                count += 1;
                context.update_state(count);
                context.update_progress(count as f32 / self.target as f32);
                context.send_event(count);
            }
        }
    }
}

Provided Associated Constants§

Source

const CMD_CAPACITY: usize = 16

actor 的命令通道容量

Source

const EVENT_CAPACITY: usize = 16

actor 的事件通道容量

Required Associated Types§

Source

type Cmd: Send + 'static

actor 命令枚举

例如:

enum MyCmd {
    Start,
    Pause,
    //...
}
Source

type Event: Clone + Send + 'static

actor 里的事件结构体,需要实现Clone

Source

type State: Clone + Send + Sync + 'static

actor 里的低频状态,如果不需要,用 type State = ();。

Source

type Progress: Clone + Send + Sync + 'static

actor 里的高频状态,如果没有高频进度时,用 type Progress = ();。

Required Methods§

Source

fn init_state_and_progress(&self) -> (Self::State, Self::Progress)

Source

fn run( self, context: ActorContext<Self>, ) -> impl Future<Output = ()> + Send + 'static

actor的主要循环

运行 actor 的主要逻辑。

§注意

接收后台端并自行决定循环和发送事件,更新状态的流程

§示例
struct MyActor;
impl Actor for MyActor {
    type Cmd = ();
    type Event = ();
    type State = ();
    type Progress = ();
    fn init_state_and_progress(&self) -> (Self::State, Self::Progress) {
        ((), ())
    }
    fn run(self, context: ActorContext<Self>) -> impl Future<Output = ()> + Send + 'static {
        let mut context = context;
    async move {
     
        loop {
        if let Some(cmd) = context.check_cmd() {
            // ...处理命令
            }
         //...主要逻辑

         //发送事件和进度,更新状态
         context.send_event(());
         context.update_progress(());
         context.update_state(());
      }
    }
  }
}

Provided Methods§

Source

fn channel( init_state: Self::State, init_progress: Self::Progress, ) -> (ActorContext<Self>, ActorHandle<Self>)

创建 actor 的通道。 ActorContext 是 actor 的后台端,ActorHandle 是 actor 的控制端。

Source

fn spawn(self) -> ActorHandle<Self>

启动 actor。

返回 actor 的控制端。

外部通过 ActorHandle 的方法发送命令、监听状态/进度、订阅事件。

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§