Add drain support for send messages about websockets

[aaugustin]

This is probably a good idea, however, it's a breaking API change: ws.send() would become a coroutine, while it's currently a function.

For the record, drain() was added to asyncio recently. It didn't exist when I wrote most of the current implementation.

[chrisprobst]

Not necessarily, it should be possible to simply add a drain()-like method to the exposed API.

It's like the asyncio API. If you do heavy streaming, you should yield from drain() after sending. If you are only transferring a bit of json, well, do not care.

Because the current implementation does not use StreamWriter, this functionality should be implemented using a future and the following callbacks:

BaseProtocol.pause_writing()
Called when the transport’s buffer goes over the high-water mark.

BaseProtocol.resume_writing()
Called when the transport’s buffer drains below the low-water mark.

This functionality is critical for every bandwidth-hungry websocket application.

[aaugustin]

I'd rather have the library handle this behind the scenes. It's focused on simplicity.

I don't want to inflict flow control on my users and certainly not with a low-level API.

The point of this library is to provide a high-level API that "just works" -- even if it's not the fastest websockets library on Earth.

Changing the API just means I have to release a 2.0. There's nothing wrong with that.

[chrisprobst]

You are right, it would be simpler and better. Version 2.0 sounds good, definitely a huge improvement for streaming apps (I'm working on a terrain streaming app with high bandwidth requirements).

[aaugustin]

I'm currently working on making WebSocketCommonProtocol inherit from StreamReaderProtocol.

This convenience API was also added recently and appears suitable for this use case.

That will make WebSocketCommonProtocol use StreamWriter and make flow control possible through private (undocumented) attributes -- ie. you will be able to yield from ws.writer.drain(). This workaround will allow you to move forward while I think about a more general solution.

[chrisprobst]

=) Awesome. That will do it.

[aaugustin]

In my pull request, the protocol uses a StreamWriter. If you can try it and confirm that yield from ws.writer.drain() does what you expect, that would be great.

[chrisprobst]

I can confirm that it does work great. Thanks!

[aaugustin]

Cool. I'm going to merge the patch now.

I think I'll wait until Python 3.4 final is released to make a new release of websockets, in case asyncio changes again. Hopefully you can work with the master until then.