Document connection pool best usage and caveats

[mpaolini]

A wrong usage of connection pool may cause deadlocks. See #113 #127 #128 for reference. Expecially issue 128 comment.

We should document what's the best way of using connection pooling and also give some example of bad usage that leads to deadlocks.

[mpaolini]

Also see aio-libs/aiohttp#981

[mpaolini]

aiohttp demo polls app has been refactored lately to match the connection pool best practices.
I am doing similar work for aiopg examples too.

Basically it boils down to:

async def index(request): 
     # the view function acquires the connection
    async with request.app['db'].acquire() as conn:
        # the connection is passed down to db utlity functions
        db.do_some_query(conn)

While the approach is sound and simple, I think it may encourage taking the connection out of the pool for longer than needed. I will point it out in the docs.

[asvetlov]

Good

[mpaolini]

Proposed patch is in #133

[asvetlov]

Fixed by #133