English

Google App Engine

The Queue Class

The Queue class may be used to prepare Tasks for offline execution by App Engine.

Queue is provided by the google.appengine.api.taskqueue module.

Introduction

A Queue object is instantiated by nam. The name must correspond either to the default queue (provided by the system) or a user-defined queue as specified in the application's queue.yaml. The Queue object may then be used to insert new Task instances for offline execution by App Engine.

Multiple Queue objects may correspond to the same underlying system queue. However, a single Task object may only be added to one Queue.

Constructor

class Queue (name='default')

Instantiates a Queue object which corresponds to either the default queue (automatically available to all applications) or a user-created queue defined in queue.yaml. Once instantiated, a Queue object may be used to insert new Tasks into the system for offline execution.

Arguments:

name:
Optional. The name of this Queue. Must correspond to a user-defined queue name from queue.yaml. Alternatively, if not specified, the Queue instance will correspond to the automatic default queue.

Properties

A Queue instance has the following properties:

name

The name of this Queue, either default (if the default queue) or a user-defined value corresponding to an active queue in queue.yaml.

Instance Methods

A Queue instance has the following methods:

add(task, transactional=False)

Add a Task or a list of Tasks to this Queue.

Arguments:

task

The Task to add, or a list of Task objects to add.

If task is a list of Task objects, all tasks are added to the queue. If transactional=True, then all of the tasks are added in the same active datastore transaction, and if any of the tasks cannot be enqueued, none of the tasks are enqueued and the datastore transaction fails. If transactional=False, a failure to enqueue any task will raise an exception, but other tasks may be enqueued successfully.

transactional=False
Relevant when this method is called inside db.run_in_transaction(). Indicates that this transactional task should be added only if an enclosing datastore transaction is applied successfully. Note that this task must not have a user-specified name in this case.

The return value is the Task or list of tasks that was supplied to this method.

If any Task has already been added to a queue, this method raises a BadTaskStateError.

If transactional=True, but this method is not called during a datastore transaction, is raises a BadTransactionStateError.

If the list of Task objects exceeds the limit for tasks added in a bulk call (see Quotas and Limits), this method raises a TooManyTasksError.

If the list of Task objects contains two tasks with the same name, this method raises a DuplicateTaskNameError.

delete_tasks(task)

Deletes a Task or list of Tasks in this Queue. Task name is the only task attribute used to select tasks for deletion. If there is any task with was_deleted property set to True, or without a task name, a BadTaskStateError is raised immediately.

Arguments:

task
A Task or a list of Tasks to delete from the Queue.
lease_tasks(lease_seconds, max_tasks)

Leases a number of tasks from the Queue for a period of time. This method can only be performed on a pull Queue. Attempts to lease tasks from a push Queue result in a InvalidQueueModeError. All non-pull tasks in the pull Queue will be converted into pull tasks when leased. If fewer than max_tasks are available, all available tasks are returned. The lease_tasks method supports leasing at most 1000 tasks for no longer than a week in a single call.

Arguments:

lease_seconds

Number of seconds to lease this task, up to one week (604,800 seconds). Must be a positive integer.

max_tasks

Maximum number of tasks to lease from the pull Queue, up to 1,000 tasks.

lease_tasks_by_tag(lease_seconds, max_tasks, tag=None)

Leases up to a specified number of tasks from the queue for a specified period of time. If a tag is specified, queries for tasks with that tag. Returns a list of leased tasks.

Note: Applies only to pull queues. Any non-pull tasks will be converted into pull tasks when being leased by tag.

Raises:

InvalidLeaseTimeError
if lease_seconds is not a valid float or integer number, or is outside the value range.
InvalidMaxTasksError
if max_tasks is not a valid integer or is outside the valid range.
InvalidQueueModeError if invoked on a queue that is not a pull queue.
modify_task_lease(lease_seconds, max_tasks)

Modifies the lease of a task in this queue.

Arguments:

task

The task instance whose lease you wish to modify.

lease_seconds

Number of seconds to lease this task, up to one week (604,800 seconds). Must not be negative. Setting lease_seconds to 0 removes the task lease, making the task available for leasing again using lease_tasks().

Raises a TypeError if lease_seconds is not a valid float or integer. Raises an InvalidLeaseTimeError if lease_seconds is outside of the valid range.

purge()
Removes all tasks from this queue. Purging the queue takes about 20 seconds, regardless of the queue size. Tasks continue executing during this time, until the backends recognize that the queue has been purged.