Consider renaming Dispatch::{In, Out}

[casey]

This was sort of discussed in tokio-rs/tokio-core#135 née #64, but it's for Dispatch::{In, Out} instead.

I think that the current use of In and Out are unintuitive, and should be switched. The current mental model is socket-centric, In is what goes into a socket, and Out is what comes out of it. However, I personally and I suspect others, when writing network applications, think from the point of view of the client or the server.

The In thing is the thing that is coming from over the network, and the Out thing is the thing that is going out over the network. So a server takes requests in and sends responses out, and a client sends requests out and takes responses in.

I would also prefer the names Incoming and Outgoing instead of In and Out, just to be a little more explicit.

[carllerche]

In general, In, Out mean different things to different people, so it is probably not a great name. That being said, I don't have a better one right now... I'll think more about Incoming / Outgoing, but I'm not sure if that helps w/ the mixup confusion. The issue is that the point of reference for In / Out is different for everyone, so Incoming / Outgoing would have the same issue.

[casey]

I think your points are totally valid, and of course, an issue like this will always have a subjective component.

One thing to consider though is that Dispatch::{In, Out} currently has the opposite meaning of tokio core Codec::{In, Out}. In that case, In is the type that comes off the wire as a result of calling decode(), and Out is the type that goes over the wire as a result of calling encode(). I think that there is a strong argument to be made that these should be harmonized, regardless of what the actual names wind up being.

[carllerche]

To clarify, I don't think anybody likes the In / Out names... I'm hoping to change them to something completely unambiguous :P just need to figure out what.

[carllerche]

I was going to comment that maybe the types should be named Item and SinkItem, but that isn't true given that the sink vs. stream half depends on if it is a client or server.

Given that Dispatch is an advanced concept, adding solid documentation on the types is enough?

[casey]

It looks like tokio-core is going with FramedRead / Decoder, and FramedWrite / Encoder, see tokio-rs/tokio-core#135, and @alexcrichton's branch

Given that, how about Decoded and Encoded? It's not perfect, but it does sort of harmonize things.

[carllerche]

So, the "obvious" naming would be to match Sink / Stream fn names...

Send and Poll