1# ylong_runtime
2
3## Introduction
4Rust asynchronous runtime, provides functionalities such as spawning async tasks, async io, async synchronization primitives, parallel calculation.
5
6### Overall structure
7![structure](./figures/structure.png)
8
9- `System Service`: System services that use Rust's asynchronous capabilities, including Request, IPC, NetStack, etc.
10- `Runtime`: Rust asynchronous runtime provides Rust asynchronous programming interface and task scheduling capabilities for system services. From the functional level, it can be divided into two layers: `ylong_runtime` and `ylong_io`:
11   - `ylong_runtime`: The functional body of the asynchronous runtime, which provides a large number of asynchronous version of the Rust std library interfaces, and also provides capabilities such as life cycle management and scheduling of user tasks.
12   - `ylong_io`: Relying on the `libc` library, combined with the epoll mechanism of the system, providing the non-blocking TCP and UDP functions, as the base of `ylong_runtime` asynchronous IO.
13- `libc`: Rust third party library, providing Rust encapsulation of system libc interface.
14- `Kernel`: Capabilities provided by the operating system kernel, such as socket, epoll, etc.
15
16### Crates inner relations
17![inner_dependencies](./figures/inner_dependencies.png)
18
19`ylong_runtime` is the main crate of the repository, and users can directly rely on this library when using it. `ylong_runtime` depends on the following three crates:
20
21- `ylong_io`: Provides nonblocking and event-driven TCP/UDP through epoll. Users do not need to directly depend on this library.
22- `ylong_ffrt`: Provides a Rust wrapper of the Function Flow Runtime interface, which can be used as the underlying task scheduler of `ylong_runtime`. Users can configure whether to use this scheduler through the feature `ffrt` of `ylong_runtime`, and this scheduler is used by default on OpenHarmony. Users do not need to directly depend on this library.
23- `ylong_macros`: The procedural macros required to implement `ylong_runtime`, currently mainly used to provide `select!` procedural macros. Users can configure whether to use this library through the feature `macros` of `ylong_runtime`, which is used by default on OpenHarmony. Users do not need to directly depend on this library.
24
25### ylong_runtime framework
26![runtime_framework](./figures/runtime_framework.png)
27
28`ylong_runtime` external API is divided into four modules:
29
30- `Sync`: Asynchronous synchronization primitives, which can be used in an asynchronous context, including asynchronous mutex, read-write lock, semaphore, channel, etc.
31- `Async IO`: Asynchronous network IO & file IO, providing IO interfaces that can be used in an asynchronous context, including creation, closing, reading, writing of TCP, UDP, file.
32- `Parallel Calculation`: Parallel computing function, which supports automatic splitting of user data into multiple small tasks for parallel processing, and users can asynchronously wait for the processing results of tasks in an asynchronous context.
33- `Timer`: asynchronous timer, providing timing functions, including asynchronous sleep, interval, etc.
34
35The feature of the asynchronous interface is that waiting in the asynchronous context will not block the current thread, and the thread will automatically switch to the next executable task, thereby avoiding the waste of thread resources and improving the overall concurrency of the system.
36
37This capability of asynchronous interfaces is achieved through the `Reactor` and `Executor` modules:
38
39- `Reactor`: Monitors IO system events and Timer events, wakes up blocked tasks through the monitored events, and pushes the tasks to the task queue of `Executor`:
40   - `IO Driver`: IO event poller, checks whether there are IO events coming;
41   - `Timer Driver`: Timer event poller, checks whether a Timer is about to time out;
42- `Executor`: The subject of task scheduling and task execution. The task submitted by the user enters the task queue of `Executor` and is executed at the appropriate time. If a task is blocked during execution, `Executor` will select the next executable task to execute according to some strategies. `ylong_runtime` has two schedulers that are interchangeable:
43   - `ylong executor`: A task scheduler implemented in Rust.
44   - `FFRT executor`: Function Flow Runtime task scheduler, implemented in C++. This implementation is used by default on OpenHarmony.
45
46## Compile
47
48### Use Cargo
491. Introduce `ylong_runtime` in `Cargo.toml`
50
51```toml
52[dependencies]
53ylong_runtime = { git = "https://gitee.com/openharmony/commonlibrary_rust_ylong_runtime.git", features = ["full"]}
54```
55### Use gn
561. add `ylong_runtime` in bundle.json
57
58```
59"deps": {
60   "components": ["ylong_runtime"]
61}
62```
63
642. add `ylong_runtime:ylong_runtime` in `BUILD.gn`
65
66```
67external_deps = ["ylong_runtime:ylong_runtime"]
68```
69
70## Directory
71```
72ylong_runtime
73|── docs                            # User guide
74|── figures                         # Structure figures in docspo
75|── patches                         # Patches for ci
76|── ylong_ffrt
77|    └── src                        # FFRT rust ffi
78|── ylong_io
79|    |── exmaples                   # Examples of ylong_io
80|    |── src                        # Source code of ylong_io
81|    |    └── sys                   # OS specific implementation
82|    |         |── linux            # Epoll driven io
83|    |         └── windows          # Iocp driven io
84|── ylong_runtime
85|    |── benches                    # Benchmarks of ylong_runtime
86|    |── examples                   # Examples of ylong_runtime
87|    |── src                        # Source code of ylong_runtime
88|    |    |── builder               # Runtime builder
89|    |    |── executor              # Runtime executor
90|    |    |── ffrt                  # FFRT adapter
91|    |    |── fs                    # Async fs components
92|    |    |── io                    # Async io traits and components
93|    |    |   └── buffered          # Async BufReader and BufWriter
94|    |    |── iter                  # Async parallel iterator
95|    |    |   |── parallel          # ParIter implementation for data containers
96|    |    |   └── pariter           # Core of pariter
97|    |    |── net                   # Async net io and net driver
98|    |    |   └── sys               # Async system io
99|    |    |       └── tcp           # Async Tcp
100|    |    |── sync                  # Runtime synchronization components
101|    |    |   └── mpsc              # Mpsc channels
102|    |    |── task                  # Async task components
103|    |    |── time                  # Timer components
104|    |    └── util                  # Utilities
105|    |        |── core_affinity     # Vore affinity components
106|    |        └── num_cpus          # Num cpus components
107|    └── tests                      # Sdv of ylong_runtime
108└── ylong_runtime_macros
109     |── examples                   # Examples of ylong_macro
110     └── src                        # Procedural macro implementation for runtime
111```
112
113## User Guide
114
115See [user_guide](./docs/user_guide.md).
116
117## Acknowledgements
118
119Based on the user's habit, the API of this library, after changing the original Rust standard library synchronous interface implementation to asynchronous, retains the original naming style of the standard library, such as ``TcpStream::connect``, ``File::read``, ``File::write`` and so on. We also refer to some of Tokio's general API design ideas, and we would like to express our gratitude to the Rust standard library and Tokio.
120
121