Queue items to allow later processing.

The queue system allows placing items in a queue and processing them later. The system tries to ensure that only one consumer can process an item.

Before a queue can be used it needs to be created by BackdropQueueInterface::createQueue().

Items can be added to the queue by passing an arbitrary data object to BackdropQueueInterface::createItem().

To process an item, call BackdropQueueInterface::claimItem() and specify how long you want to have a lease for working on that item. When finished processing, the item needs to be deleted by calling BackdropQueueInterface::deleteItem(). If the consumer dies, the item will be made available again by the BackdropQueueInterface implementation once the lease expires. Another consumer will then be able to receive it when calling BackdropQueueInterface::claimItem(). Due to this, the processing code should be aware that an item might be handed over for processing more than once.

The $item object used by the BackdropQueueInterface can contain arbitrary metadata depending on the implementation. Systems using the interface should only rely on the data property which will contain the information passed to BackdropQueueInterface::createItem(). The full queue item returned by BackdropQueueInterface::claimItem() needs to be passed to BackdropQueueInterface::deleteItem() once processing is completed.

There are two kinds of queue backends available: reliable, which preserves the order of messages and guarantees that every item will be executed at least once. The non-reliable kind only does a best effort to preserve order in messages and to execute them at least once but there is a small chance that some items get lost. For example, some distributed back-ends like Amazon SQS will be managing jobs for a large set of producers and consumers where a strict FIFO ordering will likely not be preserved. Another example would be an in-memory queue backend which might lose items if it crashes. However, such a backend would be able to deal with significantly more writes than a reliable queue and for many tasks this is more important. Another example is doing Twitter statistics -- the small possibility of losing a few items is insignificant next to power of the queue being able to keep up with writes. As described in the processing section, regardless of the queue being reliable or not, the processing code should be aware that an item might be handed over for processing more than once (because the processing code might time out before it finishes).

File

core/modules/system/system.queue.inc, line 7
Queue functionality.

Classes

Name Locationsort ascending Description
BackdropQueue core/modules/system/system.queue.inc Factory class for interacting with queues.
SystemQueue core/modules/system/system.queue.inc Default queue implementation.
MemoryQueue core/modules/system/system.queue.inc Static queue implementation.

Interfaces

Name Locationsort ascending Description
BackdropQueueInterface core/modules/system/system.queue.inc
BackdropReliableQueueInterface core/modules/system/system.queue.inc Reliable queue interface.