Concepts

These pages use one word for each object. The table is the list. A later page does not introduce a second word for the same object.

Word	Meaning
step	A named Go function. The function returns a value and an error.
action	A named Go function. The function returns only an error.
workflow	A definition of a DAG. You build it with Define or DefineResult.
run	One execution of a step, an action, or a workflow. The run is a row.
standalone job	A run with one node. You start it with Enqueue.
node	One step or one action inside a run.
future	The typed output of a node. You pass a future to the next Do.
handler	The Go function that a worker calls for a step or an action.
client	The value that New returns.
worker	A client that calls handlers. You start it with Start.
producer	A client with no handlers. Start returns ErrProducerOnly.
result	The typed output of a completed run. Result waits and returns it.
schedule	A row that starts runs from a cron specification.
signal	A named payload that you send to a waiting run.
queue	A name that selects which workers claim a step.
lease	The interval during which one worker owns a running step.
attempt	One call of a handler that counts against the attempt limit.
reclaim	A new claim after a lease expires. A reclaim is not an attempt.

Do not use "task", "pipeline", or "promise" for these objects. "Job" means a standalone job. A workflow execution is a run.

Three calls

You declare the work. You submit the work. You read the run.

fetch := cyclone.NewStep("fetch", fetchPage)
save := cyclone.NewStep("save", savePage)

ingest := cyclone.DefineResult("ingest",
    func(b *cyclone.Builder, url string) (*cyclone.Future[Receipt], error) {
        page := fetch.Do(b, cyclone.Lit(url))
        return save.Do(b, page), nil
    })

run, err := ingest.Submit(ctx, client, url)
receipt, err := run.Result(ctx)

Do does not call the handler. Do adds a node to the graph. The worker calls the handler later.

A future has no method that blocks inside the builder. An if in the builder can read the submit input. An if cannot read the future value. That value does not exist yet.

Result, Wait, and Output

Method	Waits	Returns
Result	Yes	The output. A failed or cancelled run returns an error that matches ErrRunNotCompleted.
Wait	Yes	The terminal status. A failed run is not an error. Read State.
Output	No	The output of a completed run. Any other state returns an error.

A cancel of the context stops Result or Wait. The run continues.

What stays fixed

The builder writes the graph at submit time. Cyclone inserts the run and every node in one transaction. You cannot add a node to that run later.

Two nodes can grow after submit, and the node itself is still fixed:

• ForEach adds one item task for each element of an upstream list.
• Child starts a second run. The child builder runs when the child input exists.

Order in the builder does not create an edge. A future input creates a data edge. After creates an order edge. Nodes with no edge can proceed together.

Where state is

Postgres holds the run. The worker does not. A worker claims a row, calls the handler, and writes the result. If the process stops, the lease expires and another worker can claim the step.

CompletionTx is a transaction that commits with the step. A write on that transaction commits with the completion, or it rolls back with the completion.

Next

• Errors
• Mental model
• Static DAGs