aws / aws/aws-durable-execution-sdk-java

[Docs]: Document finally cleanup behavior during durable suspension

オープン 初心者向け
#645 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る
documentation pkg:sdk
主要言語
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

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。