aws / aws/aws-durable-execution-sdk-java
[Docs]: Document finally cleanup behavior during durable suspension
- Lenguaje dominante
- Java
- Estrellas
- 28
- Forks
- 11
- Merge medio
- 1 d 8 h
- PR fusionados (30 d)
- 47
Descripción
## 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.
Guía de contribución
Línea de trabajo
Comienza en docs/advanced/error-handling.md, en la sección “Handling SuspendExecutionException”, y revisa la solicitud de documentación compartida enlazada para entender el contexto. Documenta cómo se comporta finally durante la suspensión, explica dónde colocar de forma segura la limpieza y cómo se propagan las excepciones, e incluye el ejemplo de Java propuesto; la sección estará terminada cuando cubra tanto la suspensión normal como las rutas de limpieza terminales.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Stack tecnológico
- java
- Área
- documentation
- Tipo de issue
- Documentación
- Dificultad
- 1/5
- Tiempo estimado
- 1-3 horas
- Estado de actividad
- Activo
- Claridad
- Bien especificado
- Aptitud para principiantes
- 88/100