Immediate execution¶

This is the default backend if another is not specified in your settings file. The ImmediateBackend runs enqueued Tasks immediately, rather than in the background. This allows background Task functionality to be slowly added to an application, before the required infrastructure is available.

To use it, set BACKEND to "django.tasks.backends.immediate.ImmediateBackend":

TASKS = {"default": {"BACKEND": "django.tasks.backends.immediate.ImmediateBackend"}}

The ImmediateBackend may also be useful in tests, to bypass the need to run a real background worker in your tests.

虚拟后端¶

The DummyBackend doesn't execute enqueued Tasks at all, instead storing results for later use. Task results will forever remain in the READY state.

This backend is not intended for use in production - it is provided as a convenience that can be used during development and testing.

To use it, set BACKEND to "django.tasks.backends.dummy.DummyBackend":

TASKS = {"default": {"BACKEND": "django.tasks.backends.dummy.DummyBackend"}}

The results for enqueued Tasks can be retrieved from the backend's results attribute:

>>> from django.tasks import default_task_backend
>>> my_task.enqueue()
>>> len(default_task_backend.results)
1

Stored results can be cleared using the clear() method:

>>> default_task_backend.clear()
>>> len(default_task_backend.results)
0

Third-party backends¶

As mentioned at the beginning of this section, Django includes backends suitable for development and testing only. Production systems should rely on backends that supply a worker process and a durable queue implementation. Available third-party backends are listed on the Community Ecosystem page and the Tasks framework grid from Django Packages.

To use an external Task backend with Django, use the Python import path as the BACKEND of the TASKS setting, like so:

TASKS = {
    "default": {
        "BACKEND": "path.to.backend",
    }
}

A Task backend is a class that inherits BaseTaskBackend. At a minimum, it must implement BaseTaskBackend.enqueue(). If you're building your own backend, you can use the built-in Task backends as reference implementations. You'll find the code in the django/tasks/backends/ directory of the Django source.

异步支持¶

Django has developing support for asynchronous Task backends.

BaseTaskBackend has async variants of all base methods. By convention, the asynchronous versions of all methods are prefixed with a. The arguments for both variants are the same.

Retrieving backends¶

Backends can be retrieved using the task_backends connection handler:

from django.tasks import task_backends

task_backends["default"]  # The default backend
task_backends["reserve"]  # Another backend

The "default" backend is available as default_task_backend:

from django.tasks import default_task_backend

Task context¶

Sometimes, the running Task may need to know context about how it was enqueued, and how it is being executed. This can be accessed by taking a context argument, which is an instance of TaskContext.

To receive the Task context as an argument to your Task function, pass takes_context when defining it:

import logging
from django.core.mail import send_mail
from django.tasks import task

logger = logging.getLogger(__name__)


@task(takes_context=True)
def email_users(context, emails, subject, message):
    logger.debug(
        f"Attempt {context.attempt} to send user email. Task result id: {context.task_result.id}."
    )
    return send_mail(
        subject=subject, message=message, from_email=None, recipient_list=emails
    )

Modifying Tasks¶

Before enqueueing Tasks, it may be necessary to modify certain parameters of the Task. For example, to give it a higher priority than it would normally.

A Task instance cannot be modified directly. Instead, a modified instance can be created with the using() method, leaving the original as-is. For example:

>>> email_users.priority
0
>>> email_users.using(priority=10).priority
10

事务¶

For most backends, Tasks are run in a separate process, using a different database connection. When using a transaction, without waiting for it to commit, workers could start to process a Task which uses objects it can't access yet.

For example, consider this simplified example:

@task
def my_task(thing_num):
    Thing.objects.get(num=thing_num)


with transaction.atomic():
    Thing.objects.create(num=1)
    my_task.enqueue(thing_num=1)

To prevent the scenario where my_task runs before the Thing is committed to the database, use transaction.on_commit(), binding all arguments to enqueue() via functools.partial():

from functools import partial

from django.db import transaction

with transaction.atomic():
    Thing.objects.create(num=1)
    transaction.on_commit(partial(my_task.enqueue, thing_num=1))

Updating results¶

A TaskResult contains the status of a Task's execution at the point it was retrieved. If the Task finishes after get_result() is called, it will not update.

To refresh the values, call the django.tasks.TaskResult.refresh() method:

>>> result.status
RUNNING
>>> result.refresh()  # or await result.arefresh()
>>> result.status
SUCCESSFUL

Return values¶

If your Task function returns something, it can be retrieved from the django.tasks.TaskResult.return_value attribute:

>>> result.status
SUCCESSFUL
>>> result.return_value
42

If the Task has not finished executing, or has failed, ValueError is raised.

>>> result.status
RUNNING
>>> result.return_value
Traceback (most recent call last):
...
ValueError: Task has not finished yet

Errors¶

If the Task doesn't succeed, and instead raises an exception, either as part of the Task or as part of running it, the exception and traceback are saved to the django.tasks.TaskResult.errors list.

Each entry in errors is a TaskError containing information about error raised during the execution:

>>> result.errors[0].exception_class

Note that this is just the type of exception, and contains no other values. The traceback information is reduced to a string which you can use to help debugging:

>>> result.errors[0].traceback
Traceback (most recent call last):
...
TypeError: Object of type datetime is not JSON serializable