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
[]
= "0.2"
The crate requires Rust 1.85 or newer.
Basic usage
use Group;
async
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 Arc;
use ;
;
# async
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 ;
# async
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 Duration;
use CachedGroup;
# async
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.