stream / classes / class-scheduler.php

class-scheduler.php in Stream – Activity Log & Audit Trail trunk, at classes/class-scheduler.php

120 lines 4.2 KB

Raw Download Zip

1	<?php
2	/**
3	* Scheduler abstraction for Stream's deferred work.
4	*
5	* Stream defers record purging and large-table resets to a background
6	* scheduler so they do not block admin requests. Historically this was
7	* Action Scheduler (AS) exclusively. This interface decouples the calling
8	* code (Admin, Settings) from the concrete scheduler so the same purge
9	* logic can run either through Action Scheduler or through WP-Cron,
10	* selected at runtime via the `wp_stream_use_action_scheduler` filter.
11	*
12	* Implementations:
13	* - {@see AS_Scheduler} — Action Scheduler (default; bundled dependency).
14	* - {@see Cron_Scheduler} — WP-Cron fallback for hosts with reliable cron
15	* (e.g. Cavalcade) that prefer not to use AS.
16	*
17	* @package WP_Stream
18	*/
19
20	namespace WP_Stream;
21
22	/**
23	* Interface - Scheduler
24	*/
25	interface Scheduler {
26
27	/**
28	* Enqueue a one-off asynchronous action to run as soon as possible.
29	*
30	* Values in $args are passed positionally to the hook callback, in the
31	* order they appear in the array, mirroring Action Scheduler semantics.
32	* How the args are stored is backend-specific: AS keeps the array as
33	* given (preserving Stream's historical behavior and the keyed display
34	* in Tools → Scheduled Actions), while cron stores array_values(). Args
35	* therefore only round-trip through next_scheduled() on the backend
36	* that scheduled them — which is the only supported usage.
37	*
38	* @param string $hook Action hook name.
39	* @param array $args Arguments passed positionally to the callback.
40	* @param string $group Optional grouping label (used by AS; ignored by cron).
41	* @return void
42	*/
43	public function enqueue_async( $hook, $args = array(), $group = '' );
44
45	/**
46	* Schedule a recurring action if one is not already scheduled.
47	*
48	* The "already scheduled" probe may be hook-scoped (ignoring args and
49	* group): the AS backend intentionally checks the hook only, preserving
50	* Stream's historical behavior and preventing recurrences with differing
51	* args from stacking. Callers must treat one recurring action per hook
52	* as the contract; the sole caller schedules with empty args.
53	*
54	* @param int $timestamp First run, as a Unix timestamp.
55	* @param int $interval Recurrence interval in seconds.
56	* @param string $hook Action hook name.
57	* @param array $args Arguments passed positionally to the callback.
58	* @param string $group Optional grouping label (used by AS; ignored by cron).
59	* @return void
60	*/
61	public function schedule_recurring( $timestamp, $interval, $hook, $args = array(), $group = '' );
62
63	/**
64	* Get the next scheduled timestamp for a hook (with matching args).
65	*
66	* @param string $hook Action hook name.
67	* @param array $args Arguments the action was scheduled with.
68	* @return int\|false Unix timestamp of the next run, or false if none.
69	*/
70	public function next_scheduled( $hook, $args = array() );
71
72	/**
73	* Whether any instance of a hook is scheduled, regardless of its args.
74	*
75	* @param string $hook Action hook name.
76	* @return bool
77	*/
78	public function has_scheduled( $hook );
79
80	/**
81	* Whether any of the given hooks is pending or currently in progress.
82	*
83	* Used as the auto-purge overlap guard and to drive the Settings UI
84	* "currently running" notices.
85	*
86	* @param array $hooks Action hook names to probe.
87	* @return bool
88	*/
89	public function any_pending_or_running( $hooks );
90
91	/**
92	* Unschedule every pending instance of a hook.
93	*
94	* @param string $hook Action hook name.
95	* @return void
96	*/
97	public function unschedule_all( $hook );
98
99	/**
100	* Mark a deferred-work context as actively running.
101	*
102	* No-op for schedulers that track in-progress state natively (AS). The
103	* cron fallback uses it to bridge the window between a callback starting
104	* and the next chained event being scheduled, so the overlap guard does
105	* not report "idle" mid-chain.
106	*
107	* @param string $context Short identifier for the running work.
108	* @return void
109	*/
110	public function mark_running( $context );
111
112	/**
113	* Clear the running marker set by {@see Scheduler::mark_running()}.
114	*
115	* @param string $context Short identifier for the running work.
116	* @return void
117	*/
118	public function mark_done( $context );
119	}
120