﻿Sometimes a task is started while its last run is still going: a slow run meets
the next cron time, or someone clicks **Run** twice.
[`on_overlap`](/configuration/tasks/#on_overlap) decides what happens.

```toml title="runwisp.toml"
[tasks.health-probe]
cron       = "* * * * *"
on_overlap = "skip"   # default is "queue"
run        = "curl -sf https://example.com/health"
```

By default a task runs one copy at a time
([`max_concurrent`](/configuration/tasks/#max_concurrent) is `1`). While there is
a free slot, a new run starts at once. `on_overlap` only matters when all slots are
taken.

## Choosing a policy

### queue

The default. The new run waits and starts when the running one finishes. Runs
start in the order they arrived, whether they came from cron, the CLI, the Web
UI, or the API.

```toml title="runwisp.toml"
[tasks.process-uploads]
cron = "*/5 * * * *"
run  = "/usr/local/bin/process"
```

Use it when every run has to happen eventually, for example when each run
handles its own batch of work.

The queue has a limit, [`max_queued`](/configuration/tasks/#max_queued). When
it's full, the new run is recorded as `queue_full` and dropped. If you see
`queue_full` runs, the task can't keep up: run it less often, raise
[`max_concurrent`](/configuration/tasks/#max_concurrent), or switch to `skip`.

### skip

The new run is dropped and recorded as `skipped` (exit code `-1`). The running
one carries on.

```toml title="runwisp.toml"
[tasks.pg-dump]
cron       = "0 * * * *"
on_overlap = "skip"
run        = "pg_dump app > /backups/app.sql"
```

Use it when a missed run doesn't matter (a probe, a poll) or when two copies at
once would do harm (two dumps writing the same file).

By default a skipped run is not a failure, so it doesn't send notifications and
doesn't count toward the failure rate ([`failures`](/configuration/tasks/#failures)
can add `skipped` to change that). It is never retried, whatever `failures`
says. It still shows up in the history under its own status, so a task that
keeps overlapping stands out.

A manual start that gets skipped tells you so: the CLI, Web UI, and API report
that the run was skipped.

### kill

RunWisp stops the oldest running run and starts the new one right away. The
stopped run gets [`stop_signal`](/configuration/tasks/#stop_signal) and
[`graceful_stop`](/configuration/tasks/#graceful_stop) to exit, and is recorded
as `stopped`, the same as a manual stop. A stopped run is never retried.

```toml title="runwisp.toml"
[tasks.rebuild-index]
on_overlap = "kill"
run        = "/usr/local/bin/rebuild-index"
```

Use it when only the newest run matters: a rebuild or a deploy that the next
request makes out of date.

## Running several at once

Raise [`max_concurrent`](/configuration/tasks/#max_concurrent) to let several
runs of the same task go at once. [`on_overlap`](/configuration/tasks/#on_overlap) applies only once all of them are
busy.

```toml title="runwisp.toml"
[tasks.thumbnail-render]
cron           = "* * * * *"
max_concurrent = 4
run            = "/usr/local/bin/render"
```

Here up to four renders run at the same time and a fifth waits in the queue.
With `on_overlap = "skip"`, the fifth is dropped instead.

Only raise it when the runs don't share state or fight over one resource. It
fits a task that usually finishes in seconds but sometimes takes much longer.

For a pool of long-running workers, use a service with
[`instances`](/configuration/services/#instances) instead. Services have no
`on_overlap`; see [Tasks and services](/concepts/tasks-vs-services/).
