This document describes Celery 2.4. For development docs, go here.
celery.contrib.abortable¶
Abortable tasks overview¶
For long-running Task
‘s, it can be desirable to support
aborting during execution. Of course, these tasks should be built to
support abortion specifically.
The AbortableTask
serves as a base class for all Task
objects that should support abortion by producers.
- Producers may invoke the
abort()
method onAbortableAsyncResult
instances, to request abortion. - Consumers (workers) should periodically check (and honor!) the
is_aborted()
method at controlled points in their task’srun()
method. The more often, the better.
The necessary intermediate communication is dealt with by the
AbortableTask
implementation.
Usage example¶
In the consumer:
from celery.contrib.abortable import AbortableTask
class MyLongRunningTask(AbortableTask):
def run(self, **kwargs):
logger = self.get_logger(**kwargs)
results = []
for x in xrange(100):
# Check after every 5 loops..
if x % 5 == 0: # alternatively, check when some timer is due
if self.is_aborted(**kwargs):
# Respect the aborted status and terminate
# gracefully
logger.warning("Task aborted.")
return None
y = do_something_expensive(x)
results.append(y)
logger.info("Task finished.")
return results
In the producer:
from myproject.tasks import MyLongRunningTask
def myview(request):
async_result = MyLongRunningTask.delay()
# async_result is of type AbortableAsyncResult
# After 10 seconds, abort the task
time.sleep(10)
async_result.abort()
...
After the async_result.abort() call, the task execution is not aborted immediately. In fact, it is not guaranteed to abort at all. Keep checking the async_result status, or call async_result.wait() to have it block until the task is finished.
Note
In order to abort tasks, there needs to be communication between the producer and the consumer. This is currently implemented through the database backend. Therefore, this class will only work with the database backends.
-
class
celery.contrib.abortable.
AbortableAsyncResult
(task_id, backend=None, task_name=None, app=None)¶ Represents a abortable result.
Specifically, this gives the AsyncResult a
abort()
method, which sets the state of the underlying Task to “ABORTED”.-
abort
()¶ Set the state of the task to
ABORTED
.Abortable tasks monitor their state at regular intervals and terminate execution if so.
Be aware that invoking this method does not guarantee when the task will be aborted (or even if the task will be aborted at all).
-
is_aborted
()¶ Returns
True
if the task is (being) aborted.
-
-
class
celery.contrib.abortable.
AbortableTask
¶ A celery task that serves as a base class for all
Task
‘s that support aborting during execution.All subclasses of
AbortableTask
must call theis_aborted()
method periodically and act accordingly when the call evaluates toTrue
.-
classmethod
AsyncResult
(task_id)¶ Returns the accompanying AbortableAsyncResult instance.
-
is_aborted
(**kwargs)¶ Checks against the backend whether this
AbortableAsyncResult
isABORTED
.Always returns
False
in case the task_id parameter refers to a regular (non-abortable)Task
.Be aware that invoking this method will cause a hit in the backend (for example a database query), so find a good balance between calling it regularly (for responsiveness), but not too often (for performance).
-
name
= 'celery.contrib.abortable.AbortableTask'¶
-
classmethod