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

[Docs]: Document finally cleanup behavior during durable suspension

Ouverte Adaptée aux débutants
#645 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub
documentation pkg:sdk
Langage dominant
Java
Étoiles
28
Forks
11
Merge moyen
1 j 8 h
PR mergées (30 j)
47

Description

## 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.

Guide de contribution

Ouvrir le guide de contribution

Piste de recherche

Commencez dans docs/advanced/error-handling.md, à la section « Handling SuspendExecutionException », et consultez la demande de documentation partagée liée pour le contexte. Documentez le comportement de finally pendant la suspension, expliquez où placer le nettoyage de manière sûre et comment les exceptions se propagent, et incluez l’exemple Java proposé ; la section est terminée lorsqu’elle couvre à la fois la suspension normale et les chemins de nettoyage terminaux.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
java
Domaine
documentation
Type d'issue
Documentation
Difficulté
1/5
Temps estimé
1-3 heures
Activité
Active
Clarté
Clairement spécifiée
Accessibilité débutants
88/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.