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\Task;
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 TaskAdapterInterface
30	{
31
32	/**
33	* Schedule job with queue
34	*
35	* @param  Task $task
36	* @return TaskAdapterInterface
37	*/
38	public function schedule(Task $task): TaskAdapterInterface;
39
40	/**
41	* Get scheduled tasks
42	*
43	* @return array
44	*/
45	public function getTasks(): array;
46
47	/**
48	* Get scheduled task
49	*
50	* @param  string $taskId
51	* @return ?Task
52	*/
53	public function getTask(string $taskId): ?Task;
54
55	/**
56	* Get every scheduled task, keyed by task ID.
57	*
58	* Exists so callers that want all of them - Queue::getScheduledTasks(), and
59	* through it every run() on every tick - can ask for them in one go instead
60	* of listing the IDs and then fetching each task individually. That pattern
61	* costs a round trip per scheduled task on every backend that has round
62	* trips, which is the definition of an N+1.
63	*
64	* Any task that can't be loaded (corrupt, tampered, or removed mid-read) is
65	* omitted rather than returned as null, matching what callers already did
66	* with getTask()'s null.
67	*
68	* @return array  taskId => Task
69	*/
70	public function getAllTasks(): array;
71
72	/**
73	* Update scheduled task
74	*
75	* @param  Task $task
76	* @return TaskAdapterInterface
77	*/
78	public function updateTask(Task $task): TaskAdapterInterface;
79
80	/**
81	* Remove scheduled task
82	*
83	* @param  string $taskId
84	* @return TaskAdapterInterface
85	*/
86	public function removeTask(string $taskId): TaskAdapterInterface;
87
88	/**
89	* Get scheduled tasks count
90	*
91	* @return int
92	*/
93	public function getTaskCount(): int;
94
95	/**
96	* Has scheduled tasks
97	*
98	* @return bool
99	*/
100	public function hasTasks(): bool;
101
102	/**
103	* Clear all scheduled task
104	*
105	* @return TaskAdapterInterface
106	*/
107	public function clearTasks(): TaskAdapterInterface;
108
109	/**
110	* Atomically claim a task's current due-window. Returns true if this
111	* call claimed $taskId for $window (no other live claim for that same
112	* window exists); false if another claim for the same window is
113	* already live. A claim for a *different* window from what's
114	* currently stored always succeeds immediately, regardless of the old
115	* claim's expiry - only a same-window re-claim is blocked, and only
116	* until the stored claim's TTL elapses.
117	*
118	* @param  string $taskId
119	* @param  string $window
120	* @return bool
121	*/
122	public function claimTaskRun(string $taskId, string $window): bool;
123
124	}