1	<?php
2	declare(strict_types=1);
3	/**
4	* Pop PHP Framework (https://www.popphp.org/)
5	*
6	* @link       https://github.com/popphp/popphp-framework
7	* @author     Nick Sagona, III <nick@popphp.org>
8	* @copyright  Copyright (c) 2009-2026 Nick Sagona, III
9	* @license    https://www.popphp.org/license     New BSD License
10	*/
11
12	/**
13	* @namespace
14	*/
15	namespace Pop\Queue\Adapter;
16
17	use Pop\Queue\Process\AbstractJob;
18
19	/**
20	* Adapter interface
21	*
22	* @category   Pop
23	* @package    Pop\Queue
24	* @author     Nick Sagona, III <nick@popphp.org>
25	* @copyright  Copyright (c) 2009-2026 Nick Sagona, III
26	* @license    https://www.popphp.org/license     New BSD License
27	* @version    3.0.0
28	*/
29	interface AdapterInterface
30	{
31
32	public function setPriority(string $priority = 'FIFO'): AdapterInterface;
33
34	public function getPriority(): string;
35
36	public function isFifo(): bool;
37
38	public function isFilo(): bool;
39
40	public function isLilo(): bool;
41
42	public function isLifo(): bool;
43
44	/**
45	* Push a job onto the queue
46	*
47	* @param  AbstractJob $job
48	* @return AdapterInterface
49	*/
50	public function push(AbstractJob $job): AdapterInterface;
51
52	/**
53	* Atomically claim the next eligible job and lease it. Returns null if
54	* nothing is eligible (no pending jobs due, or all reserved jobs have a
55	* live lease).
56	*
57	* @return ?AbstractJob
58	*/
59	public function reserve(): ?AbstractJob;
60
61	/**
62	* Put a reserved job back to pending. $delay overrides the job's own
63	* backoff schedule when given; otherwise release() computes the delay
64	* from $job->getBackoffDelay().
65	*
66	* @param  AbstractJob $job
67	* @param  ?int        $delay
68	* @return AdapterInterface
69	*/
70	public function release(AbstractJob $job, ?int $delay = null): AdapterInterface;
71
72	/**
73	* Permanently remove a job (success/ack)
74	*
75	* @param  AbstractJob $job
76	* @return AdapterInterface
77	*/
78	public function delete(AbstractJob $job): AdapterInterface;
79
80	/**
81	* Move a job to the dead-letter store (terminal)
82	*
83	* @param  AbstractJob $job
84	* @param  ?string     $reason
85	* @return AdapterInterface
86	*/
87	public function bury(AbstractJob $job, ?string $reason = null): AdapterInterface;
88
89	/**
90	* Whether there are pending or reserved jobs
91	*
92	* @return bool
93	*/
94	public function hasJobs(): bool;
95
96	/**
97	* Count of pending + reserved jobs
98	*
99	* @return int
100	*/
101	public function count(): int;
102
103	/**
104	* Clear pending and reserved jobs (not dead-letter jobs)
105	*
106	* @return AdapterInterface
107	*/
108	public function clear(): AdapterInterface;
109
110	public function hasDeadJobs(): bool;
111
112	public function countDead(): int;
113
114	/**
115	* @param  bool $unserialize
116	* @return array
117	*/
118	public function getDeadJobs(bool $unserialize = true): array;
119
120	/**
121	* @param  string $jobId
122	* @param  bool   $unserialize
123	* @return mixed
124	*/
125	public function getDeadJob(string $jobId, bool $unserialize = true): mixed;
126
127	/**
128	* Move a dead-letter job back to pending
129	*
130	* @param  string $jobId
131	* @return AdapterInterface
132	*/
133	public function retryDeadJob(string $jobId): AdapterInterface;
134
135	public function deleteDeadJob(string $jobId): AdapterInterface;
136
137	public function clearDead(): AdapterInterface;
138
139	}