An asynchronous, bounded-concurrency task queue for Elixir.

Tasque lets you enqueue work — anonymous functions or MFA tuples — and execute it asynchronously under a supervised Task.Supervisor, with a configurable ceiling on simultaneous tasks. Results are delivered back to the caller via plain OTP messages, so you can choose between blocking (await/2) and non-blocking (selective receive) consumption styles.

Quick Start

Add a Tasque instance to your application's supervision tree:

children = [
  {Tasque, name: MyApp.Queue, max_concurrency: 10}
]

Supervisor.start_link(children, strategy: :one_for_one)

Then enqueue work from anywhere:

{:ok, ref} = Tasque.queue_task(MyApp.Queue, fn -> expensive_work() end)

# Block until the result arrives (or timeout):
{:ok, result} = Tasque.await(ref)

Result Format

Every task result is delivered as a {:tasque_result, ref, outcome} message to the process that called queue_task/3. The outcome is one of:

When using await/2, the outcome tuple is returned directly.

Task Formats

Tasks can be provided as either a zero-arity anonymous function or an MFA tuple. MFA tuples are normalized internally to fn -> apply(m, f, a) end.

# Anonymous function
Tasque.queue_task(queue, fn -> String.upcase("hello") end)

# MFA tuple
Tasque.queue_task(queue, {String, :upcase, ["hello"]})

Supervision Architecture

Each Tasque instance starts a small supervision subtree:

Tasque.Supervisor (:one_for_all)
├── Task.Supervisor   — runs tasks via async_nolink
└── Tasque.Queue      — GenServer managing the FIFO queue

The :one_for_all strategy ensures that if either child crashes, both are restarted together, keeping the system in a consistent state. The Task.Supervisor starts first so its name is available to Tasque.Queue at init time.

Concurrency Control

When the number of in-flight tasks is below :max_concurrency, enqueued work is dispatched immediately. Once the limit is reached, tasks wait in a FIFO queue and are dispatched as running tasks complete, crash, or time out — each of these events frees a concurrency slot.

Fault Isolation

Tasks run under Task.Supervisor.async_nolink/2, so a crashing task:

• Does not crash the queue GenServer
• Does not affect other concurrently running tasks
• Produces an {:exit, reason} result delivered to the original caller
• Frees its concurrency slot, allowing the next queued task to dispatch

Per-Task Timeouts

You can set a timeout on individual tasks at enqueue time:

Tasque.queue_task(queue, fn -> slow_work() end, timeout: 5_000)

The timeout starts when the task is enqueued, so it includes time spent waiting in the queue as well as time spent running.

If the timeout fires while the task is still queued, the queue tombstones it, delivers {:exit, :timeout} to the caller, and skips it during dispatch.

If the timeout fires while the task is already running:

1. The task process is killed (Task.Supervisor.terminate_child/2)
2. {:exit, :timeout} is delivered to the caller
3. The concurrency slot is freed

Pass timeout: :infinity to disable the per-task timeout. Otherwise, :timeout must be a positive integer in milliseconds. If no :timeout option is given, the task runs without a timeout.

Multiple Queues

You can run independent queues with different concurrency limits for different workload categories:

children = [
  {Tasque, name: MyApp.CpuQueue, max_concurrency: System.schedulers_online()},
  {Tasque, name: MyApp.IoQueue,  max_concurrency: 50}
]

Each queue maintains its own task supervisor, dispatch loop, and concurrency budget.

Caller Refs

The reference returned by queue_task/3 is a caller ref — a make_ref() created by the queue GenServer and decoupled from the internal Task ref used by the task supervisor. This means:

• The caller never holds a direct reference to the underlying task process
• Refs are unique per enqueue call, even if the same function is submitted twice
• The queue maintains the mapping from internal task refs to caller refs

Edge Cases

• Caller dies before task completes — the result message is sent to a dead PID and silently dropped. The task still runs to completion (or timeout) and the concurrency slot is freed normally.

• Await times out — await/2 returns {:error, :timeout} but the task keeps running. The {:tasque_result, ref, outcome} message will eventually arrive in the caller's mailbox. You can call await/2 again with the same ref to retrieve it, or use a selective receive.