feature: Add BackgroundTask — cross-platform cancellable, progress-pollable worker (#552)

[xerial]

Closes #552.

Why

wvlet's SqlConnector.QueryHandle (state/stats/cancel/await) is free for Trino (polls a remote server) but the DuckDB impl is a synchronous wrapper — cancel is a no-op, no progress. libduckdb exposes duckdb_query_progress / duckdb_interrupt / a pending-result API, but driving them needs the query to run on a different thread than the one polling progress / cancelling. uni had no cross-platform primitive for that. This adds one.

What

wvlet.uni.control.BackgroundTask[A, P] — run a plain side-effecting block on a background worker, no effect monad:

trait BackgroundTask[A, P]:
  def progress: Option[P]        // latest reported, non-blocking poll snapshot
  def poll: Option[Result[A]]    // terminal snapshot, non-blocking
  def await(): Result[A]         // block until done
  def cancel(): Unit             // cooperative cancel + run onCancel hooks
  def isCancelled: Boolean
  def isDone: Boolean

trait TaskContext[P]:            // handed to the body
  def isCancelled: Boolean
  def checkCancelled(): Unit     // throws TaskCancelledException
  def reportProgress(p: P): Unit
  def onCancel(hook: () => Unit): Unit   // e.g. () => duckdb_interrupt(conn)

BackgroundTask.start[A, P](body: TaskContext[P] => A): BackgroundTask[A, P]

The shared state machine (atomic flags + result + lock-coordinated cancel hooks) lives in uni/src/main; only the worker spawn + completion gate are per-platform (BackgroundTaskCompat): JVM/Native = daemon Thread + CountDownLatch; JS = inline run + no-op gate. Reuses Result, ThreadUtil.

Design decision: JS is non-concurrent (documented)

The issue assumed Node worker_threads could host the work, but they run a separate JS realm fed a pre-written JS string (see adr/2026-05-14-nodejs-sync-http.md) — an arbitrary Scala.js closure can't run on one, and Scala.js is single-threaded. So a true background worker exists only on JVM and Native (the DuckDB targets). The API is identical on all three, but on JS the body runs inline during start() (completes before it returns; no concurrency; cancel() after completion is a no-op). This was confirmed with the maintainer before implementing.

Testing

• Cross-platform (uni/src/test, JS runs inline): completion → Success, body throw → Failure, progress reported, await/poll agree.
• JVM + Native concurrency: live cancel observed via isCancelled, checkCancelled → Failure(TaskCancelledException), onCancel fires (incl. registered-after-cancel), await blocks until completion.
• JVM 9 / JS 4 / Native 9 pass.

Plan: plans/2026-06-20-background-task.md. Follow-ups noted there: Rx[P] progress stream, Thread.interrupt() on cancel, worker pooling/timeouts, and an ADR for the Node-worker_threads limitation.

🤖 Generated with Claude Code

[xerial]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces BackgroundTask, a cross-platform, cooperatively cancellable, and progress-pollable background worker with platform-specific implementations for JVM, Native, and JS. Feedback on the changes highlights a critical issue where fatal exceptions (such as OutOfMemoryError) could cause await() to hang indefinitely because the completion gate is not signalled in a finally block. Additionally, it is recommended to clear registered onCancel hooks upon task completion to prevent potential memory leaks.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Code Review

This pull request introduces BackgroundTask, a cross-platform, cooperatively cancellable, and progress-pollable background worker implementation for JVM, Native, and JS targets. While the JVM and Native platforms run tasks concurrently on daemon threads, the JS platform executes them inline. The feedback highlights two critical issues in the shared state machine: first, catching only NonFatal exceptions can cause await() to hang indefinitely if a fatal exception or InterruptedException occurs; second, failing to clear registered onCancel hooks upon task completion leads to memory leaks and potential post-completion execution of cancel hooks. Addressing these issues by wrapping the execution in a finally block to clean up hooks and signal the gate is highly recommended.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.