timed_locks/
lib.rs

1//! `timed-locks` is a set of smart pointers to `tokio::sync` locks that can be
2//! used as drop-in replacement and will either panic or return an error after a
3//! given timeout when the lock cannot be acquired. Default timeout is 30
4//! seconds.
5//!
6//! # Motivation
7//!
8//! In smaller codebases it's fairly trivial to prevent deadlocks by making sure
9//! that you simply don't introduce any. As the codebase gets more complex
10//! however, it gets more complex to cover all branches with automated or manual
11//! testing and so the chances to unintentionally introduce deadlocks get
12//! higher. In case a potential deadlock is introduced and makes it way into
13//! production, it might not happen directly but only after a while when a
14//! specific scenario in the codebase happens. In such cases it's often wanted
15//! that a service can recover. While you can monitor services for
16//! responsiveness from the outside and restart them if required, doing that
17//! is offloading the responsbility to a thirdparty. So in order to have a
18//! backup plan inside the service itself, it can be useful to have failsafe
19//! mechanism in place that makes it possible to have the service itself recover
20//! from a deadlock.
21//!
22//! The default behavior of panicking was chosen since just returning an error
23//! might not help break the deadlock in a service in case the bug is
24//! selfenforcing. So to have higher chances of recovering the process or task
25//! should be shutdown completely by just panicking. However, if you are certain
26//! that in your specific scenario returning errors can lead to gracefully
27//! handling a deadlock there are the `read_err` / `write_err` methods that
28//! return an error instead of panicking.
29//!
30//! # Examples
31//!
32//! Deadlock that panics after 30 seconds:
33//!
34//! ```
35//! # async {
36//! let lock = timed_locks::RwLock::new(std::collections::HashSet::<usize>::new());
37//! let _lock = lock.read().await;
38//! lock.write().await;
39//! # };
40//! ```
41//!
42//! Deadlock that returns an error after 30 seconds:
43//!
44//! ```
45//! # async {
46//! let lock = timed_locks::RwLock::new(std::collections::HashSet::<usize>::new());
47//! let _lock = lock.read().await;
48//! lock.write_err().await.unwrap();
49//! # };
50//! ```
51
52#![deny(trivial_casts, trivial_numeric_casts, unused_extern_crates, unused_qualifications)]
53#![warn(
54	missing_debug_implementations,
55	missing_docs,
56	unused_import_braces,
57	dead_code,
58	clippy::unwrap_used,
59	clippy::expect_used,
60	clippy::missing_docs_in_private_items,
61	clippy::missing_panics_doc
62)]
63
64mod mutex;
65mod rwlock;
66
67use std::time::Duration;
68
69pub use mutex::Mutex;
70pub use rwlock::RwLock;
71
72/// Duration constant of 30 seconds for the default timeout.
73pub const DEFAULT_TIMEOUT_DURATION: Duration = Duration::from_secs(30);
74
75/// Custom result.
76pub type Result<T> = std::result::Result<T, Error>;
77
78/// Timed locks errors.
79#[derive(Debug, thiserror::Error)]
80pub enum Error {
81	/// Mutex lock timeout error.
82	#[error("Timed out while waiting for `lock` after {0} seconds.")]
83	LockTimeout(u64),
84
85	/// RwLock::read lock timeout error.
86	#[error("Timed out while waiting for `read` lock after {0} seconds.")]
87	ReadLockTimeout(u64),
88
89	/// RwLock::write lock timeout error.
90	#[error("Timed out while waiting for `write` lock after {0} seconds.")]
91	WriteLockTimeout(u64),
92
93	/// `tokio::sync::TryLockError` error.
94	#[error(transparent)]
95	TokioSyncTryLock(#[from] tokio::sync::TryLockError),
96}
timed_locks/lib.rs

timed_locks/
lib.rs
