aws / aws/aws-durable-execution-sdk-java
[Docs]: Document finally cleanup behavior during durable suspension
- 主要言語
- Java
- スター
- 28
- フォーク
- 11
- 平均マージ
- 1日 8時間
- マージ済み PR(30日)
- 47
説明
## Issue
The `Handling SuspendExecutionException` section correctly explains that `SuspendExecutionException` extends `Error`, bypasses a normal `catch (Exception e)`, and must never be swallowed.
It does not currently explain the related `finally` behavior: Java executes an active `finally` block while `SuspendExecutionException` unwinds the stack. As a result, resource cleanup placed in `finally` can run during a normal durable suspension rather than only when the overall durable execution succeeds or fails.
This applies to any operation that can suspend, including `wait`, `waitForCondition`, callbacks, invokes, retry delays, and suspension inside map or parallel branches.
For example, this pattern can terminate a resource immediately when the wait suspends:
```java
try {
var resource = ctx.step("launch-resource", Resource.class,
stepCtx -> launchResource());
var result = ctx.waitForCallback("work-complete", Result.class,
(callbackId, stepCtx) -> dispatchWork(resource, callbackId));
return result;
} finally {
ctx.step("terminate-resource", Void.class,
stepCtx -> terminateResource());
}
```
## Page/Location
https://github.com/aws/aws-durable-execution-sdk-java/blob/main/docs/advanced/error-handling.md
Section: `Handling SuspendExecutionException`
## Suggested Fix
Extend the section with guidance that:
- `finally` executes when the internal suspension signal unwinds the handler stack.
- Durable cleanup that must happen only on completion or actual failure should not be placed in `finally` around suspending operations.
- Cleanup should run explicitly after successful completion and from handlers for application or operation exceptions.
- `SuspendExecutionException` must continue to propagate untouched; avoid `catch (Throwable)` unless it immediately rethrows suspension and other control-flow errors appropriately.
Include a safe Java example such as:
```java
try {
var result = performDurableWorkThatMaySuspend(ctx);
ctx.step("cleanup-resource", Void.class,
stepCtx -> cleanupResource());
return result;
} catch (Exception e) {
ctx.step("cleanup-resource", Void.class,
stepCtx -> cleanupResource());
throw e;
}
```
The cleanup step occupies the same next durable-operation position on either terminal path, while `SuspendExecutionException` bypasses `catch (Exception e)` and suspends normally.
This is the Java-specific companion to the shared documentation request: https://github.com/aws/aws-durable-execution-docs/issues/131.
コントリビューションガイド
調査の方向性
docs/advanced/error-handling.md の「Handling SuspendExecutionException」セクションから始め、コンテキストを確認するためにリンクされた共有ドキュメントリクエストを確認してください。サスペンション中に finally がどのように動作するかをドキュメント化し、安全なクリーンアップの配置と例外の伝播について説明し、提案された Java の例を含めてください。このセクションは、通常のサスペンションと終端時のクリーンアップパスの両方を扱えば完了です。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- java
- 領域
- documentation
- issue の種類
- ドキュメント
- 難易度
- 1/5
- 見積もり時間
- 1〜3時間
- 活発さ
- 活発
- 明瞭さ
- 明確に書かれている
- 初心者へのやさしさ
- 88/100