Tasks¶
Async¶
Use async()
from your code to quickly offload tasks to the Cluster
:
from django_q import async, result
# create the task
async('math.copysign', 2, -2)
# or with import and storing the id
import math.copysign
task_id = async(copysign, 2, -2)
# get the result
task_result = result(task_id)
# result returns None if the task has not been executed yet
# so in most cases you will want to use a hook:
async('math.modf', 2.5, hook='hooks.print_result')
# hooks.py
def print_result(task):
print(task.result)
Synchronous testing¶
async()
can be instructed to execute a task immediately by setting the optional keyword sync=True.
The task will then be injected straight into a worker and the result saved by a monitor instance:
from django_q import async, fetch
# create a synchronous task
task_id = async('my.buggy.code', sync=True)
# the task will then be available immediately
task = fetch(task_id)
# and can be examined
if not task.success:
print('An error occurred: {}'.format(task.result))
An error occurred: ImportError("No module named 'my'",)
Note that async()
will block until the task is executed and saved. This feature bypasses the Redis server and is intended for debugging and development.
Connection pooling¶
Django Q tries to pass redis connections around its parts as much as possible to save you from running out of connections.
When you are making individual calls to async()
a lot though, it can help to set up a redis connection to pass to async()
:
# redis connection economy example
from django_q import async
from django_q.conf import redis_client
for i in range(50):
async('math.modf', 2.5, redis=redis_client)
Tip
If you are using django-redis , you can configure Django Q to use its connection pool.
Reference¶
-
async
(func, *args, hook=None, timeout=None, sync=False, redis=None, **kwargs)¶ - Puts a task in the cluster queue
Parameters: - func (object) – The task function to execute
- args – The arguments for the task function
- hook (object) – Optional function to call after execution
- timeout (int) – Overrides global cluster timeout.
- sync (bool) – If set to True, async will simulate a task execution
- redis – Optional redis connection
- kwargs – Keyword arguments for the task function
Returns: The uuid of the task
Return type:
-
result
(task_id)¶ Gets the result of a previously executed task
Parameters: task_id (str) – the uuid or name of the task Returns: The result of the executed task
-
fetch
(task_id)¶ Returns a previously executed task
Parameters: name (str) – the uuid or name of the task Returns: The task Return type: Task Changed in version 0.2.0.
Renamed from get_task
-
class
Task
¶ Database model describing an executed task
-
id
¶
An
uuid.uuid4()
identifier-
name
¶
The name of the task as a humanized version of the
id
Note
This is for convenience and can be used as a parameter for most functions that take a task_id. Keep in mind however that it is not guaranteed to be unique if you store very large amounts of tasks in the database.
-
func
¶
The function or reference that was executed
-
hook
¶
The function to call after execution.
-
args
¶
Positional arguments for the function.
-
kwargs
¶
Keyword arguments for the function.
-
result
¶
The result object. Contains the error if any occur.
-
started
¶
The moment the task was created by an async command
-
stopped
¶
The moment a worker finished this task
-
success
¶
Was the task executed without problems?
-
time_taken
()¶
Calculates the difference in seconds between started and stopped.
Note
Time taken represents the time a task spends in the cluster, this includes any time it may have waited in the queue.
-
classmethod
get_result
(task_id)¶ Get a result directly by task uuid or name
-
-
class
Success
¶ A proxy model of
Task
with the queryset filtered onTask.success
is True.
-
class
Failure
¶ A proxy model of
Task
with the queryset filtered onTask.success
is False.