Added gen.task decorator

[ei-grad]

It provides more straightforward usage of gen.Task interface.

Example:

from functools import wraps

from tornado import gen, web 
from tornado.ioloop import IOLoop
from tornado.httpserver import HTTPServer


@gen.task
def worker(name, callback):
    callback('Hello, %s!' % name)


class MainHandler(web.RequestHandler):

    @web.asynchronous
    @gen.engine
    def get(self):
        result = yield worker('world')
        self.finish(result)


application = web.Application([
    (r"/", MainHandler),
])  

if __name__ == "__main__":
    server = HTTPServer(application)
    server.bind(8888)
    server.start(4)
    IOLoop.instance().start()

[bdarnell]

I don't like this approach because it reduces flexibility and has consequences for consistency. A function with your @task decorator can only be used as a gen.Task, and not with gen.Callback/gen.Wait, or from a non-@gen.engine function. You may decide you don't need that flexibility in your own application, but then calling your own code looks different from calling someone else's code (i.e. I wouldn't apply this decorator to AsyncHTTPClient.fetch, so you'd still need an explicit gen.Task for that function).

[finiteloop]

An approach like this might be more flexible and equally useful:

def task(method):
    """Seamless support for yield-based coroutines.                             

    If the keyword arg "callback" is given, we execute a callback-style         
    call to the wrapped method. Otherwise, we return a tornado.gen.Task         
    for use with tornado.gen.engine.                                            
    """
    @functools.wraps(method)
    def wrapper(*args, **kwargs):
        if "callback" not in kwargs:
            return tornado.gen.Task(method, *args, **kwargs)
        else:
            return method(*args, **kwargs)
    return wrapper

I use this a lot in my own projects to avoid having to choose between the two programming styles in my libraries.

[bdarnell]

Yeah, checking for a callback kwarg is a nice way of discriminating between the two styles. I've been thinking about doing something similar with my branch where I'm playing with concurrent.futures integration.

[ei-grad]

Are there any chances for something like a task decorator from @finiteloop's comment to be included in tornado.gen in the tornado 3.0 release?

[bdarnell]

There's something like it in there now, although it returns a Future instead of a gen.Task (in 3.0 Futures can be yielded in gen.engine functions). It's currently called tornado.concurrent.future_wrap, although I'm not very happy with that name and may change it before the 3.0 release is finalized.