service/resize

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.

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

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`:
+<https://github.com/Cuprate/cuprate/blob/0941f68efcd7dfe66124ad0c1934277f47da9090/storage/service/src/service/write.rs#L107-L171>.
 
-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
+- [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
+- 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
+- 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.
+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.

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`