Expand description
§rs-singleflight
rs-singleflight coalesces concurrent asynchronous work by key. When several
callers request the same key at the same time, one caller runs the operation
and the others receive the same result.
The crate also provides an optional success-only TTL cache with generation-safe invalidation.
§Installation
[dependencies]
rs-singleflight = "0.2"The crate requires Rust 1.85 or newer.
§Basic usage
use rs_singleflight::Group;
#[tokio::main]
async fn main() -> Result<(), String> {
let group = Group::<String, usize, String>::new();
let value = group
.do_call("answer".to_owned(), || async {
// Perform the expensive request here.
Ok(42)
})
.await?;
assert_eq!(value, 42);
Ok(())
}Group is cheap to clone. Its clones share the same in-flight registry, which
makes it convenient to move into spawned tasks.
§Results that are not Clone
Use do_call_shared when the value or error cannot be cloned. It returns the
same API shape as CachedGroup::get_shared:
use std::sync::Arc;
use rs_singleflight::{Group, SharedResult};
struct Payload(Vec<u8>);
let group = Group::<&str, Payload, String>::new();
let result: SharedResult<Payload, String> = group
.do_call_shared("asset", || async { Ok(Payload(vec![1, 2, 3])) })
.await;
let payload: Arc<Payload> = result.unwrap();
assert_eq!(payload.0, vec![1, 2, 3]);§Leader cancellation and panics
By default, if the leader future is dropped, a waiting caller retries the acquisition and may execute its own operation. This keeps waiters from hanging, but means an operation that performed a side effect before cancellation can be executed more than once.
For non-idempotent operations, select LeaderDropPolicy::ReturnError:
use rs_singleflight::{CallError, Group, LeaderDropPolicy};
let group = Group::<&str, usize, String>::new();
let result = group
.do_call_with_policy("charge", LeaderDropPolicy::ReturnError, || async {
Ok(1)
})
.await;
match result {
Ok(value) => assert_eq!(value, 1),
Err(CallError::Operation(error)) => eprintln!("operation failed: {error}"),
Err(CallError::LeaderDropped) => eprintln!("leader was cancelled or panicked"),
}Operations supplied for the same key should be semantically equivalent. Which caller’s closure becomes the leader depends on scheduling.
§TTL cache
CachedGroup caches successful values from the time the operation completes.
Errors are coalesced but are never cached.
use std::time::Duration;
use rs_singleflight::CachedGroup;
let cache = CachedGroup::<String, String, String>::new(Duration::from_secs(30));
let value = cache
.get("user:42".to_owned(), || async { Ok("Ada".to_owned()) })
.await
.unwrap();
assert_eq!(value, "Ada");
assert!(cache.invalidate("user:42"));invalidate and clear are generation barriers:
- callers already waiting on an old flight still receive its result;
- calls started after invalidation never join that old flight;
- an invalidated flight cannot repopulate the cache.
Expired values are replaced on demand. For unbounded key spaces, call
purge_expired periodically. Generation metadata created by per-key
invalidation is retained until clear so old generations can never become
current again.
§API overview
Group::do_call: clonedResult<V, E>values for convenient everyday use.Group::do_call_shared:Result<Arc<V>, Arc<E>>withoutClonebounds.Group::forget: detach an active flight so later callers start a new one.CachedGroup: coalescing plus a success-only TTL cache.*_with_policy: explicit behavior when a leader future is dropped.
No internal lock is held across an .await, and operations for different keys
can run independently.
§Migrating from 0.1
Version 0.2 intentionally replaces the original operation-owning API with a smaller per-call API:
| 0.1 | 0.2 |
|---|---|
Group::new(operation) | Group::new() |
group.run(key) | group.do_call(key, operation) |
Arc<Outcome<T, E>> | Result<T, E> or SharedResult<T, E> |
Outcome::Canceled | CallError::LeaderDropped with ReturnError policy |
group.forget(key) | retained, now returns whether a live flight was detached |
The low-level Entry, Leader, and Subscriber API is no longer public.
Use do_call_with_policy when cancellation must be observable rather than
automatically retried.
§License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Structs§
- Cached
Group - A
Grouplayered with a success-only, in-memory TTL cache. - Group
- Coalesces concurrent asynchronous operations by key.
Enums§
- Call
Error - Error returned by policy-aware calls.
- Leader
Drop Policy - Controls what a waiting caller does when the leader future is dropped.
Type Aliases§
- Shared
Result - A result whose value and error can be shared without implementing
Clone.