Debouncing

Debouncing collapses repeated enqueues that share a key into a single job whose run keeps sliding into the future while the calls keep coming. It is the answer to "rebuild this user's report once they stop editing", not "run this at most 100 times a minute" — see Flow control for how it differs from throttling and from idempotent coalescing.

@queue.task(
    debounce="5m",                    # slide the run 5 minutes out on every enqueue
    debounce_key="report:{user_id}",  # one window per user
    debounce_max_wait="30m",          # but never delay past 30 minutes
)
def build_report(user_id: str) -> None: ...

first = build_report.delay("u1")      # creates the job
again = build_report.delay("u1")      # same job id — deadline moves

queue.task("buildReport", buildReport, {
  debounce: "5m", // slide the run 5 minutes out on every enqueue
  debounceKey: "report:{userId}", // one window per user
  debounceMaxWait: "30m", // but never delay past 30 minutes
});

queue.enqueue("buildReport", [{ userId: "u1" }]); // creates the job
queue.enqueue("buildReport", [{ userId: "u1" }]); // same job id — deadline moves

record Report(String userId, int revision) {}

Task<Report> BUILD_REPORT = Task.of("build-report", Report.class)
        .debounce(
                Duration.ofMinutes(5),    // slide the run 5 minutes out on every enqueue
                "report:{userId}",        // one window per user
                Duration.ofMinutes(30));  // but never delay past 30 minutes

String first = flexiq.enqueue(BUILD_REPORT, new Report("u1", 1));  // creates the job
String again = flexiq.enqueue(BUILD_REPORT, new Report("u1", 2));  // same id — deadline moves

The first enqueue creates the job; every later one with the same resolved key returns that job's id, so a burst of a hundred calls leaves one pending row. The deadline is min(now + window, first_seen + max_wait), recomputed inside the same storage operation that finds the open window — two producers racing on one key cannot both create a job.

A job that has already been claimed is never pulled backwards. If a worker picked the job up a microsecond ago, the enqueue leaves it alone and inserts a fresh one instead: the run in flight finishes with the payload it started with, and the new window opens behind it.

Durations

The key is the window

The key is a template resolved against the arguments of each individual call — never at registration, since that is where the arguments do not exist yet.

@queue.task(debounce="10s", debounce_key="sync:{0}", debounce_max_wait="2m")
def sync_user(user_id: str) -> None: ...

queue.task("syncUser", syncUser, {
  debounce: "10s",
  debounceKey: "sync:{0}", // syncUser(userId: string)
  debounceMaxWait: "2m",
});

Task<Report> SYNC_USER = Task.of("sync-user", Report.class)
        .debounce(Duration.ofSeconds(10), "sync:{userId}", Duration.ofMinutes(2));

A placeholder that resolves to nothing — a missing name, an out-of-range position, an object where a scalar was expected —

at enqueue, and nothing is inserted. The alternative would be one global window silently shared by every caller, which is the failure debouncing exists to avoid. A template with no placeholder at all is legal and means exactly that: one window for the whole task.

Max wait is mandatory

A window with no max wait is refused when the task is registeredwhen the task is registeredat build() time, before any job exists. Without a ceiling, a caller who never stops enqueuing starves the job forever — the classic debounce footgun. The ceiling is measured from when the window opened, not from the latest call, so the job runs on schedule no matter how long the burst lasts. It may never be shorter than the window itself, which would cap the very first insert and make the window meaningless.

Which payload runs

By default the job runs with the arguments the window opened with; later enqueues move the deadline and nothing else. Turn on payload replacement to run with the newest arguments instead:

@queue.task(
    debounce="5m",
    debounce_key="report:{user_id}",
    debounce_max_wait="30m",
    debounce_replace_payload=True,
)
def build_report(user_id: str, revision: int) -> None: ...

queue.task("buildReport", buildReport, {
  debounce: "5m",
  debounceKey: "report:{userId}",
  debounceMaxWait: "30m",
  debounceReplacePayload: true,
});

Task<Report> BUILD_REPORT = Task.of("build-report", Report.class)
        .debounce(Duration.ofMinutes(5), "report:{userId}", Duration.ofMinutes(30), true);

Priority, metadata, notes, dependencies and expiry always belong to the job that opened the window — only the deadline and, optionally, the payload move. A coalescing call is a vote to run again soon, not a redefinition of the run.

Per-enqueue debouncing

The same knobs work on a single submission, so a producer that registers no handler can still debounce, and one call can override the task's defaults:

build_report.apply_async(
    args=("u1",),
    debounce="30s",
    debounce_key="report:{user_id}",
    debounce_max_wait="5m",
)

# Or from a producer process that never imported the task function:
queue.enqueue(
    "build_report",
    args=("u1",),
    debounce="30s",
    debounce_key="report:{0}",
    debounce_max_wait="5m",
)

queue.enqueue("buildReport", [{ userId: "u1" }], {
  debounce: "30s",
  debounceKey: "report:{userId}",
  debounceMaxWait: "5m",
});

EnqueueOptions urgent = EnqueueOptions.builder()
        .debounce(Duration.ofSeconds(30))
        .debounceKey("report:{userId}")
        .debounceMaxWait(Duration.ofMinutes(5))
        .debounceReplacePayload(true)
        .build();

flexiq.enqueue(BUILD_REPORT, new Report("u1", 3), urgent);

Limits

Backends

The slide-or-insert decision, the claimed-row guard and the write are one atomic step on every backend — see Flow control for the per-backend mechanism and what Redis does under contention.