Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[Docs]: Document finally cleanup behavior during durable suspension

Open Beginner friendly
  • Is something wrong?
#645 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
1-3 hours
Newbie friendliness
88/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
java
Domain
documentation

Research direction

Start in docs/advanced/error-handling.md at the “Handling SuspendExecutionException” section and review the linked shared documentation request for context. Document how finally behaves during suspension, explain safe cleanup placement and exception propagation, and include the proposed Java example; the section is done when it covers both normal suspension and terminal cleanup paths.

Written by the indexing model from the issue text.

Description

documentation pkg:sdk

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:

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:

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.

Dominant language
Java
Stars
28
Forks
13
Avg merge
2d 3h
Merged PRs (30d)
44

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from aws/aws-durable-execution-sdk-java

All issues in aws/aws-durable-execution-sdk-java

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.