Consider renaming Codec::{In, Out}

[alexcrichton]

Moved over from tokio-rs/tokio-proto#64, but the terminology of "in" and "out" can be confusing from time to time. Can we figure out names which are unambiguous?

[tikue]

Encode and Decode?

[casey]

I think this is symptomatic of a subtle issue with the Codec trait. As it stands, a Codec is a trait which knows how to serialize or deserialize frames, but the types of those frames may be different in either direction.

Although it is reasonable when considering that a Codec will often be implemented for a request/response protocol where different types are flowing in different directions, it conflicts with the plain meaning of the word "codec".

I think when most people think of a "codec", they think of something that encodes and decodes data of the same type. For example, and audio codec deserializes bytes to audio, and serializes audio to bytes. It wouldn't be natural to call something a codec that deserializes bytes to audio, and serializes video to bytes.

I think that my vote for the In and Out types are "Incoming" for the type that decode() returns, and "Outgoing" as the type that encode() takes. The mental model is that the codec sits between you and the internet/transport/whatever, and it takes Outgoing objects to encode, and gives you Incoming objects that have been decoded from the wire.

Tangent, but why is Codec a single trait, instead of an Encoder and a Decoder? I'm trying to figure this out, like perhaps there's a situation where the deserializer and serializer need to share state, but I can't think of a case where that would be needed.

[sinkuu]

Tangent, but why is Codec a single trait, instead of an Encoder and a Decoder? I'm trying to figure this out, like perhaps there's a situation where the deserializer and serializer need to share state, but I can't think of a case where that would be needed.

If Io::framed gets to require Encoder + Decoder instead of Codec, you will implement Encoder and Decoder for a codec type anyway and be able to share state between them.

[alexcrichton]

@casey we originally had the trait split, but it ended up coming at a hit to the common case of ergonomics, so we ended up unifying it into one, but retaining the two associated types to support similar use cases.

Note that Codec and framed are intended to be conveniences, not the "one true way" to do things. In that sense it's always possible to have slightly different constructions out of tree.

[Ralith]

If Io::framed gets to require Encoder + Decoder instead of Codec, you will implement Encoder and Decoder for a codec type anyway and be able to share state between them.

Io is getting split up into separate traits for 0.2 (see #62); it's a similar case of two unrelated things being welded together. AsyncRead/AsyncWrite could each have their own encode/decode methods fed an individual Encoder/Decoder. For the cases where shared state is really necessary framed could be retained, but I have a hard time seeing this as the common case.

[quodlibetor]

Transmit / Receive?

[alexcrichton]

Done in https://github.com/alexcrichton/tokio-io, the migration of this crate will be tracked by #61