From 01750fec82ea05db5721558098e92c4b69d1dea7 Mon Sep 17 00:00:00 2001 From: yaythomas Date: Tue, 8 Sep 2026 23:10:55 +0000 Subject: [PATCH] docs: correct map, parallel, wait, callback The default completion config fails the batch on the first failed item, in Python and TypeScript alike. max_concurrency caps in-flight items and a suspended item keeps its slot. A SerDes that fails to deserialize stored polling state fails wait_for_condition. A custom callback SerDes result must serialize with the default SerDes. Behavior moved to shared prose so the language tabs stay symmetric. Java and C# completion-default wording was left untouched; those SDKs were not verified for this change. --- docs/sdk-reference/operations/callback.md | 4 ++++ docs/sdk-reference/operations/map.md | 23 ++++++++++++------- docs/sdk-reference/operations/parallel.md | 20 +++++++++++----- .../operations/wait-for-condition.md | 7 +++--- 4 files changed, 37 insertions(+), 17 deletions(-) diff --git a/docs/sdk-reference/operations/callback.md b/docs/sdk-reference/operations/callback.md index f0d4bbb..37fa0ff 100644 --- a/docs/sdk-reference/operations/callback.md +++ b/docs/sdk-reference/operations/callback.md @@ -452,6 +452,10 @@ submitter step. - `retry_strategy` (optional) A callable returning a `RetryDecision` for the submitter step. See [Retry strategies](../error-handling/retries.md). + - `serdes` (optional, inherited from `CallbackConfig`) Custom `SerDes` that + deserializes the raw callback payload. The SDK then checkpoints the deserialized + value with the default SerDes, so the default SerDes must serialize whatever your + custom `SerDes` returns. See [Serialization](../state/serialization.md). === "Java" diff --git a/docs/sdk-reference/operations/map.md b/docs/sdk-reference/operations/map.md index 88b3506..0b45352 100644 --- a/docs/sdk-reference/operations/map.md +++ b/docs/sdk-reference/operations/map.md @@ -216,10 +216,12 @@ Use map to apply the same operation to every item in a collection. Use **Parameters:** - - `maxConcurrency` (optional) Maximum items running at once. Default: unlimited. + - `maxConcurrency` (optional) Maximum items in flight at once. Default: unlimited. + See [Configuration](#configuration). - `itemNamer` (optional) A function that returns a custom name for each item, used in logs and tests. - - `completionConfig` (optional) When to stop. Default: wait for all items. + - `completionConfig` (optional) When to stop. See + [Completion strategies](#completion-strategies). - `serdes` (optional) Custom `Serdes` for the `BatchResult`. - `itemSerdes` (optional) Custom `Serdes` for individual item results. - `summaryGenerator` (optional) A function invoked when the serialized `BatchResult` @@ -243,9 +245,10 @@ Use map to apply the same operation to every item in a collection. Use **Parameters:** - - `max_concurrency` (optional) Maximum items running at once. Default: unlimited. - - `completion_config` (optional) When to stop. Default: `CompletionConfig()` (lenient, - all items run regardless of failures). + - `max_concurrency` (optional) Maximum items in flight at once. Default: unlimited. + See [Configuration](#configuration). + - `completion_config` (optional) When to stop. See + [Completion strategies](#completion-strategies). - `serdes` (optional) Custom `SerDes` for the `BatchResult`. - `item_serdes` (optional) Custom `SerDes` for individual item results. - `summary_generator` (optional) A callable invoked when the serialized `BatchResult` @@ -270,7 +273,8 @@ Use map to apply the same operation to every item in a collection. Use **Parameters:** - - `maxConcurrency` (optional) Maximum items running at once. Default: unlimited. + - `maxConcurrency` (optional) Maximum items in flight at once. Default: unlimited. + See [Configuration](#configuration). - `completionConfig` (optional) When to stop. Default: `CompletionConfig.allCompleted()`. - `serDes` (optional) Custom `SerDes` for item results and the overall result. @@ -295,7 +299,7 @@ Use map to apply the same operation to every item in a collection. Use **Parameters:** - - `MaxConcurrency` (optional) Maximum items running at once. `null` (default) is + - `MaxConcurrency` (optional) Maximum items in flight at once. `null` (default) is unlimited; must be at least 1 when set. - `CompletionConfig` (optional) When to stop. Default: `CompletionConfig.AllSuccessful()`. Any item failure completes the map with `FailureToleranceExceeded`. Set @@ -678,7 +682,10 @@ Name your map operations to make them easier to identify in logs and tests. ## Configuration -Configure map behavior using `MapConfig`: +Configure map behavior using `MapConfig`. `maxConcurrency` caps items in flight, not +threads. A suspended item, for example one awaiting an invoke result or a callback, keeps +its slot until it completes. By default the batch fails on the first failed item. See +[Completion strategies](#completion-strategies) to tolerate failures or stop early. === "TypeScript" diff --git a/docs/sdk-reference/operations/parallel.md b/docs/sdk-reference/operations/parallel.md index abe1cfa..2f83c56 100644 --- a/docs/sdk-reference/operations/parallel.md +++ b/docs/sdk-reference/operations/parallel.md @@ -237,8 +237,10 @@ execute the same operation concurrently for each item in a collection. **Parameters:** - - `maxConcurrency` (optional) Maximum branches running at once. Default: unlimited. - - `completionConfig` (optional) When to stop. Default: wait for all branches. + - `maxConcurrency` (optional) Maximum branches in flight at once. Default: unlimited. + See [Configuration](#configuration). + - `completionConfig` (optional) When to stop. See + [Completion strategies](#completion-strategies). - `serdes` (optional) Custom `Serdes` for the `BatchResult`. - `itemSerdes` (optional) Custom `Serdes` for individual branch results. - `summaryGenerator` (optional) A function invoked when the serialized `BatchResult` @@ -261,7 +263,8 @@ execute the same operation concurrently for each item in a collection. **Parameters:** - - `max_concurrency` (optional) Maximum branches running at once. Default: unlimited. + - `max_concurrency` (optional) Maximum branches in flight at once. Default: unlimited. + See [Configuration](#configuration). - `completion_config` (optional) When to stop. Default: `CompletionConfig.all_successful()`. - `serdes` (optional) Custom `SerDes` for the `BatchResult`. @@ -283,7 +286,8 @@ execute the same operation concurrently for each item in a collection. **Parameters:** - - `maxConcurrency` (optional) Maximum branches running at once. Default: unlimited. + - `maxConcurrency` (optional) Maximum branches in flight at once. Default: unlimited. + See [Configuration](#configuration). - `completionConfig` (optional) When to stop. Default: `CompletionConfig.allCompleted()`. - `nestingType` (optional) `NestingType.NESTED` (default) or `NestingType.FLAT`. See @@ -302,7 +306,7 @@ execute the same operation concurrently for each item in a collection. **Parameters:** - - `MaxConcurrency` (optional) Maximum branches running at once. `null` (default) = + - `MaxConcurrency` (optional) Maximum branches in flight at once. `null` (default) = unlimited. Must be at least 1 when set. - `CompletionConfig` (optional) When to stop. Default: `CompletionConfig.AllSuccessful()`. @@ -715,7 +719,11 @@ Name your parallel operations to make them easier to identify in logs and tests. ## Configuration -Configure parallel behavior using `ParallelConfig`: +Configure parallel behavior using `ParallelConfig`. `maxConcurrency` caps branches in +flight, not threads. A suspended branch, for example one awaiting an invoke result or a +callback, keeps its slot until it completes. By default the batch fails on the first +failed branch. See [Completion strategies](#completion-strategies) to tolerate failures +or stop early. === "TypeScript" diff --git a/docs/sdk-reference/operations/wait-for-condition.md b/docs/sdk-reference/operations/wait-for-condition.md index b328320..a28771e 100644 --- a/docs/sdk-reference/operations/wait-for-condition.md +++ b/docs/sdk-reference/operations/wait-for-condition.md @@ -116,9 +116,10 @@ applied. as a durable step and each subsequent polling attempt is a retry, so avoid heavy computation or side effects and keep it focused on querying status. - `config` - A configuration object containing: - - `initialState` - The state object passed to the first check invocation. In Python - the SDK round-trips this value through the configured SerDes before the first - check, so it must be serializable by that SerDes. + - `initialState` - The state object passed to the first check invocation. The SDK + checkpoints polling state through the configured SerDes and restores it on + resume, so this value must serialize with that SerDes. A SerDes that fails to + deserialize the stored state fails the operation. - `waitStrategy` - A [Wait strategy](#wait-strategies) to control polling behavior **Returns:** The final state object from the last check function invocation.