If an application intends to use task queues to perform work, the app can include a configuration file to define named queues, or to provide configuration for the default queue. For Java apps, this file is named queue.xml, in the WEB-INF/ directory in the WAR.
A Java app can define task queues using a file named queue.xml, in the app's WEB-INF/ directory in the WAR. If no queue.xml file is provided, the app can still use the default queue returned by QueueFactory.getDefaultQueue().
The following example defines three queues:
|
<queue-entries>
<queue>
<name>default</name>
<rate>1/s</rate>
</queue>
<queue>
<name>mail-queue</name>
<rate>2000/d</rate>
<bucket-size>10</bucket-size>
</queue>
<queue>
<name>background-processing</name>
<rate>5/s</rate>
</queue>
</queue-entries>
The app's queue configuration applies to all versions of the app. If a given version of an app enqueues a task, the queue will use the task handler for that version of the app.
All apps have a default queue, with a rate of 5 tasks per second. You can customize the settings for this queue by defining a queue named default in queue.xml. If you go without configuration, the default queue doesn't show up in the Administration Console until the first time it is used.
An app can only add tasks to queues defined in queue.xml and the default queue. If you upload a new queue.xml file that removes a queue, but that queue still has tasks, the queue is "paused" (its rate is set to 0) but not deleted. You can re-enable the deleted queue by uploading a new queue.xml file with the queue defined.
The queue.xml file is an XML file whose root element is <queue-entries>. This element contains zero or more <queue> elements, one for each named queue.
A <queue> element contains configuration for a queue. It can contain the following elements:
<name>The name of the queue. This is the name you specify when you call QueueFactory.getQueue().
A queue name can contain letters, numbers and hyphens.
<rate>How often tasks are processed on this queue. The value is a number followed by a slash and a unit of time, where the unit is s for seconds, m for minutes, h for hours, or d for days. For example, the value 5/m says tasks will be processed at a rate of 5 times per minute.
If the number is 0 (such as 0/s), the queue is considered "paused," and no tasks are processed.
<bucket-size>Task queues use a "token bucket" algorithm for dequeueing tasks. The bucket size limits how fast the queue is processed when many tasks are in the queue and the rate is high. This allows you to have a high rate so processing starts shortly after a task is enqueued, but still limit resource usage when many tasks are enqueued in a short period of time.
If no <bucket-size> is specified for a queue, the default value is 5.
For more information on the algorithm, see the Wikipedia article on token buckets.
The task queue configuration for the app is updated when you upload the application using appcfg.sh update. You can update just the configuration for an app's task queues without uploading the full application. To upload the queue.xml file, use the appcfg.sh update_queues command:
./appengine-java-sdk/bin/appcfg.sh update_queues myapp/war
See Uploading an and Managing a Java App for more information.