aws / aws/aws-durable-execution-sdk-java
[Docs]: Document finally cleanup behavior during durable suspension
- Vorherrschende Sprache
- Java
- Sterne
- 28
- Forks
- 11
- Ø Merge
- 1 T. 10 Std.
- Gemergte PRs (30 T.)
- 45
Beschreibung
## 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.
Beitragsleitfaden
Rechercherichtung
Beginnen Sie in docs/advanced/error-handling.md mit dem Abschnitt „Handling SuspendExecutionException“ und sehen Sie sich die verlinkte gemeinsame Dokumentationsanfrage an, um den Kontext zu verstehen. Dokumentieren Sie, wie finally während einer Suspendierung funktioniert, erläutern Sie die sichere Platzierung der Bereinigung und die Weitergabe von Ausnahmen, und fügen Sie das vorgeschlagene Java-Beispiel ein; der Abschnitt ist fertig, wenn er sowohl die normale Suspendierung als auch die abschließenden Bereinigungspfade abdeckt.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- java
- Bereich
- documentation
- Issue-Typ
- Dokumentation
- Schwierigkeit
- 1/5
- Geschätzter Aufwand
- 1-3 Stunden
- Aktivitätsstatus
- Aktiv
- Klarheit
- Klar beschrieben
- Anfängerfreundlichkeit
- 88/100