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 3 commits
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
38 changes: 33 additions & 5 deletions backon/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,14 +33,42 @@
//!
//! Retry in BackON requires an implementation for sleeping. BackON will accept a [`Sleeper`] to pause for a specified duration.
//!
//! BackON employs the following default sleep implementations:
//! ## Default `Sleeper`
//!
//! - `tokio-sleep`: Utilizes [`TokioSleeper`] within a Tokio context in non-wasm32 environments.
//! - `gloo-timers-sleep`: Utilizes [`GlooTimersSleep`] to pause in wasm32 environments.
//! 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:
//!
//! Users CAN provide a custom implementation if they prefer not to use the default options.
//! | `Sleeper` | feature | Environment |
//! |---------------------|------------------|-------------|
//! | [`TokioSleeper`] | tokio-sleep | non-wasm32 |
//! | [`GlooTimersSleep`] | gloo-timers-sleep| wasm32 |
//!
//! 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.
//! ## 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,ignore
SteveLauC marked this conversation as resolved.
Show resolved Hide resolved
//! 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`
//!
//! 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