1# ylong_runtime
2
3## 简介
4Rust异步运行时库,用于生成并执行异步任务。同时提供了异步网络 IO,异步文件 IO,定时器,异步同步原语,并行迭代器等功能。
5
6### 图1 整体架构图
7![structure](./figures/structure.png)
8
9- `System Service`:使用 Rust 异步能力的系统服务,包括上传下载、IPC、网络协议栈等;
10- `Runtime`:Rust 异步运行时,为依赖它的系统服务提供 Rust 异步编程界面和任务调度能力,从功能层次上可以分为 `ylong_runtime` 和 `ylong_io` 两层:
11  - `ylong_runtime`:异步运行时的功能主体,提供了大量 Rust 标准库接口的异步化接口,同时提供了对用户任务的生命周期管理和调度等能力;
12  - `ylong_io`:依赖 `libc` 库,结合系统的 epoll 机制,实现了非阻塞 TCP 和 UDP 功能,作为 `ylong_runtime` 异步 IO 的底座;
13- `libc`:Rust 三方库,提供对系统 libc 接口的 Rust 封装;
14- `Kernel`:操作系统内核提供的能力,如 socket,epoll 等。
15
16### 图2 仓中不同 crates 间的关系
17![inner_dependencies](./figures/inner_dependencies.png)
18
19`ylong_runtime`为功能主体,用户使用时直接依赖该库即可。`ylong_runtime` 依赖以下三个 crates:
20
21- `ylong_io`:提供了事件驱动型网络 IO,通过 epoll 实现了非阻塞性的 TCP 和 UDP。用户无需直接依赖该库。
22- `ylong_ffrt`:提供了 Function Flow Runtime 接口的 Rust 封装,可作为 `ylong_runtime` 的底层任务调度器。可通过 `ylong_runtime` 的 feature `ffrt` 来配置是否使用该调度器,OpenHarmony 上默认使用该调度器。用户无需直接依赖该库。
23- `ylong_macros`:实现 `ylong_runtime` 所需的过程宏,目前主要用于提供 `select!` 过程宏。可通过 `ylong_runtime` 的 feature `macros` 来配置是否使用该库,OpenHarmony上默认使用该库。用户无需直接依赖该库。
24
25### 图3 ylong_runtime 内部架构图
26![runtime_framework](./figures/runtime_framework.png)
27
28`ylong_runtime` 对外 API 分为四个模块:
29
30- `Sync`:异步同步原语,即可在异步上下文中使用的同步原语,包括异步的互斥锁、读写锁、信号量、通道等;
31- `Async IO`:异步网络 IO & 文件 IO,提供可在异步上下文中使用的 IO 接口,包括 TCP、UDP、文件的创建、关闭、读、写等;
32- `Parallel Calculation`:并行计算功能,支持将用户数据自动拆分为多个小任务并行处理,用户可以在异步上下文对任务的处理结果进行异步等待;
33- `Timer`:异步定时器,提供定时功能,包括异步的睡眠、间隔超时等;
34
35上述异步接口的特点是在异步上下文中进行等待不会阻塞当前线程,运行时会自动将线程切换到下一个可执行的任务去执行,从而避免线程资源的浪费,提高系统整体的并发能力。
36
37异步接口的这种能力是通过 `Reactor` 和 `Executor` 这两个模块实现的:
38
39- `Reactor`:进行 IO 系统事件以及 Timer 事件的监听,并通过监听到的事件唤醒阻塞的任务,将任务加入 `Executor` 的任务队列:
40  - `IO Driver`:IO 事件轮询器,定期查看是否有 IO 事件到来;
41  - `Timer Driver`:Timer 事件轮询器,定期查看是否有 Timer 将要超时;
42- `Executor`:进行任务调度以及任务执行的主体。用户提交的任务进入 `Executor` 的任务队列,并在合适的时机得到执行。执行过程中如遇到任务阻塞,则 `Executor` 按一定的策略选择下一个可执行的任务去执行。 `ylong_runtime` 拥有两个可互相替换的调度器:
43  - `ylong executor`:Rust 实现的任务调度器。
44  - `FFRT executor`:Function Flow Runtime 任务调度器,C++ 实现。OpenHarmony 上默认使用该实现。
45
46## 目录
47```
48ylong_runtime
49|── docs                            # 使用文档
50|── figures                         # 架构图
51|── patches                         # 门禁编译需要的补丁
52|── ylong_ffrt
53|    └── src                        # FFRT ffi封装
54|── ylong_io
55|    |── exmaples                   # ylong_io 代码示例
56|    |── src                        # ylong_io 源码
57|    |    └── sys                   # 操作系统相关io实现
58|    |         |── linux            # Linux 事件驱动IO实现
59|    |         └── windows          # Windows 事件驱动IO实现
60|── ylong_runtime
61|    |── benches                    # ylong_runtime 性能用例
62|    |── examples                   # ylong_runtime 代码示例
63|    |── src                        # ylong_runtime 源码
64|    |    |── builder               # Runtime builder实现
65|    |    |── executor              # Runtime executor实现
66|    |    |── ffrt                  # FFRT 适配
67|    |    |── fs                    # 异步文件IO实现
68|    |    |── io                    # 异步IO接口以及对外API
69|    |    |   └── buffered          # 异步缓存读写实现
70|    |    |── iter                  # 异步并行迭代器实现
71|    |    |   |── parallel          # 数据容器适配
72|    |    |   └── pariter           # 并行迭代核心业务实现
73|    |    |── net                   # 异步网络IO/Driver实现
74|    |    |   └── sys               # 系统IO异步实现
75|    |    |       └── tcp           # 异步TCP实现
76|    |    |── sync                  # 异步同步原语
77|    |    |   └── mpsc              # 单生产者多消费者通道实现
78|    |    |── task                  # 异步任务实现
79|    |    |── time                  # 定时器实现
80|    |    └── util                  # 公共组件
81|    |        |── core_affinity     # 绑核实现
82|    |        └── num_cpus          # 获取核数实现
83|    └── tests                      # ylong_runtime 测试用例
84└── ylong_runtime_macros
85     |── examples                   # ylong_runtime_macros 代码示例
86     └── src                        # ylong_runtime 过程宏实现
87```
88
89## 编译构建
90
91### 使用Cargo编译
921. 在 `Cargo.toml` 中引入 `ylong_runtime`
93```toml
94[dependencies]
95ylong_runtime = { git = "https://gitee.com/openharmony/commonlibrary_rust_ylong_runtime.git", features = ["full"]}
96```
97
98### 使用gn编译
991. 在`bundle.json`中添加`ylong_runtime`
100```
101"deps": {
102  "components": ["ylong_runtime"]
103}
104```
1052. 在`BUILD.gn`中添加`ylong_runtime:ylong_runtime`
106```
107external_deps = ["ylong_runtime:ylong_runtime"]
108```
109
110## 用户指南
111
112详细内容请见[用户指南](./docs/user_guide.md)
113
114## 致谢
115
116基于用户的使用习惯,本库的 API 在将原本 Rust 标准库同步的接口实现改为异步后,保留了标准库原本的命名风格,如 ``TcpStream::connect``、``File::read``、``File::write`` 等。同时也参考了 Tokio 的部分通用 API 设计思想,在此对 Rust 标准库和 Tokio 表示感谢。
117
118