The future package lets a producer enqueue a job and wait for the value its
handler returns. Declare a Task once to tie the job arguments to the result
type; workers register a handler for it, and application code gets a bound
Func that it calls without type parameters. The value is JSON-encoded and
stored before the job is marked completed.
Contract — shared by producers and workers:
main — wiring only:
Application code — knows only the bound task:
Call is for one-shot calls: after it returns a value, it deletes the job and
its result, since nobody else knows the job ID. Unique jobs (other callers may
share them) and failed jobs stay for retention; set
future.Config.KeepCalledJobs to keep every job. Jobs from Enqueue stay
until retention removes them.
To enqueue inside a transaction, bind with future.BindTx; the result also
has EnqueueTx(ctx, tx, args). Call Await only after the transaction
commits. If the transaction rolls back, the job never exists, and Await
returns future.ErrNotFound immediately instead of waiting.
Awaiting before the commit, or after the job was deleted, gives the same
error, because storage cannot tell these cases apart.
The handler can live in the same package as the calling code when
API and workers run in one binary; when they are separate binaries, keep the
contract in a shared package and the handler in the worker. The lower-level
future.Enqueue[R], EnqueueTx[R], RegisterWorker, and Of[R] remain
available.
Await returns the handler value, or an error you can classify with
errors.Is: future.ErrDiscarded and future.ErrCancelled (both carry a
*future.JobError with the last handler error), future.ErrNoResult for a job
completed by a plain worker, future.ErrResultLost for a completed job whose
stored value disappeared without being deleted (Redis eviction), and future.ErrNotFound (also matches
driver.ErrNotFound) for a job that does not exist. Use
EnqueueTx the same way, and call Await only after the transaction commits.
Futures work with every driver. Job state is read through the portable
JobGetByID, and every built-in driver implements driver.JobResultStore, so
results live next to the jobs: a goncordia_job_results table (SQL, Cassandra,
ClickHouse, DynamoDB — run Migrate after upgrading), collection (MongoDB,
Firestore), or key (Redis). Deleting a job deletes its result. Set
future.Config.Store to keep results elsewhere, for example jobs in Postgres
and results in your own Redis-backed JobResultStore. When producer
and worker pool share a Manager in one process, Await wakes immediately.
Across processes it polls every PollInterval on the injected clock. Delivery
stays at-least-once: the last stored value wins if a handler runs twice.
Runnable examples: future/example_test.go runs the
whole flow on the in-memory driver with a clock.Manual, and
driver/pgxv5/example_future_test.go
enqueues with BindTx inside a Postgres transaction and awaits the result.