What's the difference between loop.create_task, asyncio.async/ensure_future and Task?

Question

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?

Jashandeep Sohi · Accepted Answer · 2015-11-29T08:15:24.687

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.

edited Nov 29 '15 at 08:15

answered Nov 29 '15 at 07:02

Jashandeep Sohi

4,903
2
23
25

Sounds like I'd better use `ensure_future` then. Thanks for clearing this up. – Elektito Nov 29 '15 at 07:37
1

Unless you're writing code for Python < 3.4.4, of course ;) – Jashandeep Sohi Nov 29 '15 at 07: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 '15 at 07: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](https://github.com/python/asyncio/issues/477#issuecomment-268709555). 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 08 '18 at 16:47

egvo · Answer 2 · 2022-07-15T09:30:55.297

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.