Capy-Bearer Documentation

task_execute

lib call

Capy

function task_execute(target : as string, timeout_seconds : as f64, props : as any = {}) any

Description

task_execute() runs a task handler outside the request, right away, in a process of its own. It returns as soon as that process is started and never waits for the handler. This is the call for work that must not happen on the request's time and that nobody needs to wait for: sending the mail, writing the audit row, poking an external system.

The timeout is mandatory, in seconds. Bearer rounds it to milliseconds and accepts 1 through 86400000 milliseconds. The budget includes unit compilation and execution. The runner exits when the handler finishes, or ends it when the deadline expires. A task has no automatic retry or persistent queue.

Use a service for persistent state, ports, or repeated events. Duration alone does not make a task a service.

The task runs in a fresh workspace with a copy of the props. It does not see the caller's request, session, connections, or unit variables. Its printed output is not returned to the caller. The runner logs failures. Use log() for operator records and application storage for results.

Define TASK:STORE in /jobs/store.capy before using the example. The TASK handler page shows a complete unit. Relative target paths start at the request's entry directory, then try the site root. They do not use a nested component's directory. Use a site-root path for an unambiguous target. The selector is :STORE, not :TASK:STORE.

The returned pid is diagnostic information, not a task handle or proof of successful work. Record application progress in storage if callers need to check completion.

Parameters

target : a unit path followed by :NAME, naming the TASK:NAME handler to run

timeout_seconds : compilation and execution budget in seconds

props : the task input, received as the handler's props

Return Values

{ok: true, value: {pid}} when the process starts. Failures return {ok: false, error: "code"}, for example invalid_target.

Errors

An unknown unit yields invalid_target; a timeout outside the accepted millisecond range yields invalid_timeout; a process that could not be started yields spawn_failed or runner_failed. A handler the unit does not define, a trap, and the timeout are logged by the task process; the caller is not told, because it has already moved on.

Example

Capy

var started := task_execute("/jobs/store.capy:STORE", 30, key: "report-42")
if started.error?
{
	print("could not start: ", started.error)
}