38

I'm a little bit confused by some asyncio functions. I see there is BaseEventLoop.create_task(coro) function to schedule a co-routine. The documentation for create_task says its a new function and for compatibility we should use asyncio.async(coro) which by referring to docs again I see is an alias for asyncio.ensure_future(coro) which again schedules the execution of a co-routine.

Meanwhile, I've been using Task(coro) for scheduling co-routine execution and that too seems to be working fine. so, what's the difference between all these?

2 Answers 2

28

As you've noticed, they all do the same thing.

asyncio.async had to be replaced with asyncio.ensure_future because in Python >= 3.5, async has been made a keyword[1].

create_task's raison d'etre[2]:

Third-party event loops can use their own subclass of Task for interoperability. In this case, the result type is a subclass of Task.

And this also means you should not create a Task directly, because different event loops might have different ways of creating a "Task".

Edit

Another important difference is that in addition to accepting coroutines, ensure_future also accepts any awaitable object; create_task on the other hand just accepts coroutines.

4
  • Sounds like I'd better use ensure_future then. Thanks for clearing this up.
    – Elektito
    Nov 29, 2015 at 7:37
  • 1
    Unless you're writing code for Python < 3.4.4, of course ;) Nov 29, 2015 at 7:40
  • Ah, yes. I didn't pay attention! I am using Python < 3.4.4 as it happens; 3.4.3 to be precise.
    – Elektito
    Nov 29, 2015 at 7:42
  • This was counter-intuitive because it sounded like you said to use ensure_future and not create_task, so I made my research. In 2016, Guido said the opposite. If you know you have a coroutine and you want to schedule its execution, you should just call create_task directly. create_task exists so a third party loop can return a subclass so you shouldn't call the task constructor directly. Hope that clears things up for other asyncio neophytes.
    – Domino
    Jun 8, 2018 at 16:47
2

Future

A Future is an object that is supposed to have a result in the future.

Or more officially:

A Future is an awaitable object that represents an eventual result of an asynchronous operation.

Object is awaitable if it can be used in an await expression.

So, any Future can be await'ed.

Task

Docs:

Tasks are used to schedule coroutines concurrently.

When a coroutine is wrapped into a Task with functions like asyncio.create_task() the coroutine is automatically scheduled to run soon.

A Task actually is a Future:

A Future-like object that runs a Python coroutine.

Task is subclass of a Future.

asyncio.Taskinherits from Future all of its APIs except Future.set_result() and Future.set_exception().

create_task(coro)

Docs:

Wraps the coro coroutine into a Task and schedules its execution. Returns the Task object.

asyncio.ensure_future(obj, ...)

It actually ensures that obj is a Future. If it's not it creates a Task from obj. That's it.

Some conclusions

  • If obj already is a Future, ensure_future will return the same obj. In this case return value of a function may be a Future and not a Task - since Task is just a subclass of a Future.
  • With ensure_future you CAN do this:
# will create a Task
task = asyncio.ensure_future(coroutine())
# will ensure that it is a Task
task = asyncio.ensure_future(task)

or this:

# will create a Task
task = asyncio.create_task(coroutine())
# will ensure that it is a Task
task = asyncio.ensure_future(task)

So, you can call ensure_future on a Task. But you CAN'T do the same with create_task:

# will create a Task
task = asyncio.create_task(coroutine())
# will raise an exception
task = asyncio.create_task(task)

TypeError: a coroutine was expected, got Task

Pay attention

According to docs:

create_task() is the preferred way for creating new Tasks.

Deprecated since version 3.10: Deprecation warning is emitted if obj is not a Future-like object and loop is not specified and there is no running event loop.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.