Refactor codec::length_delimited

[hawkw]

Motivation

The current tokio::codec::length_delimited module provides its own
Framed, FramedRead, and FramedWrite types which provide the same
functionality as the types of the same name in the codec module.
However, it's not currently possible to use the codec::Framed{Read, Write}
types with the length-delimited codec; instead, the separate
types in the length_delimited module must be used.

Solution

This branch unifies length_delimited with the rest of tokio::codec,
by replacing the private length_delimited::Decoder type with a public
length_delimited::Codec that implements both codec::Encoder and
codec::Decoder. It may now be used with the Framed, FramedRead,
and FramedWrite types in tokio_codec. This branch also updates the
API documentation and tests to reflect these changes.

Refs: #500

[hawkw]

Issue #500's todo list also includes adding tests and a fix for #497; I'm going to start on that in a subsequent PR.

Edit: Actually, having looked at #497, I think this change may fix it as well, provided the same issue doesn't exist in codec::FramedWrite. Will add tests to make sure that's the case regardless.

[hawkw]

Opened #576 on top of this branch to fix issue #497.

[carllerche]

I'll have to review this in more depth when I'm fresh, however after an initial scan, this seems like an improvement.

I wonder why it was originally done the other way. Do you have any thoughts about this? Do you see any disadvantages to this route?

[hawkw]

@carllerche

I wonder why it was originally done the other way. Do you have any thoughts about this? Do you see any disadvantages to this route?

I'm not sure what the original motivation behind the prior implementation was. I did a little digging, and it looks like the length_delimited code was originally added to the project in tokio-rs/tokio-io#16. That PR doesn't contain any discussion of why the length-delimited framer wasn't implemented using theFramedRead, FramedWrite, and Framed types. However, these types did exist at the time, so the reason length_delimited got its own such types was not just that the more general API wasn't there yet. As far as I can tell, the only historical discussion of length_delimited and the Framed types is tokio-rs/tokio-io#63, which mainly describes the difficulties with the prior approach.

I can't think of any obvious technical disadvantages to this change, but it's certainly possible I've overlooked something.

[carllerche]

Ok, I found the main difference. The original implementation is able to take advantage of vectored writes to avoid having to perform a large amount of data copying.

That said, the win of this is particular implementation is debatable. I originally wrote this to support HTTP/2.0, but ended up not using this codec.

Additionally, the current implementation is not ideal for small frames.

So, I am not necessarily opposed to merging this refactor.

[carllerche]

Thoughts I started writing up.

[carllerche]

Since this will be the main type, maybe we should name it LengthDelimited. This way, when used, it will be Framed<T, LengthDelimited>.

[tobz]

Shouldn't the name be LengthDelimitedCodec if we're matching existing codecs?

[carllerche]

I would avoid this type def for now. We can always add them later if needed.

[carllerche]

Same

Made all requested changes in aeec3d6 and 84046be

[hawkw]

@carllerche I'm not sure what's the right way to deal with the issue around vectored writes, as that is a potentially significant change in behaviour. However, I believe I've addressed all the other requested changes, in case we still want to go through with merging this branch despite the vectored writes issue.

[tobz]

If @carllerche is cool with merging this sans optimization, seems worth it.

[carllerche]

I'm fine with merging it.