cuprate_txpool/service.rs
1//! [`tower::Service`] integration + thread-pool.
2//!
3//! ## `service`
4//! The `service` module implements the [`tower`] integration,
5//! along with the reader/writer thread-pool system.
6//!
7//! The thread-pool allows outside crates to communicate with it by
8//! sending database [`Request`][req_r]s and receiving [`Response`][resp]s `async`hronously -
9//! without having to actually worry and handle the database themselves.
10//!
11//! The system is managed by this crate, and only requires init by the user.
12//!
13//! ## Handles
14//! The 2 handles to the database are:
15//! - [`TxpoolReadHandle`]
16//! - [`TxpoolWriteHandle`]
17//!
18//! The 1st allows any caller to send [`ReadRequest`][req_r]s.
19//!
20//! The 2nd allows any caller to send [`WriteRequest`][req_w]s.
21//!
22//! Both the handles are cheaply [`Clone`]able.
23//!
24//! ## Initialization
25//! The database & thread-pool system can be initialized with [`init_with_pool()`].
26//!
27//! This causes the underlying database/threads to be setup
28//! and returns a read/write handle to that database.
29//!
30//! ## Shutdown
31//! Upon the above handles being dropped, the corresponding thread(s) will automatically exit, i.e:
32//! - The last [`TxpoolReadHandle`] is dropped => reader thread-pool exits
33//! - The last [`TxpoolWriteHandle`] is dropped => writer thread exits
34//!
35//! ## Request and Response
36//! To interact with the database (whether reading or writing data),
37//! a `Request` can be sent using one of the above handles.
38//!
39//! Both the handles implement [`tower::Service`], so they can be [`tower::Service::call`]ed.
40//!
41//! An `async`hronous channel will be returned from the call.
42//! This channel can be `.await`ed upon to (eventually) receive
43//! the corresponding `Response` to your `Request`.
44//!
45//! [req_r]: interface::TxpoolReadRequest
46//!
47//! [req_w]: interface::TxpoolWriteRequest
48//!
49//! // TODO: we have 2 responses
50//!
51//! [resp]: interface::TxpoolWriteResponse
52//!
53
54mod free;
55pub mod interface;
56mod read;
57mod write;
58
59pub use free::init_with_pool;
60pub use read::TxpoolReadHandle;
61pub use write::TxpoolWriteHandle;