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

[Docs]: Document finally cleanup behavior during durable suspension

Abierto Apto para principiantes
#645 1 comentario 0 reacciones 0 asignados Ver en GitHub
documentation pkg:sdk
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

Abrir la 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

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.