Add a DocC article on promise and event ordering in Channel implementations by fabianfett · Pull Request #3693 · apple/swift-nio

fabianfett · 2026-08-05T13:22:04Z

Motivation:

The order in which a Channel fulfills an operation's promise and fires the matching pipeline event is a guarantee handlers depend on, but it was only written down implicitly, spread across NIOPosix and ChannelNotificationTest. Anyone implementing ChannelCore had to reverse engineer it.

Modifications:

Add Sources/NIOCore/Docs.docc/channel-notification-order.md, documenting the state -> promise -> pipeline event -> closeFuture ordering, with per-operation walkthroughs for registration, activation, closing, half-closure and writability, plus sections on error reporting, re-entrancy, guards and finally an short implementation checklist. Link it from the NIOCore article index.

Result:

ChannelCore implementers have a written reference for the notification order.
No functional change.

…ations Motivation: The order in which a `Channel` fulfills an operation's promise and fires the matching pipeline event is a guarantee handlers depend on, but it was only written down implicitly, spread across NIOPosix and ChannelNotificationTest. Anyone implementing ChannelCore had to reverse engineer it. Modifications: Add Sources/NIOCore/Docs.docc/channel-notification-order.md, documenting the state -> promise -> pipeline event -> closeFuture ordering, with per-operation walkthroughs for registration, activation, closing, half-closure and writability, plus sections on error reporting, re-entrancy, guards and finally an short implementation checklist. Link it from the NIOCore article index. Result: - `ChannelCore` implementers have a written reference for the notification order. - No functional change.

Lukasa · 2026-08-07T12:59:03Z

+its promises and fire its pipeline events.
+
+Almost every operation on a ``Channel`` has two visible outcomes. The first one
+is private to the caller: the ``EventLoopPromise`` that was passed to the


This framing isn't quite right. This object isn't private to the caller: it's passed up and down the channel pipeline.

Lukasa · 2026-08-07T13:00:33Z

+protocol. Its methods are public, but they exist for the use of the ``Channel``
+implementation itself and should only ever be called from the channel's
+``EventLoop``. If you are writing a ``ChannelHandler``, read this article as a
+description of the guarantees you are given, and keep using


This is not just a description of the guarantees you're given, but the ones you are expected to continue to uphold if you, for example, interact with the promises or the events.

Lukasa · 2026-08-07T13:01:31Z

+
+The rest of this article works through each operation in turn.
+
+### Registration


We may want to leverage this section in future to talk about what these events mean, but for now this is totally fine.

Lukasa · 2026-08-07T13:02:07Z

+performs the `bind` and `listen` syscalls, and only in the success continuation
+does it drive the activation, which in turn fulfills the user's bind promise.
+The comment in that code is blunt about it: it is important to call the state
+changing methods before notifying the original promise, for ordering reasons.


I'm not sure that this last note about the comment adds much.

Lukasa · 2026-08-07T13:18:57Z

+- A **registration** failure does both: it fires `errorCaught`, closes the
+  channel, and fails the register promise. A failing re-registration does the
+  same, minus the promise, because there is none.
+- A failing **deregistration** during a close is fired as `errorCaught`, whereas


Might be worth calling out that it isn't really possible for deregistration to fail in a meaningful way.

glbrntt

Neat! This is helpful.

glbrntt · 2026-08-10T13:00:32Z

+4. **Fire ``Channel/closeFuture`` last of all**, and only when the channel is
+   being torn down. This happens after the pipeline has been dismantled, on a
+   later event loop tick.


Closing is a special case so it may be worth removing it from here and the single sentence below, and instead calling it out as special and covered in more detail below.

glbrntt · 2026-08-10T13:02:09Z

+        promise?.fail(ChannelError.ioOnClosedChannel)
+        return
+    }
+    guard !self.isRegistered else {


Complete nit, but IMO if X is more readable than guard !X else

Suggested change

guard !self.isRegistered else {

if self.isRegistered {

glbrntt · 2026-08-10T13:03:22Z

+   while doing this.
+2. **Fulfill the operation's promise.** Succeed or fail the ``EventLoopPromise``
+   that the caller handed to the ``ChannelCore`` method.
+3. **Fire the matching pipeline event.** Only now announce the new state to the


Minor: examples below use "broadcast", I think it's helpful to have consistent terminology here.

glbrntt · 2026-08-10T13:05:20Z

+
+First, if your activation is asynchronous — a `connect` that returns
+`EINPROGRESS`, for example — you should hold on to the connect promise and only
+fulfill it at the point where you actually become active. NIO stores it in a


nit: "you" don't become active, the channel does

glbrntt · 2026-08-10T13:07:08Z

+`pendingConnect` property and passes it into the activation path once the
+connection has been established. Avoid succeeding the connect promise early and


I think it's worth being a bit more concrete here, "NIO stores it in a pendingConnect property..." sounds like NIO does this automatically for all channels which may be misleading if you are implementing a Channel which needs to support connect.

glbrntt · 2026-08-10T13:09:22Z

+is the one NIO uses for a full close, i.e. ``CloseMode/all``. The half-closure
+modes are covered further down.
+
+| Step | What happens |


nit: seems odd to use a table here instead of an ordered list

glbrntt · 2026-08-10T13:10:14Z

+| 5 | Succeed (or fail) the **close** promise |
+| 6 | Fire ``ChannelInboundInvoker/fireChannelInactive()`` |
+| 7 | Fire ``ChannelInboundInvoker/fireChannelUnregistered()`` |
+| 8 | On a **later event loop tick**: remove all handlers from the pipeline, then succeed ``Channel/closeFuture`` |


later or next loop tick?

glbrntt · 2026-08-10T13:11:38Z

+    //
+    // 2. Do the work and reconcile the state. Any error that we discover in
+    //    here is recorded and only fired once the state is consistent again.
+    var errorCallouts: [(ChannelPipeline) -> Void] = []


We only have at most one callout in this example: perhaps the array overcomplicates things here?

glbrntt · 2026-08-10T13:13:34Z

+    guard !self.inputShutdown else {
+        promise?.fail(ChannelError.inputClosed)


same nit as about re: guard !x else

glbrntt · 2026-08-10T13:37:37Z

+private func flushNow() {
+    // Re-entrancy protection: a write issued from one of the callouts below is
+    // picked up by this loop, rather than starting a nested flush.
+    guard !self.inFlushNow else { return }


same guard !X else nit

fabianfett requested a review from Lukasa August 5, 2026 13:22

fabianfett added the semver/none No version bump required. label Aug 5, 2026

Merge branch 'main' into ff-docc-promise-and-event-ordering

db86e12

Lukasa reviewed Aug 7, 2026

View reviewed changes

glbrntt reviewed Aug 10, 2026

View reviewed changes


		The rest of this article works through each operation in turn.

		### Registration

		`pendingConnect` property and passes it into the activation path once the
		connection has been established. Avoid succeeding the connect promise early and

		guard !self.inputShutdown else {
		promise?.fail(ChannelError.inputClosed)

Uh oh!

Conversation

fabianfett commented Aug 5, 2026

Motivation:

Modifications:

Result:

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

glbrntt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants