Flutter演员系统插件actor_system的功能使用

Flutter演员系统插件actor_system的功能使用

警告：ALPHA版本

此包处于早期开发阶段，可能会频繁发生破坏性更改。目前该包还没有测试用例。

演员系统 (Actor System)

这是一个在Dart中实现的演员模型 (Actor Model)。演员系统允许创建多个演员 (Actor)，并通过路径进行通信和查找。

功能特性

• 创建演员系统：作为演员的空间，所有在同一系统中的演员可以相互通信。
• 通过路径创建演员：每个演员都有一个唯一的路径。
• 通过路径查找演员：可以根据路径查找已有的演员。
• 发送消息给演员：可以向演员发送消息，消息会被放入演员的邮箱中，按顺序处理。
• 单线程处理消息：即使消息处理是异步的，也只会一次处理一条消息。
• 异常重启：如果消息处理过程中抛出异常，演员会自动重启。
• 使用构建器创建演员：可以通过构建器函数创建演员。
• 注册全局工厂：可以为特定路径注册全局工厂函数，用于创建演员。
• 连接多个演员系统：可以注册外部创建和查找函数，以连接多个演员系统。

使用方法

1. 定义演员 (Actor)

演员是一个接受上下文 (Context) 和消息 (Message) 的函数。演员函数不应该直接调用，而是由演员系统在收到消息时调用。

typedef Actor = FutureOr<void> Function(ActorContext ctx, Object? message);

例如，一个简单的演员实现如下：

void myActor(ActorContext ctx, Object? message) {
    print(message);
}

2. 定义演员工厂 (Actor Factory)

演员工厂是一个返回演员的函数，它根据给定的路径创建演员。

typedef ActorFactory = FutureOr<Actor> Function(Uri path);

例如，一个简单的工厂实现如下：

Actor myFactory(Uri path) {
    return myActor;
}

3. 创建演员系统并创建/查找演员

演员生活在演员系统中，演员系统提供了创建和查找演员的API。

final system = ActorSystem();
final actor1 = await system.createActor(Uri.parse('/foo/bar/1'), factory: myFactory);
final actor2 = await system.lookupActor(Uri.parse('/foo/bar/2'));

createActor() 和 lookupActor() 的返回值是一个演员引用 (ActorRef)，你可以使用这个引用来向演员发送消息。

final actor = await system.lookupActor(Uri.parse('/foo/bar'));
await actor.send('message1');
await actor.send('message2');

4. 处理演员的消息队列

发送给演员的消息会被放入演员的邮箱中，演员会按顺序处理这些消息。send() 函数返回的 Future 在消息被放入邮箱后完成。

5. 状态管理

演员本身是一个函数，不能直接存储状态。可以通过闭包来管理状态。

Actor countingActor() {
    var counter = 0;

    return (ctx, message) {
        counter++;
        print('received $message on call #${counter}');
    };
}

示例代码

以下是一个完整的示例代码，展示了如何使用 actor_system 插件创建演员系统、创建演员、查找演员以及发送消息。

import 'package:actor_system/actor_system.dart';

// 定义演员工厂
Actor actorFactory(Uri path) {
  // 演员的状态
  int calls = 0;

  // 消息处理器，处理所有发给该演员的消息
  return (ActorContext ctx, Object? msg) async {
    // 统计接收到的消息数量
    calls++;

    // 打印接收到的消息
    print(
        "actor: ${ctx.current.path}, sender: ${ctx.sender?.path} message: $msg, correlationId: ${ctx.correlationId}, call: $calls");

    // 将消息转发给回复者
    await ctx.replyTo?.send(msg);
  };
}

void main() async {
  // 创建演员系统
  final actorSystem = ActorSystem();

  // 创建两个演员
  final actorRef1 = await actorSystem.createActor(Uri.parse('/test/1'), factory: actorFactory);
  await actorSystem.createActor(Uri.parse('/test/2'), factory: actorFactory);

  // 查找演员
  final actorRef2 = await actorSystem.lookupActor(Uri.parse('/test/2'));

  // 向演员发送消息
  await actorRef1.send('message1', correlationId: '1', replyTo: actorRef2);
  await actorRef1.send('message2', correlationId: '2', replyTo: actorRef2);
}