add more documentation about "channel_cap" (#19)

* add more documentation about "channel_cap"

* cache cargo-rdme

* failure

* use git release instead of cargo search

* change name of step

.github/workflows/readme.yml

@@ -11,6 +11,9 @@ on:
     paths:
       - 'src/lib.rs'
       - 'README.md'
+env:
+  CACHE_PREFIX: v0
+
 jobs:
   readme:
     name: README
@@ -26,11 +29,31 @@ jobs:
           profile: minimal
           override: true
 
+      - name: Find latest cargo-rdme version
+        shell: bash
+        run: |
+          set -e
+          set -u
+          set -o pipefail
+          CARGO_RDME_VERSION=$(curl -s https://api.github.com/repos/orium/cargo-rdme/releases/latest | jq -r '.tag_name')
+          # Alternate method using cargo (takes longer):
+          # CARGO_RDME_VERSION=$(cargo search --limit 1 cargo-rdme | grep cargo-rdme | head -n 1 | sed -E 's/cargo-rdme = "([^"]+)".*/v\1/g')
+          echo "CARGO_RDME_VERSION=$CARGO_RDME_VERSION" >> $GITHUB_ENV
+          echo "$CARGO_RDME_VERSION"
+
+      - name: Cache cargo-rdme
+        uses: actions/cache@v2
+        id: cache-cargo-rdme
+        with:
+          path: ~/.cargo/bin/cargo-rdme
+          key: ${{ env.CACHE_PREFIX }}-${{ env.CARGO_RDME_VERSION }}
+
       - name: Install cargo-rdme
+        if: steps.cache-cargo-rdme.outputs.cache-hit != 'true'
         run: |
           cargo install cargo-rdme
 
-      - name: Run cargo-rdme
+      - name: Check README is up-to-date
         run: |
           # If this step fails it means you haven't ran 'make readme' to update the README.
           cargo rdme --check

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+
+- Added more documentation about `channel_cap`.
+
 ## [v0.2.3](https://github.com/epwalsh/batched-fn/releases/tag/v0.2.3) - 2022-03-11
 
 ### Changed

README.md

@@ -42,7 +42,9 @@ macro into the function that runs requests through the model.
 - 🚀 Easy to use: drop the `batched_fn!` macro into existing code.
 - 🔥 Lightweight and fast: queue system implemented on top of the blazingly fast [flume crate](https://github.com/zesterer/flume).
 - 🙌 Easy to tune: simply adjust [`max_delay`](https://docs.rs/batched-fn/latest/batched_fn/macro.batched_fn.html#config) and [`max_batch_size`](https://docs.rs/batched-fn/latest/batched_fn/macro.batched_fn.html#config).
-- 🛑 [Back pressure](https://medium.com/@jayphelps/backpressure-explained-the-flow-of-data-through-software-2350b3e77ce7) mechanism included: just set [`channel_cap`](https://docs.rs/batched-fn/latest/batched_fn/macro.batched_fn.html#config).
+- 🛑 [Back pressure](https://medium.com/@jayphelps/backpressure-explained-the-flow-of-data-through-software-2350b3e77ce7) mechanism included:
+  just set [`channel_cap`](https://docs.rs/batched-fn/latest/batched_fn/macro.batched_fn.html#config) and handle
+  [`Error::Full`](https://docs.rs/batched-fn/latest/batched_fn/enum.Error.html#variant.Full) by returning a 503 from your webserver.
 
 ## Examples
 

src/lib.rs

@@ -12,7 +12,9 @@
 //! - 🚀 Easy to use: drop the `batched_fn!` macro into existing code.
 //! - 🔥 Lightweight and fast: queue system implemented on top of the blazingly fast [flume crate](https://github.com/zesterer/flume).
 //! - 🙌 Easy to tune: simply adjust [`max_delay`](crate::batched_fn#config) and [`max_batch_size`](crate::batched_fn#config).
-//! - 🛑 [Back pressure](https://medium.com/@jayphelps/backpressure-explained-the-flow-of-data-through-software-2350b3e77ce7) mechanism included: just set [`channel_cap`](crate::batched_fn#config).
+//! - 🛑 [Back pressure](https://medium.com/@jayphelps/backpressure-explained-the-flow-of-data-through-software-2350b3e77ce7) mechanism included:
+//!   just set [`channel_cap`](crate::batched_fn#config) and handle
+//!   [`Error::Full`](crate::Error#variant.Full) by returning a 503 from your webserver.
 //!
 //! ## Examples
 //!
@@ -206,6 +208,10 @@ impl Default for Config {
 #[derive(Debug, Copy, Clone)]
 pub enum Error {
     /// Channel is full.
+    ///
+    /// This can happen if you've set `channel_cap`, and should usually be handled
+    /// by returning a 503 error code from your server to signal that the server is too
+    /// busy at the moment to handle any more requests.
     Full,
 
     /// Channel has been disconnected, most likely due to the handler thread crashing.
@@ -383,8 +389,8 @@ macro_rules! __batched_fn_internal {
 /// the handler thread to accept another batch. By default `channel_cap` is `None`, but if
 /// set to `Some(usize)` then
 /// [`BatchedFn::evaluate_in_batch`](struct.BatchedFn.html#method.evaluate_in_batch) will
-/// return an error if the channel between the calling thread and the handler thread is at this
-/// capacity.
+/// return [`Error::Full`](crate::Error#variant.Full) if the channel between the calling thread and the handler thread is at this
+/// capacity. You probably want to set this to some multiple of `max_batch_size`.
 ///
 /// ## `context`
 ///