FunctionCall

class FunctionCall(typing.Generic, modal.object.Object)

A reference to an executed function call.

Constructed using .spawn(...) on a Modal function with the same arguments that a function normally takes. Acts as a reference to an ongoing function call that can be passed around and used to poll or fetch function results at some later time.

Conceptually similar to a Future/Promise/AsyncResult in other contexts and languages.

hydrate

hydrate(self, client=None)

Synchronize the local object with its identity on the Modal server.

It is rarely necessary to call this method explicitly, as most operations will lazily hydrate when needed. The main use case is when you need to access object metadata, such as its ID.

Added in v0.72.39: This method replaces the deprecated .resolve() method.

logs

logs: FunctionCallLogsManager

Access logs for a single FunctionCall.

Use fetch() to read logs from a UTC time range, tail() to read the most recent logs, and stream() to follow new logs as they arrive.

See Also

modal app logs: CLI access to logs for an App.

logs.fetch

fetch(self, *, since=None, until=None, source=None, search_text="")

Fetch all associated logs corresponding to the date range and filters.

Parameters

since datetime | None

Start date to fetch logs from. Must be in UTC or timezone-naive, which is interpreted as local time. By default, this will fetch logs from the start of the function call.

until datetime | None

Defaults to current date if None. Must be in UTC or timezone-naive, which is interpreted as local time.

source LogSource | None

Filter by source: 'stdout', 'stderr', or 'system'.

search_text str

Filter by search text. (Default is "")

Yields

LogEntry objects in chronological order.

Usage

function = modal.Function.from_name("my-app", "train")
call = function.spawn()

for entry in call.logs.fetch():
    print(entry.timestamp, entry.message, end="")

logs.tail

tail(self, entries=100, *, source=None)

Fetch the most recent FunctionCall logs.

Parameters

entries int

The number of log entries to return. (Default is 100)

source LogSource | None

Filter by source: 'stdout', 'stderr', or 'system'.

Yields

LogEntry objects in chronological order.

Usage

function = modal.Function.from_name("my-app", "train")
call = function.spawn()

for entry in call.logs.tail(entries=10):
    print(entry.timestamp, entry.message, end="")

logs.stream

stream(self, timeout=None)

Stream new FunctionCall logs until the timeout is reached. The timeout specifies the number of seconds to wait between log entries before terminating the stream. This method will stop when the FunctionCall is observed to have completed, or when the timeout is reached. The completion check is best-effort; if completion cannot be determined, the stream will continue until the timeout is reached.

Parameters

timeout float | None

Number of seconds to wait between log entries before terminating the stream. By default, this will block until it is interrupted.

Yields

LogEntry objects as they arrive.

Usage

function = modal.Function.from_name("my-app", "train")
call = function.spawn()

for entry in call.logs.stream():
    print(entry.message, end="")

num_inputs

num_inputs(self)

Get the number of inputs in the function call.

Returns

How many inputs this function call includes (e.g. 1 for .spawn(), more for .spawn_map()).

get

get(self, timeout=None, *, index=0)

Get the result of the index-th input of the function call.

.spawn() calls have a single output, so only specifying index=0 is valid. A non-zero index is useful when your function has multiple outputs, like via .spawn_map().

This function waits indefinitely by default. It takes an optional timeout argument that specifies the maximum number of seconds to wait, which can be set to 0 to poll for an output immediately.

The returned coroutine is not cancellation-safe.

Parameters

timeout float | None

Maximum seconds to wait for a result, or None to wait indefinitely.

index int

Which input's result to retrieve (typically 0 for .spawn()). (Default is 0)

Returns

The deserialized return value from that input.

iter

iter(self, *, start=0, end=None)

Iterate in-order over the results of the function call.

Optionally, specify a range [start, end) to iterate over.

If end is not provided, it will iterate over all results.

Parameters

start int

First input index to include (inclusive). (Default is 0)

end int | None

One past the last index to include, or None for all remaining inputs.

Yields

Each result value in index order.

Usage

@app.function()
def my_func(a):
    return a ** 2


@app.local_entrypoint()
def main():
    fc = my_func.spawn_map([1, 2, 3, 4])
    assert list(fc.iter()) == [1, 4, 9, 16]
    assert list(fc.iter(start=1, end=3)) == [4, 9]

get_call_graph

get_call_graph(self)

Fetch information about the graph of Inputs this FunctionCall is part of.

Note: the call graph data is not populated in real-time, and its capture is best-effort. We do not recommend relying on this method for critical use cases.

See the modal.types reference for information on the return values.

Returns

A list of InputInfo nodes describing the call graph.

cancel

cancel(self, terminate_containers=False)

Cancel the FunctionCall and terminate its inputs without retrying.

Parameters

terminate_containers bool

If True, terminate the containers running the cancelled inputs. Any other inputs running concurrently on those containers will be rescheduled. (Default is False)

from_id

from_id(cls, function_call_id, client=None)

Instantiate a FunctionCall object from an existing ID.

Note that it’s only necessary to re-instantiate the FunctionCall with this method if you no longer have access to the original object returned from Function.spawn.

Parameters

function_call_id str

Object ID of an existing function call (e.g. from FunctionCall.object_id).

client "modal.client.Client | None"

Modal client to use; defaults to Client.from_env() when omitted.

Returns

A FunctionCall handle for the given ID.

Usage

# Spawn a FunctionCall and keep track of its object ID
fc = my_func.spawn()
fc_id = fc.object_id

# Later, use the ID to re-instantiate the FunctionCall object
fc = FunctionCall.from_id(fc_id)
result = fc.get()

gather

gather(*function_calls)

Wait until all Modal FunctionCall objects have results before returning.

Accepts a variable number of FunctionCall objects, as returned by Function.spawn().

Raises an exception from the first failing function call.

Added in v0.73.69: This method replaces the deprecated modal.functions.gather function.

Parameters

*function_calls "_FunctionCall[T]"

FunctionCall instances to wait on (same order as the returned sequence).

Returns

Results in the same order as function_calls (like asyncio.gather).

Usage

fc1 = slow_func_1.spawn()
fc2 = slow_func_2.spawn()

result_1, result_2 = modal.FunctionCall.gather(fc1, fc2)