Chris@0
|
1 <?php
|
Chris@0
|
2
|
Chris@0
|
3 namespace Drupal\Core\Queue;
|
Chris@0
|
4
|
Chris@0
|
5 /**
|
Chris@0
|
6 * Interface for a queue.
|
Chris@0
|
7 *
|
Chris@0
|
8 * Classes implementing this interface will do a best effort to preserve order
|
Chris@0
|
9 * in messages and to execute them at least once.
|
Chris@0
|
10 *
|
Chris@0
|
11 * @ingroup queue
|
Chris@0
|
12 */
|
Chris@0
|
13 interface QueueInterface {
|
Chris@0
|
14
|
Chris@0
|
15 /**
|
Chris@0
|
16 * Adds a queue item and store it directly to the queue.
|
Chris@0
|
17 *
|
Chris@0
|
18 * @param $data
|
Chris@0
|
19 * Arbitrary data to be associated with the new task in the queue.
|
Chris@0
|
20 *
|
Chris@0
|
21 * @return
|
Chris@0
|
22 * A unique ID if the item was successfully created and was (best effort)
|
Chris@0
|
23 * added to the queue, otherwise FALSE. We don't guarantee the item was
|
Chris@0
|
24 * committed to disk etc, but as far as we know, the item is now in the
|
Chris@0
|
25 * queue.
|
Chris@0
|
26 */
|
Chris@0
|
27 public function createItem($data);
|
Chris@0
|
28
|
Chris@0
|
29 /**
|
Chris@0
|
30 * Retrieves the number of items in the queue.
|
Chris@0
|
31 *
|
Chris@0
|
32 * This is intended to provide a "best guess" count of the number of items in
|
Chris@0
|
33 * the queue. Depending on the implementation and the setup, the accuracy of
|
Chris@0
|
34 * the results of this function may vary.
|
Chris@0
|
35 *
|
Chris@0
|
36 * e.g. On a busy system with a large number of consumers and items, the
|
Chris@0
|
37 * result might only be valid for a fraction of a second and not provide an
|
Chris@0
|
38 * accurate representation.
|
Chris@0
|
39 *
|
Chris@17
|
40 * @return int
|
Chris@0
|
41 * An integer estimate of the number of items in the queue.
|
Chris@0
|
42 */
|
Chris@0
|
43 public function numberOfItems();
|
Chris@0
|
44
|
Chris@0
|
45 /**
|
Chris@0
|
46 * Claims an item in the queue for processing.
|
Chris@0
|
47 *
|
Chris@0
|
48 * @param $lease_time
|
Chris@0
|
49 * How long the processing is expected to take in seconds, defaults to an
|
Chris@0
|
50 * hour. After this lease expires, the item will be reset and another
|
Chris@0
|
51 * consumer can claim the item. For idempotent tasks (which can be run
|
Chris@0
|
52 * multiple times without side effects), shorter lease times would result
|
Chris@0
|
53 * in lower latency in case a consumer fails. For tasks that should not be
|
Chris@0
|
54 * run more than once (non-idempotent), a larger lease time will make it
|
Chris@0
|
55 * more rare for a given task to run multiple times in cases of failure,
|
Chris@0
|
56 * at the cost of higher latency.
|
Chris@0
|
57 *
|
Chris@0
|
58 * @return
|
Chris@0
|
59 * On success we return an item object. If the queue is unable to claim an
|
Chris@0
|
60 * item it returns false. This implies a best effort to retrieve an item
|
Chris@0
|
61 * and either the queue is empty or there is some other non-recoverable
|
Chris@0
|
62 * problem.
|
Chris@0
|
63 *
|
Chris@0
|
64 * If returned, the object will have at least the following properties:
|
Chris@0
|
65 * - data: the same as what what passed into createItem().
|
Chris@0
|
66 * - item_id: the unique ID returned from createItem().
|
Chris@0
|
67 * - created: timestamp when the item was put into the queue.
|
Chris@0
|
68 */
|
Chris@0
|
69 public function claimItem($lease_time = 3600);
|
Chris@0
|
70
|
Chris@0
|
71 /**
|
Chris@0
|
72 * Deletes a finished item from the queue.
|
Chris@0
|
73 *
|
Chris@0
|
74 * @param $item
|
Chris@0
|
75 * The item returned by \Drupal\Core\Queue\QueueInterface::claimItem().
|
Chris@0
|
76 */
|
Chris@0
|
77 public function deleteItem($item);
|
Chris@0
|
78
|
Chris@0
|
79 /**
|
Chris@0
|
80 * Releases an item that the worker could not process.
|
Chris@0
|
81 *
|
Chris@0
|
82 * Another worker can come in and process it before the timeout expires.
|
Chris@0
|
83 *
|
Chris@0
|
84 * @param $item
|
Chris@0
|
85 * The item returned by \Drupal\Core\Queue\QueueInterface::claimItem().
|
Chris@0
|
86 *
|
Chris@0
|
87 * @return bool
|
Chris@0
|
88 * TRUE if the item has been released, FALSE otherwise.
|
Chris@0
|
89 */
|
Chris@0
|
90 public function releaseItem($item);
|
Chris@0
|
91
|
Chris@0
|
92 /**
|
Chris@0
|
93 * Creates a queue.
|
Chris@0
|
94 *
|
Chris@0
|
95 * Called during installation and should be used to perform any necessary
|
Chris@0
|
96 * initialization operations. This should not be confused with the
|
Chris@0
|
97 * constructor for these objects, which is called every time an object is
|
Chris@0
|
98 * instantiated to operate on a queue. This operation is only needed the
|
Chris@0
|
99 * first time a given queue is going to be initialized (for example, to make
|
Chris@0
|
100 * a new database table or directory to hold tasks for the queue -- it
|
Chris@0
|
101 * depends on the queue implementation if this is necessary at all).
|
Chris@0
|
102 */
|
Chris@0
|
103 public function createQueue();
|
Chris@0
|
104
|
Chris@0
|
105 /**
|
Chris@0
|
106 * Deletes a queue and every item in the queue.
|
Chris@0
|
107 */
|
Chris@0
|
108 public function deleteQueue();
|
Chris@0
|
109
|
Chris@0
|
110 }
|