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 if the future has been marked canceled by its provider. See the cancellation limitation below.

if future:is_canceled() then
    print("Operation was canceled")
end

Returns: boolean

result

Returns the cached result when complete or nil while the operation is pending.

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.