Skip to content

ChannelInitializer: correct misleading comment on exceptionCaught route#16847

Merged
normanmaurer merged 1 commit into
netty:4.1from
daguimu:docs/16846-channelinitializer-comment
May 28, 2026
Merged

ChannelInitializer: correct misleading comment on exceptionCaught route#16847
normanmaurer merged 1 commit into
netty:4.1from
daguimu:docs/16846-channelinitializer-comment

Conversation

@daguimu
Copy link
Copy Markdown
Contributor

@daguimu daguimu commented May 24, 2026

Motivation:

The catch block in ChannelInitializer.initChannel(ChannelHandlerContext) currently attributes the explicit exceptionCaught(...) call to two reasons that don't match the current code:

} catch (Throwable cause) {
    // Explicitly call exceptionCaught(...) as we removed the handler before calling initChannel(...).
    // We do so to prevent multiple calls to initChannel(...).
    exceptionCaught(ctx, cause);
} finally {
    if (!ctx.isRemoved()) {
        ctx.pipeline().remove(this);
    }
}
  • The handler is not removed before initChannel(...) is called — removal happens in the finally block immediately below.
  • Re-entrance is guarded by the initMap.add(ctx) check at the top of the method, not by this catch block.

Both clauses of the comment mislead a reader trying to understand why the catch block exists.

Modification:

Rewrite the two-line comment to name the actual mechanisms:

  • the exceptionCaught(...) call routes the failure into the pipeline;
  • re-entrance is guarded by initMap.add(ctx) above;
  • handler removal happens in the finally block below.

No code change.

Result:

Future readers of initChannel(ChannelHandlerContext) can trust the comment instead of having to cross-check it against the surrounding code.

Fixes #16846.

The same wording exists on 4.1, 4.2, and 5.0; targeting 4.1 so auto-port carries it forward.

Motivation:

The catch block in initChannel(ChannelHandlerContext) currently attributes the explicit exceptionCaught(...) call to two reasons that are not accurate against the current code: it claims the handler was removed before initChannel(...) was called, but removal actually happens in the finally block below; and it credits this block with preventing multiple initChannel(...) calls, while re-entrance is in fact guarded by the initMap.add(ctx) check at the top of the method. netty#16846 flags the confusion.

Modification:

Rewrite the two-line comment to name the actual mechanisms: the call is to route the failure into the pipeline, re-entrance is guarded by initMap.add(ctx) above, and handler removal happens in the finally block below. No code change.

Result:

Future readers of initChannel(ChannelHandlerContext) can trust the comment instead of having to cross-check it against the surrounding code.

Fixes netty#16846.
@normanmaurer normanmaurer added this to the 4.1.135.Final milestone May 28, 2026
@normanmaurer normanmaurer added needs-cherry-pick-4.2 This PR should be cherry-picked to 4.2 once merged. needs-cherry-pick-5.0 This PR should be cherry-picked to 5.0 once merged. labels May 28, 2026
@normanmaurer normanmaurer merged commit 22d1be6 into netty:4.1 May 28, 2026
21 checks passed
@netty-project-bot
Copy link
Copy Markdown
Contributor

Auto-port PR for 4.2: #16853

@netty-project-bot
Copy link
Copy Markdown
Contributor

Auto-port PR for 5.0: #16854

@github-actions github-actions Bot removed the needs-cherry-pick-5.0 This PR should be cherry-picked to 5.0 once merged. label May 28, 2026
normanmaurer pushed a commit that referenced this pull request May 28, 2026
…ptionCaught route (#16854)

Auto-port of #16847 to 5.0
Cherry-picked commit: 22d1be6

---
Motivation:

The catch block in
`ChannelInitializer.initChannel(ChannelHandlerContext)` currently
attributes the explicit `exceptionCaught(...)` call to two reasons that
don't match the current code:

```java
} catch (Throwable cause) {
    // Explicitly call exceptionCaught(...) as we removed the handler before calling initChannel(...).
    // We do so to prevent multiple calls to initChannel(...).
    exceptionCaught(ctx, cause);
} finally {
    if (!ctx.isRemoved()) {
        ctx.pipeline().remove(this);
    }
}
```

- The handler is **not** removed before `initChannel(...)` is called —
removal happens in the `finally` block immediately below.
- Re-entrance is guarded by the `initMap.add(ctx)` check at the top of
the method, **not** by this catch block.

Both clauses of the comment mislead a reader trying to understand why
the catch block exists.

Modification:

Rewrite the two-line comment to name the actual mechanisms:

- the `exceptionCaught(...)` call routes the failure into the pipeline;
- re-entrance is guarded by `initMap.add(ctx)` above;
- handler removal happens in the `finally` block below.

No code change.

Result:

Future readers of `initChannel(ChannelHandlerContext)` can trust the
comment instead of having to cross-check it against the surrounding
code.

Fixes #16846.

The same wording exists on 4.1, 4.2, and 5.0; targeting 4.1 so auto-port
carries it forward.

Co-authored-by: Guimu <[email protected]>
normanmaurer added a commit that referenced this pull request May 28, 2026
…ptionCaught route (#16853)

Auto-port of #16847 to 4.2
Cherry-picked commit: 22d1be6

---
Motivation:

The catch block in
`ChannelInitializer.initChannel(ChannelHandlerContext)` currently
attributes the explicit `exceptionCaught(...)` call to two reasons that
don't match the current code:

```java
} catch (Throwable cause) {
    // Explicitly call exceptionCaught(...) as we removed the handler before calling initChannel(...).
    // We do so to prevent multiple calls to initChannel(...).
    exceptionCaught(ctx, cause);
} finally {
    if (!ctx.isRemoved()) {
        ctx.pipeline().remove(this);
    }
}
```

- The handler is **not** removed before `initChannel(...)` is called —
removal happens in the `finally` block immediately below.
- Re-entrance is guarded by the `initMap.add(ctx)` check at the top of
the method, **not** by this catch block.

Both clauses of the comment mislead a reader trying to understand why
the catch block exists.

Modification:

Rewrite the two-line comment to name the actual mechanisms:

- the `exceptionCaught(...)` call routes the failure into the pipeline;
- re-entrance is guarded by `initMap.add(ctx)` above;
- handler removal happens in the `finally` block below.

No code change.

Result:

Future readers of `initChannel(ChannelHandlerContext)` can trust the
comment instead of having to cross-check it against the surrounding
code.

Fixes #16846.

The same wording exists on 4.1, 4.2, and 5.0; targeting 4.1 so auto-port
carries it forward.

Co-authored-by: Guimu <[email protected]>
Co-authored-by: Norman Maurer <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants