API reference¶
map_unordered
async
¶
map_unordered(
function_name: str,
inputs: list[Any],
/,
*,
input_key: str,
constant_args: dict[str, Any] | None = None,
memory: int | None = None,
endpoint_url: str | None = None,
project: str | None = None,
dispatchers: int | Literal["auto"] = "auto",
concurrency: int = DEFAULT_CONCURRENCY,
retries: int = 2,
on_progress: Callable[[int], None] | None = None,
dispatcher_stats: list[dict[str, Any]] | None = None,
invocation_stats: list[dict[str, Any]] | None = None,
) -> AsyncGenerator[tuple[int, Any], None]
Invoke function_name once per value of inputs, yielding
(index, output) as each output comes back. If outputs
are not needed, use for_each.
Refer to Session.map_unordered for argument
definitions.
endpoint_url onwards are the dispatch settings documented on
Session, applied to a session opened for this call alone - which
closes when the iterator does, so stopping early still shuts the
client down.
Yields:
| Type | Description |
|---|---|
AsyncGenerator[tuple[int, Any], None]
|
|
for_each
async
¶
for_each(
function_name: str,
inputs: list[Any],
/,
*,
input_key: str,
constant_args: dict[str, Any] | None = None,
memory: int | None = None,
endpoint_url: str | None = None,
project: str | None = None,
dispatchers: int | Literal["auto"] = "auto",
concurrency: int = DEFAULT_CONCURRENCY,
retries: int = 2,
on_progress: Callable[[int], None] | None = None,
dispatcher_stats: list[dict[str, Any]] | None = None,
invocation_stats: list[dict[str, Any]] | None = None,
) -> None
Invoke function_name once for each value of inputs. This is
the same as map_unordered except nothing is returned.
Refer to Session.map_unordered for argument
definitions.
Session
dataclass
¶
Session(
endpoint_url: str | None = None,
project: str | None = None,
dispatchers: int | Literal["auto"] = "auto",
concurrency: int = DEFAULT_CONCURRENCY,
retries: int = 2,
on_progress: Callable[[int], None] | None = None,
dispatcher_stats: list[dict[str, Any]] | None = None,
invocation_stats: list[dict[str, Any]] | None = None,
)
The deployed lambdas, holding settings and stats for a session.
Use as async with.
endpoint_url
class-attribute
instance-attribute
¶
endpoint_url: str | None = None
None uses AWS with credentials and region picked up from the local
environment; LOCAL_ENDPOINT_URL uses a local cargo
lambda watch instead.
project
class-attribute
instance-attribute
¶
project: str | None = None
The project the lambdas were deployed as, which prefixes every name on AWS:
the dispatcher is <project>-dispatcher, and a worker "copy" is
<project>-copy. None uses the names as given. Against a local cargo lambda
watch, names are never prefixed, as it serves each function under its binary's
name.
dispatchers
class-attribute
instance-attribute
¶
dispatchers: int | Literal['auto'] = 'auto'
The number of dispatchers the inputs are partitioned across.
"auto" uses the fewest number of dispatchers that respects AWS Lambda
limits.
concurrency
class-attribute
instance-attribute
¶
concurrency: int = DEFAULT_CONCURRENCY
The total number of worker lambdas in flight for the whole call, split across dispatchers.
retries
class-attribute
instance-attribute
¶
retries: int = 2
How many times to retry a failed request to Lambda (per invocation). The default is 2, which is 3 attempts in total. A worker that ran and raised is never retried: the same payload gets the same output.
on_progress
class-attribute
instance-attribute
¶
on_progress: Callable[[int], None] | None = None
Called as invocations complete, with how many more have since the last call.
dispatcher_stats
class-attribute
instance-attribute
¶
dispatcher_stats: list[dict[str, Any]] | None = None
Pass a list to collect stats for the dispatchers - one record per dispatcher invocation. A call stops at its first failed invocation without waiting for these, so it collects none. Each record holds:
req_id- AWS's id for the dispatcher's own invocation, for finding its run in CloudWatchdispatched- invocations it sent, which is its partition's sizeretried- attempts beyond the first, across the partitionretry_wait_ms- summed wait before those attemptscold- whether the execution environment was cold, orNonefor a local run, which has no shared client set to buildconnections- HTTP/2 connections the invocations were spread overelapsed_ms- how long the partition tookcall- whichmap_unorderedorfor_eachof the session this wascall_start- when that call began, as epoch seconds
invocation_stats
class-attribute
instance-attribute
¶
invocation_stats: list[dict[str, Any]] | None = None
Pass a list to collect stats for the function invocations - one record per worker function invocation, holding:
index- the position ininputsof the input it ranreq_id- AWS's id for the worker invocation, for joining to CloudWatch. Empty againstcargo lambda watch, which assigns noneinvoke_start,invoke_end- epoch seconds, spanning every attemptcall,call_start- as indispatcher_stats
function_name ¶
function_name(
name: str, /, *, memory: int | None = None
) -> str
The name a call to name invokes, such as <project>-copy-3538 on AWS, for
finding the function's logs or metrics. Works whether or not the session is open.
map_unordered ¶
map_unordered(
function_name: str,
inputs: list[Any],
/,
*,
input_key: str,
constant_args: dict[str, Any] | None = None,
memory: int | None = None,
) -> AsyncGenerator[tuple[int, Any], None]
Invoke function_name once per value of inputs, yielding
(index, output) as each output comes back. If outputs
are not needed, use for_each.
Each worker's payload is a dict with the input value
under input_key, plus a copy of constant_args (if supplied).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
function_name
|
str
|
The worker's name in its project, such as |
required |
inputs
|
list[Any]
|
The values to pass to the function, one entry per invocation. |
required |
input_key
|
str
|
The name of the key for the input in each worker's
payload. Must match the field the worker deserialises it into:
for a Rust worker, a field of its |
required |
constant_args
|
dict[str, Any] | None
|
Optional extra arguments to pass to each function invocation. |
None
|
memory
|
int | None
|
Which of the worker's deployed memory sizes to use, in MB, or
|
None
|
Yields:
| Type | Description |
|---|---|
AsyncGenerator[tuple[int, Any], None]
|
|
for_each
async
¶
for_each(
function_name: str,
inputs: list[Any],
/,
*,
input_key: str,
constant_args: dict[str, Any] | None = None,
memory: int | None = None,
) -> None
Invoke function_name once for each value of inputs. This is
the same as map_unordered except nothing is
returned, and it
waits for the whole call.
Refer to map_unordered for argument definitions.
invoke_detached
async
¶
invoke_detached(
function_name: str, /, **payload: Any
) -> None
Invoke function_name once with the given payload and do not wait for it.
Useful for "fire and forget" semantics, where failing after submission
and not learning about the failure is acceptable - failing to submit
raises. For a synchronous one-off, use
for_each with a single input.
Stats¶
stats ¶
What calls recorded about themselves, and how to render it.
Two kinds of record, one per level, each collected only when a caller
passes Session a list:
dispatcher_stats- one per dispatcher invocation, i.e. per partition per call.summarize_dispatchersrenders them.invocation_stats- one per worker invocation, built by the dispatcher only when asked (return_stats), and arriving on the frames as the call goes.summarize_invocationsrenders them.
Every record carries call, the 0-based index of the
map_unordered or
for_each call it came from, and call_start,
time.time() when that call began. Records group by call because it is an
index: two calls that read the same clock value would merge on a timestamp.
An invocation's duration is time queued for a connection, plus the round trip, plus execution.
summarize_dispatchers ¶
summarize_dispatchers(dispatcher_stats: list[Stats]) -> str
A short human-readable summary of dispatchers.
summarize_invocations ¶
summarize_invocations(
invocation_stats: list[Stats],
elapsed: float | None = None,
max_pool_connections: int | None = None,
) -> str
A short human-readable summary of invocation timings.
elapsed is the caller's wall clock. Without it the wall time and
rate are left out rather than derived from the records, whose span
starts at the first invocation rather than at the call.
write_jsonl ¶
write_jsonl(stats: list[Stats], path: str | Path) -> None
Write one JSON object per record.
Timeline¶
timeline ¶
A timeline of invocations: one row per invocation, showing when its call began, when it went on the wire, when the function actually ran, and when it came back.
Adapted from cubed's cubed/diagnostics/timeline.py.
generate_timeline ¶
generate_timeline(
records: Sequence[Stats],
title: str | None = None,
max_points: int = DEFAULT_MAX_POINTS,
) -> Any
Build the figure. Returns a matplotlib Figure for the caller to save.
matplotlib is imported lazily: it is an optional extra
(map-lambda[diagnostics]).