From 14f29f963540cd534a5c6fd71fde7ba6749850d4 Mon Sep 17 00:00:00 2001 From: "hinto.janai" Date: Wed, 4 Sep 2024 17:05:00 -0400 Subject: [PATCH] service/resize --- .../storage/common/service/initialization.md | 10 +++++++++- .../src/storage/common/service/requests.md | 9 ++++++++- .../src/storage/common/service/resizing.md | 17 ++++++++++------- .../src/storage/common/service/responses.md | 19 ++++++++++++++++++- 4 files changed, 45 insertions(+), 10 deletions(-) diff --git a/books/architecture/src/storage/common/service/initialization.md b/books/architecture/src/storage/common/service/initialization.md index 59f994c..1a21788 100644 --- a/books/architecture/src/storage/common/service/initialization.md +++ b/books/architecture/src/storage/common/service/initialization.md @@ -1 +1,9 @@ -# 🟢 Initialization +# Initialization +A database service is started simply by calling: [`init()`](https://doc.cuprate.org/cuprate_blockchain/service/fn.init.html). + +This function initializes the database, spawns threads, and returns a: +- Read handle to the database (cloneable) +- Write handle to the database (not cloneable) +- The database itself + +These handles implement the `tower::Service` trait, which allows sending requests and receiving responses `async`hronously. \ No newline at end of file diff --git a/books/architecture/src/storage/common/service/requests.md b/books/architecture/src/storage/common/service/requests.md index 7391375..99716c1 100644 --- a/books/architecture/src/storage/common/service/requests.md +++ b/books/architecture/src/storage/common/service/requests.md @@ -1 +1,8 @@ -# 🟢 Requests +# Requests +Along with the 2 handles, there are 2 types of requests: +- Read requests, e.g. [`BlockchainReadRequest`](https://doc.cuprate.org/cuprate_types/blockchain/enum.BlockchainReadRequest.html) +- Write requests, e.g. [`BlockchainWriteRequest`](https://doc.cuprate.org/cuprate_types/blockchain/enum.BlockchainWriteRequest.html) + +Quite obviously: +- Read requests are for retrieving various data from the database +- Write requests are for writing data to the databases \ No newline at end of file diff --git a/books/architecture/src/storage/common/service/resizing.md b/books/architecture/src/storage/common/service/resizing.md index 214b1fb..1b91499 100644 --- a/books/architecture/src/storage/common/service/resizing.md +++ b/books/architecture/src/storage/common/service/resizing.md @@ -1,12 +1,15 @@ # Resizing -Database backends that require manually resizing will, by default, use a similar algorithm as `monerod`'s. +As noted in the [`cuprate_database` resizing section](../../db/resizing.md), +builders on-top of `cuprate_database` are responsible for resizing the database. -Note that this only relates to the [`Service`](../common/service/intro.md) section, where the database is handled by `cuprate_database_service` itself, not the user. In the case of a user directly using `cuprate_database`, it is up to them on how to resize. The database will return [`RuntimeError::ResizeNeeded`](https://doc.cuprate.org/cuprate_database/enum.RuntimeError.html#variant.ResizeNeeded) when it needs resizing. +In `cuprate_{blockchain,txpool}`'s case, that means the `tower::Service` must know +how to resize. This logic is shared between both crates, defined in `cuprate_database_service`: +. -Within `service`, the resizing logic defined [here](https://github.com/Cuprate/cuprate/blob/2ac90420c658663564a71b7ecb52d74f3c2c9d0f/database/src/service/write.rs#L139-L201) does the following: +By default, this uses a _similar_ algorithm as `monerod`'s: -- If there's not enough space to fit a write request's data, start a resize -- Each resize adds around [`1_073_745_920`](https://github.com/Cuprate/cuprate/blob/2ac90420c658663564a71b7ecb52d74f3c2c9d0f/database/src/resize.rs#L104-L160) bytes to the current map size -- A resize will be attempted `3` times before failing +- [If there's not enough space to fit a write request's data](https://github.com/Cuprate/cuprate/blob/0941f68efcd7dfe66124ad0c1934277f47da9090/storage/service/src/service/write.rs#L130), start a resize +- Each resize adds around [`1,073,745,920`](https://github.com/Cuprate/cuprate/blob/2ac90420c658663564a71b7ecb52d74f3c2c9d0f/database/src/resize.rs#L104-L160) bytes to the current map size +- A resize will be [attempted `3` times](https://github.com/Cuprate/cuprate/blob/0941f68efcd7dfe66124ad0c1934277f47da9090/storage/service/src/service/write.rs#L110) before failing -There are other [resizing algorithms](https://github.com/Cuprate/cuprate/blob/2ac90420c658663564a71b7ecb52d74f3c2c9d0f/database/src/resize.rs#L38-L47) that define how the database's memory map grows, although currently the behavior of [`monerod`](https://github.com/Cuprate/cuprate/blob/2ac90420c658663564a71b7ecb52d74f3c2c9d0f/database/src/resize.rs#L104-L160) is closely followed. \ No newline at end of file +There are other [resizing algorithms](https://doc.cuprate.org/cuprate_database/resize/enum.ResizeAlgorithm.html) that define how the database's memory map grows, although currently the behavior of `monerod` is closely followed for no particular reason. \ No newline at end of file diff --git a/books/architecture/src/storage/common/service/responses.md b/books/architecture/src/storage/common/service/responses.md index 3ba68e0..c03b42f 100644 --- a/books/architecture/src/storage/common/service/responses.md +++ b/books/architecture/src/storage/common/service/responses.md @@ -1 +1,18 @@ -# 🟢 Responses +# Responses +After sending a request using the read/write handle, the value returned is _not_ the response, yet an `async`hronous channel that will eventually return the response: +```rust,ignore +// Send a request. +// tower::Service::call() +// V +let response_channel: Channel = read_handle.call(BlockchainReadRequest::ChainHeight)?; + +// Await the response. +let response: BlockchainReadRequest = response_channel.await?; +``` + +After `await`ing the returned channel, a `Response` will eventually be returned when +the `Service` threadpool has fetched the value from the database and sent it off. + +Both read/write requests variants match in name with `Response` variants, i.e. +- `BlockchainReadRequest::ChainHeight` leads to `BlockchainResponse::ChainHeight` +- `BlockchainWriteRequest::WriteBlock` leads to `BlockchainResponse::WriteBlockOk`