diff --git a/README.md b/README.md index c464504d20..509818e355 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ int main() * This project has built-in **service governance** and **load balancing** features. * Wiki link : [PaaS Architecture](https://github.com/sogou/workflow/wiki) -#### Compiling and running environment +#### Compiling and Running Environment * This project supports `Linux`, `macOS`, `Windows`, `Android` and other operating systems. * `Windows` version is currently released as an independent [branch](https://github.com/sogou/workflow/tree/windows), using `iocp` to implement asynchronous networking. All user interfaces are consistent with the `Linux` version. @@ -53,7 +53,7 @@ int main() * Uses the `C++11` standard and therefore, it should be compiled with a compiler which supports `C++11`. Does not rely on `boost` or `asio`. * No other dependencies. However, if you need `Kafka` protocol, some compression libraries should be installed, including `lz4`, `zstd` and `snappy`. -### Get started (Linux, macOS): +### Get Started (Linux, macOS): ~~~sh git clone https://github.com/sogou/workflow cd workflow @@ -134,9 +134,9 @@ If you want to use xmake to build workflow, you can see [xmake build document](d * [Asynchronous MySQL client：mysql\_cli](docs/en/tutorial-12-mysql_cli.md) * [Asynchronous Kafka client: kafka\_cli](docs/en/tutorial-13-kafka_cli.md) -#### Programming paradigm +#### Programming Paradigm -We believe that a typical back-end program=protocol+algorithm+workflow and should be developed completely independently. +Program = Protocol + Algorithm + Workflow * Protocol * In most cases, users use built-in common network protocols, such as HTTP, Redis or various rpc. @@ -151,35 +151,34 @@ We believe that a typical back-end program=protocol+algorithm+workflow and shoul * The typical workflow is a closed series-parallel graph. Complex business logic may be a non-closed DAG. * The workflow graph can be constructed directly or dynamically generated based on the results of each step. All tasks are executed asynchronously. -Basic task, task factory and complex task +Structured Concurrency and Task Abstraction -* Our system contains six basic tasks: networking, file IO, CPU, GPU, timer, and counter. -* All tasks are generated by the task factory and automatically recycled after callback. - * Server task is one kind of special networking task, generated by the framework which calls the task factory, and handed over to the user through the process function. -* In most cases, the task generated by the user through the task factory is a complex task, which is transparent to the user. +* Our system contains five basic tasks: communication, computation, file IO, timer, and counter. +* All tasks are generated by the task factory, and users organize the concurrency structure by calling interfaces, such as series, parallel, DAG, etc. +* In most cases, the tasks generated by the user through the task factory is a complex task which encapsulates multiple asynchronous processes, but it is transparent to the user. * For example, an HTTP request may include many asynchronous processes (DNS, redirection), but for user, it is just a networking task. * File sorting seems to be an algorithm, but it actually includes many complex interaction processes between file IO and CPU computation. * If you think of business logic as building circuits with well-designed electronic components, then each electronic component may be a complex circuit. + * The task abstraction mechanism greatly reduces the number of tasks users need to create and the depth of callbacks. +* Any task runs in a **SeriesWork** and the tasks in the same SeriesWork shares the series context, which simplifies data transfer between asynchronous tasks. -Asynchrony and encapsulation based on `C++11 std::function` +Callback and Memory Reclamation Mechanism -* Not based on user mode coroutines. Users need to know that they are writing asynchronous programs. * All calls are executed asynchronously, and there is almost no operation that occupies a thread. - * Although we also provide some facilities with semi-synchronous interfaces, they are not core features. +* Explicit callback mechanism. Users are aware that they are writing asynchronous programs. +* **A set of object lifecycle mechanisms greatly simplifies memory management for asynchronous programs.** + * The lifecycle of any task created by the framework is from creation until the callback function finishes running. There is no risk of leakage. + * If a task is created but the user does not want to run it, the user needs to release it through the `dismiss()` interface. + * Any data in the task, such as the response of the network request, will also be recycled with the task. At this time, the user can use `std::move()` to move the required data. + * The project doesn’t use `std::shared_ptr` to manage memory. + * We try to avoid user's derivations, and encapsulate user behavior with `std::function` instead, including: * The callback of any task. * Any server's process. This conforms to the `FaaS` (Function as a Service) idea. * The realization of an algorithm is simply a `std::function`. But the algorithm can also be implemented by derivation. + * If used deeply, one will find that everything can be derived. -Memory reclamation mechanism - -* Every task will be automatically reclaimed after the callback. If a task is created but a user does not want to run it, the user needs to release it through the dismiss method. -* Any data in the task, such as the response of the network request, will also be recycled with the task. At this time, the user can use `std::move()` to move the required data. -* SeriesWork and ParallelWork are two kinds of framework objects, which are also recycled after their callback. - * When a series is a branch of a parallel, it will be recycled after the callback of the parallel that it belongs to. -* This project doesn’t use `std::shared_ptr` to manage memory. - -#### Any other questions? +#### Any Other Questions? You may check the [FAQ](https://github.com/sogou/workflow/issues/406) and [issues](https://github.com/sogou/workflow/issues) list first to see if you can find the answer.