tonic_server_dispatch/lib.rs
1//! A typical architecture of network service is that after receiving a
2//! request, the network tasks dispatch it to the business tasks according
3//! to some fields. In this way, requests for the same content can be
4//! dispatched in the same task to avoid shared state or locking.
5//! This [tokio tutorial] gives detailed description.
6//!
7//! The same is true in `tonic`'s gRPC server. The dispatch of requests
8//! from network tasks to the business task has a pattern. This crate is
9//! an abstraction of this pattern to simplify the repetitive work in
10//! the application.
11//!
12//!
13//! # Examples
14//!
15//! This library is a bit difficult to get started with.
16//! See the DictService service examples in [async mode] or [sync mode],
17//! before the API documentation.
18//!
19//!
20//! # Async vs Sync
21//!
22//! The business jobs can run in async or sync mode.
23//!
24//! The [tokio tutorial] talks about the async mode. The business jobs run
25//! as tokio-tasks above the tokio runtime:
26//!
27//! network +--+ +--+ +--+ channels +--+ +--+ +--+ business
28//! tasks | | | | | | <----------> | | | | | | tasks*
29//! +--+ +--+ +--+ +--+ +--+ +--+
30//! tokio +----------------------------------------+
31//! runtime | |
32//! +----------------------------------------+
33//! +---+ +---+ +---+
34//! threads | | | | ... | |
35//! +---+ +---+ +---+
36//!
37//! If your business jobs contains no async code, then they can also
38//! run as native threads:
39//!
40//! network +--+ +--+ +--+ +---+ +---+ +---+ business
41//! tasks | | | | | | | | | | | | threads*
42//! +--+ +--+ +--+ | | | | | |
43//! tokio +------------+ channels | | | | | |
44//! runtime | | <----------> | | | | | |
45//! +------------+ | | | | | |
46//! +---+ +---+ | | | | | |
47//! threads | |... | | | | | | | |
48//! +---+ +---+ +---+ +---+ +---+
49//!
50//! This crate supports both modes.
51//!
52//! [tokio tutorial]: https://tokio.rs/tokio/tutorial/channels
53//! [async mode]: https://github.com/WuBingzheng/tonic-server-dispatch/blob/master/examples/src/server_async.rs
54//! [sync mode]: https://github.com/WuBingzheng/tonic-server-dispatch/blob/master/examples/src/server_sync.rs
55
56
57mod sync;
58mod r#async;
59
60mod common;