Add docs to explain inbound/outbound #142
Conversation
Sources/NIO/ChannelHandler.swift
Outdated
| /// Despite the fact that `write` is one of the methods on this `protocol`, you should avoid assuming that "outbound" events are to do with | ||
| /// writing to sockets. Instead, "outbound" events are events that are passed *to* the socket (or other event source): that is, things you tell | ||
| /// the socket to do. That includes `write` ("write this data to the socket"), but it also includes `read` ("please begin attempting to read from | ||
| /// the socket") and `bind` ("please bind the following address"), which have nothing to do with sending data. |
There was a problem hiding this comment.
@Lukasa I am not sure we should use socket here as a Channel may not be backed by a socket.
There was a problem hiding this comment.
That said the rest of the docs sounds good... Maybe just make it clear that socket is an example here.
Sources/NIO/ChannelHandler.swift
Outdated
| @@ -124,7 +129,12 @@ public protocol _ChannelOutboundHandler: ChannelHandler { | |||
|
|
|||
| /// Untyped `ChannelHandler` which handles inbound I/O events. | |||
| /// | |||
| /// We _strongly_ advice against implementing this protocol directly. Please implement `ChannelInboundHandler`. | |||
| /// Despite the fact that `channelRead` is one of the methods on this `protocol`, you should avoid assuming that "inbound" events are to do with | |||
| /// reading from sockets. Instead, "inbound" events are events that originate *from* the socket (or other event source): that is, events that the | |||
Lukasa
force-pushed
the
cb-explain-inbound-outbound
branch
from
1d0c389 to
c61d38b
Compare
|
Ok, addressed. |
|
It was me who was hitting this, we talked about it in the Slack. I think those comments are buried too deep and this somehow belongs into the main README or some other document. (Now that I think I understood it, I consider writing a blog entry about it.) What Inbound and Outbound is, is not obvious to someone who didn't do Netty before (actually I think the naming in general is not particularly good, no offence!) I (and I suspect many will) originally mapped "Inbound" to the concept of "ReadStream" and "Outbound" to the concept of a "WriteStream". But this is not at all what is going on here. I'm not yet sure how to describe it easily, but the way I understand it Outbound is like a "perform action" and Inbound is like "did perform action". It decouples the emitter from the result handler (in a pretty "distant" way). |
|
@helje5 I am happy for other naming suggestions. We used |
|
You are right, I shouldn't complain w/o providing decent alternatives ;-> I'm not sure yet, I don't fully understand yet why you do some things the way you do them. Maybe I come back to you on this later. For this particular issue, it would be cool to get some more prominent mention of this on the main README or design document (actually I recommend making the README smaller, and put the current stuff in a DESIGN.md or sth). |
|
@normanmaurer happy with this? |
Motivation: It's important to ensure that child channel users can observe the writability state of a child channel in order to avoid ballooning data in memory. Up until now we haven't supported writability notifications, but we really should. Modifications: - Added a flow controller to manage writability. - Managed data flow through promises. - Lots of tests. Result: Child channels will provide a much better signal as to whether they are writable.
Resolves #138.