Function Invocation

The funcs module calls registered functions synchronously or asynchronously. An executor can propagate request context, security identity, and implementation-specific call options. This page is an API reference; target IDs, arguments, and application data represent surrounding code.

Loading

local funcs = require("funcs")

call

Calls a registered function synchronously and waits for its result.

local result, err = funcs.call("app.api:get_user", user_id)
if err then
    return nil, err
end
print(result.name)

Returns: result, error

The target uses the namespace:name format.

async

Starts a function call and returns a Future immediately. Futures allow other work to continue while the call runs and support multiple concurrent calls.

-- Start heavy computation without blocking
local future, err = funcs.async("app.process:analyze_data", large_dataset)
if err then
    return nil, err
end

-- Do other work while computation runs...

-- Wait for result when ready
local ch = future:response()
local _, open = ch:receive()
if not open then
    return nil, errors.new("future response channel closed")
end

local payload, result_err = future:result()
if result_err then
    return nil, result_err
end
local result, data_err = payload:data()
if data_err then return nil, data_err end

Returns: Future, error

new

Creates an Executor for calls that need custom context, security identity, or call options.

local exec = funcs.new()

Returns: Executor

Executor

An executor stores call context and options. Its configuration methods return new executor instances, allowing a base configuration to be reused.

with_context

Adds request-scoped values that will be available to the called function, such as trace IDs, session data, or feature flags.

local ctx = require("ctx")

-- Propagate request context to downstream services
local request_id, ctx_err = ctx.get("request_id")
if ctx_err then return nil, ctx_err end

local exec, err = funcs.new():with_context({
    request_id = request_id,
    feature_flags = {dark_mode = true}
})
if err then return nil, err end

local user, err = exec:call("app.api:get_user", user_id)
if err then return nil, err end

Returns: Executor, error

with_actor

Sets the security actor used for authorization checks in the called function.

local security = require("security")
local actor = security.actor()  -- Get current user's actor

-- Call admin function with user's credentials
local exec, err = funcs.new():with_actor(actor)
if err then return nil, err end
local result, err = exec:call("app.admin:delete_record", record_id)
if err and err:kind() == errors.PERMISSION_DENIED then
    return nil, errors.new({kind = errors.PERMISSION_DENIED, message = "User cannot delete records"})
end

Returns: Executor, error

with_scope

Sets the security scope for called functions. The scope defines the permissions available to the call.

local security = require("security")
local scope = security.new_scope()

local exec, err = funcs.new():with_scope(scope)
if err then return nil, err end

Returns: Executor, error

with_options

Sets call options such as the retry policy or the overlay network. Options are merged over any preset options of the target function entry.

-- Retry transient failures up to 5 times with exponential backoff
local exec = funcs.new():with_options({
    retry = { max_attempts = 5, initial_delay = 100 }
})
local result, err = exec:call("app.external:fetch_data", query)
if err then
    -- All attempts failed, or the error was not retryable
end

Only retryable errors trigger retries; non-retryable errors surface immediately. Temporal activity options are described in Activities.

The runtime-defined option is:

Returns: Executor, error

Selecting a network requires network.select permission on that network ID.

call and async

The executor versions of call and async use its configured context and options.

-- Build reusable executor with context
local exec = funcs.new()
    :with_context({trace_id = "abc-123"})
    :with_options({retry = {max_attempts = 3}})

-- Make multiple calls with same context
local users, users_err = exec:call("app.api:list_users")
if users_err then return nil, users_err end
local posts, posts_err = exec:call("app.api:list_posts")
if posts_err then return nil, posts_err end

Future Invocation Summary

async() returns a future representing an in-progress invocation. The methods below cover the caller-facing steps for receiving, inspecting, or canceling that invocation. See Future for the Future object reference.

response and channel

Returns the channel used to receive the result.

local time = require("time")

local future, err = funcs.async("app.api:slow_operation", data)
if err then
    return nil, err
end
local ch = future:response()  -- or future:channel()

local timeout, err = time.after("5s")
if err then
    return nil, err
end

local result = channel.select {
    ch:case_receive(),
    timeout:case_receive()
}

Returns: Channel

The response channel signals completion. After it becomes ready, call future:result() to obtain the cached value or the called function's error.

is_complete

Checks whether the future has completed without blocking.

while not future:is_complete() do
    -- do other work
    local _, sleep_err = time.sleep("100ms")
    if sleep_err then return nil, sleep_err end
end
local result, err = future:result()

Returns: boolean

is_canceled

Returns true after cancellation is requested. This does not mean the operation has finished. See the cancellation limitation below.

if future:is_canceled() then
    print("Cancellation requested")
end

Returns: boolean

result

Returns the cached result when complete or nil, nil while the operation is pending. Native futures complete only after the call frame and its owned resources are released. Requesting cancellation does not replace the eventual result; it may still be a success. Temporal workflow futures retain their recorded behavior: a marked-canceled future returns errors.CANCELED.

local value, err = future:result()
if err then
    print("Failed:", err:message())
elseif value then
    local data, data_err = value:data()
    if data_err then return nil, data_err end
    print("Got:", data)
end

Returns: Payload|table|nil, error|nil

error

Returns the operation error when the future has failed.

local err, has_error = future:error()
if has_error then
    print("Error kind:", err:kind())
end

Returns: error|nil, boolean

This method returns a non-retryable INTERNAL wrapper for a failed operation. Use result() to preserve the called function's original error metadata.

cancel

Requests cancellation of the asynchronous operation.

local canceled, err = future:cancel()
if err then return nil, err end

Returns: boolean, error

Parallel Operations

Combine async with channel.select to run and collect multiple calls concurrently.

-- Start multiple operations in parallel
local f1, err = funcs.async("app.api:get_user", user_id)
if err then return nil, err end
local f2, err = funcs.async("app.api:get_orders", user_id)
if err then return nil, err end
local f3, err = funcs.async("app.api:get_preferences", user_id)
if err then return nil, err end

-- Wait for all to complete using channels
local user_ch = f1:channel()
local orders_ch = f2:channel()
local prefs_ch = f3:channel()

local pending = {
    [user_ch] = {name = "user", future = f1},
    [orders_ch] = {name = "orders", future = f2},
    [prefs_ch] = {name = "preferences", future = f3}
}
local results = {}
while next(pending) do
    local cases = {}
    for ch in pairs(pending) do
        cases[#cases + 1] = ch:case_receive()
    end

    local r = channel.select(cases)
    local completed = pending[r.channel]
    pending[r.channel] = nil

    local payload, result_err = completed.future:result()
    if result_err then
        return nil, result_err
    end
    local data, data_err = payload:data()
    if data_err then
        return nil, data_err
    end
    results[completed.name] = data
end

Permissions

Function operations are subject to security policy evaluation.

Errors

See Error Handling for working with errors.