Skip to main content

Crate rs_singleflight

Crate rs_singleflight 

Source
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: cloned Result<V, E> values for convenient everyday use.
  • Group::do_call_shared: Result<Arc<V>, Arc<E>> without Clone bounds.
  • 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.10.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::CanceledCallError::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§

CachedGroup
A Group layered with a success-only, in-memory TTL cache.
Group
Coalesces concurrent asynchronous operations by key.

Enums§

CallError
Error returned by policy-aware calls.
LeaderDropPolicy
Controls what a waiting caller does when the leader future is dropped.

Type Aliases§

SharedResult
A result whose value and error can be shared without implementing Clone.