# commonlibrary_rust_ylong_light_actor

**Repository Path**: xue-lei3/commonlibrary_rust_ylong_light_actor

## Basic Information

- **Project Name**: commonlibrary_rust_ylong_light_actor
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/openharmony-sig/commonlibrary_rust_ylong_light_actor
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2023-06-19
- **Last Updated**: 2023-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ylong_light_actor

## 简介

ylong_light_actor 提供了两个功能模块：Actor 和 EventHandler.

### Actor

Actor 编程模型是一种并发编程模型，旨在解决并发编程中使用传统的内存共享模型带来的数据竞争以及加锁导致的性能损失及死锁等问题。

一个 Actor 由state、mailbox以及run（逻辑执行）三部分组成：

- state是actor的内部数据，actor会确保对其访问不会有数据竞争；
- mailbox是actor的消息队列，外部对actor的访问将通过发消息进行，队列是FIFO的，确保访问按顺序进行，不会并发；
- run用来读取mailbox中的消息并执行处理该消息的逻辑，run中可以访问和改变state。

通过 Actor 编程模型可以简化并发编程中需要进行数据共享的场景，减少锁的使用，让用户更多地关注业务逻辑的实现，而不是对数据的并发保护。Rust Actor编程框架将为Rust开发用户提供一种可选的并发编程模型。

### EventHandler

EventHandler 提供一种机制，用于处理线程间通信，可以通过创建新线程，将耗时的操作放到新线程上执行。这样既不阻塞原来的线程，任务又可以得到合理的处理。

EventHandler 支持以下功能：

- 支持线程保活及生命周期的自动管理；
- 支持线程之间发送消息/任务；
- 支持发送优先级不等的消息/任务；
- 支持发送延时消息/任务；
- 支持消息/任务顺序处理/执行；
- 支持删除指定消息/任务；
- 支持查询指定消息/任务是否存在；

### ylong_light_actor 在 OpenHarmony中的位置
ylong_light_actor 向 OpenHarmony 系统服务层提供具有线程间通信能力的并发编程模型，基于异步运行时向上层提供便利的线程间任务处理能力。

![actor_framework](./figures/actor_framework.jpg)

以下是对于上图关键字段的描述信息：

- `SA`: 需要使用并发编程模型的系统服务。
- `ylong_light_actor`:提供并发编程模型的系统组件。
  - `Actor`: 简化多线程中数据共享场景的并发编程模型。
  - `EventHandler`: 处理耗时任务的并发编程模型。
- `ylong_runtime`: `ylong` 提供的 Rust 异步运行时库。

### ylong_light_actor 的内部架构

![inner_framework](./figures/inner_framework.jpg)

`ylong_light_actor` 内部提供两个模型： `Actor` 和 `EventHandler`。

两个模型共同依赖一套公共组件进行实现：

- `InnerEvent`: 线程之间消息传递的实体封装，支持封装有参闭包、无参闭包和事件ID三种类型。
- `InnerQueue`: 优先级队列中的队列单元,保存管理 `InnerEvent`。
- `EventQueue`: 线程消息队列，管理由 `InnerQueue` 组成的优先级队列，提供消息延时处理及唤醒等功能。
- `Dispatcher`: 异步任务调度框架，基于 `ylong_runtime` 实现。
- `EventRunner`: 事件循环器，结合 `EventQueue` 和 `Dispatcher` 实现队列在线程中的调度与运行。

在公共组件外，两个模型依赖各自所需的 `trait` 进行创建及运行。

`Actor` 模型：

- `ToActor`: 允许用户将自定义类型申明为`Actor`类型。
- `Handler`: 自定义可处理的消息类型，并定义处理消息的方法。

`EvenrHandler`模型：

- `ToEventHandler`: 允许用户将自定义类型申明为`EventHandler`类型，并定义ID事件的消息处理函数。
- `DistributeEvent`: 提供事件类型匹配的函数，自动为实现了 `ToEventHandler` 的类型实现。

## 编译构建

在您的 BUILD.gn 需要的地方添加依赖即可。

```json
deps += ["//commonlibrary/rust/ylong_light_actor:lib"]
```

如果您需要使用 Cargo 的方式进行依赖，可以在自己的 Rust 工程的 Cargo.toml 下添加如下字段：

如果您的本地环境上存在 ylong_light_actor 库，您可以使用路径依赖：

```toml
[dependencies]
ylong_light_actor = { git = "https://gitee.com/openharmony-sig/commonlibrary_rust_ylong_light_actor.git" }
```


## 目录

```
ylong_light_actor
├── examples                               # ylong_light_actor 代码示例
└── src 
    ├── event_handler
    │   ├── event_queue                     # 线程消息队列，管理 InnerEvent。
    │   ├── handler                         # 用户在当前线程上投递 InnerEvent 事件到异步线程上处理的机制。
    │   ├── inner_event                     # 线程之间消息传递的实体封装。
    │   ├── inner_queue                     # 优先级队列中的队列单元。
    │   └── runner                          # 事件循环器。
    └── dispatcher							# 管理Actor所运行的调度框架。
```

## 用户指南

详情内容请见[用户指南](./docs/user_guide.md)