Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: document custom Sleeper impl #147

Merged
merged 6 commits into from
Sep 5, 2024
Merged

docs: document custom Sleeper impl #147

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c43737f
docs: document custom Sleeper impl
SteveLauC Sep 4, 2024
0cfae4b
docs: ignore the example
SteveLauC Sep 4, 2024
5db9a15
style: fmt
SteveLauC Sep 4, 2024
9b08faa
docs: address feedback
SteveLauC Sep 5, 2024
ef1c0fa
docs: add MonoioSleeper to docs/examples
SteveLauC Sep 5, 2024
fc88e36
docs: remove backticks around Sleeper
SteveLauC Sep 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
docs: document custom Sleeper impl
  • Loading branch information
@SteveLauC
SteveLauC committed Sep 4, 2024
commit c43737fb4bdc74453e4dcdcec32af1ef054b169f
44 changes: 36 additions & 8 deletions backon/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,15 +32,43 @@
//! # Sleep
//!
//! Retry in BackON requires an implementation for sleeping. BackON will accept a [`Sleeper`] to pause for a specified duration.
//!
//! ## Default `Sleeper`
//!
//! Currently, BackON has 2 built-in `Sleeper` implementations for different environments,
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be 3, we have std-blocking-sleep for blocking context.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added the BlockingSleeper to the table.

//! they are gated under their own features, which are enabled by default:
//!
//! | `Sleeper` | feature | Environment |
//! |---------------------|------------------|-------------|
//! | [`TokioSleeper`] | tokio-sleep | non-wasm32 |
//! | [`GlooTimersSleep`] | gloo-timers-sleep| wasm32 |
//!
//! ## Custom `Sleeper`
//!
//! If you do not want to use the built-in `Sleeper`, you CAN provide a custom
//! implementation, here is an example that implements a `Sleeper` with `monoio::time::sleep`:
//!
//! ```rust,no_run
//! use std::time::Duration;
//! use backon::Sleeper;
//! use monoio::time::sleep;
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't want to use Monoio as an example here. Let's just implement a function that prints "Hello, World!" and then returns Ready

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

//! use monoio::time::Sleep;
//!
//! /// Sleeper implemented using `monoio::time::sleep()`.
//! struct MonoioSleeper;
//!
//! impl Sleeper for MonoioSleeper {
//! type Sleep = Sleep;
//!
//! fn sleep(&self, dur: Duration) -> Self::Sleep {
//! sleep(dur)
//! }
//! }
//! ```
//!
//! ## The empty `Sleeper`
//!
//! BackON employs the following default sleep implementations:
//!
//! - `tokio-sleep`: Utilizes [`TokioSleeper`] within a Tokio context in non-wasm32 environments.
//! - `gloo-timers-sleep`: Utilizes [`GlooTimersSleep`] to pause in wasm32 environments.
//!
//! Users CAN provide a custom implementation if they prefer not to use the default options.
//!
//! If neither feature is enabled nor a custom implementation is provided, BackON will fallback to an empty sleeper. This will cause a panic in the `debug` profile and do nothing in the `release` profile.
//! If neither feature is enabled nor a custom implementation is provided, BackON will fallback to the empty sleeper. This will cause a panic in the `debug` profile and do nothing in the `release` profile.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is out-of-date now. We will raise a build error now.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated

//!
//! # Retry
//!
Expand Down