1	<?php
2	/**
3	* This program is free software; you can redistribute it and/or modify
4	* it under the terms of the GNU General Public License as published by
5	* the Free Software Foundation; either version 2 of the License, or
6	* (at your option) any later version.
7	*
8	* This program is distributed in the hope that it will be useful,
9	* but WITHOUT ANY WARRANTY; without even the implied warranty of
10	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11	* GNU General Public License for more details.
12	*
13	* You should have received a copy of the GNU General Public License along
14	* with this program; if not, write to the Free Software Foundation, Inc.,
15	* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16	* http://www.gnu.org/copyleft/gpl.html
17	*
18	* @file
19	*/
20
21	/**
22	* Job that has a run() method and metadata accessors for JobQueue::pop() and JobQueue::ack().
23	*
24	* Instances are not only enqueueable via JobQueue::push(), but they can also be executed by
25	* calling their run() method. When constructing a job to be enqueued via JobQueue::push(), it
26	* will not be possible to construct a RunnableJob instance if the class for that job is not
27	* loaded by the application for the local DB domain. In that case, the general-purpose
28	* JobSpecification class can be used instead.
29	*
30	* See [the architecture doc](@ref jobqueuearch) for more information.
31	*
32	* @stable to implement
33	* @since 1.33
34	* @ingroup JobQueue
35	*/
36	interface RunnableJob extends IJobSpecification {
37	/** @var int Job must not be wrapped in the usual explicit LBFactory transaction round */
38	public const JOB_NO_EXPLICIT_TRX_ROUND = 1;
39
40	/**
41	* Run the job.
42	*
43	* If this method returns `false` or completes exceptionally, the job runner will retry executing this
44	* job unless the number of retries has exceeded its configured retry limit.
45	* Retries are allowed by default, unless allowRetries() is overridden to disable retries.
46	*
47	* See [the architecture doc](@ref jobqueuearch) for more information.
48	*
49	* @return bool Return `false` to instruct the job runner to retry a failed job.
50	* Otherwise return `true` to indicate that a job completed
51	* (i.e. succeeded, or failed in a way that's deterministic or redundant).
52	*/
53	public function run();
54
55	/**
56	* @param string|null $field Metadata field or null to get all the metadata
57	* @return mixed|null Value; null if missing
58	*/
59	public function getMetadata( $field = null );
60
61	/**
62	* @param string $field Key name to set the value for
63	* @param mixed $value The value to set the field for
64	* @return mixed|null The prior field value; null if missing
65	*/
66	public function setMetadata( $field, $value );
67
68	/**
69	* @param int $flag JOB_* class constant
70	* @return bool
71	* @since 1.31
72	*/
73	public function hasExecutionFlag( $flag );
74
75	/**
76	* @return string|null Id of the request that created this job. Follows
77	*  jobs recursively, allowing to track the id of the request that started a
78	*  job when jobs insert jobs which insert other jobs.
79	* @since 1.27
80	*/
81	public function getRequestId();
82
83	/**
84	* Whether to retry execution of this job if run() returned `false` or threw an exception.
85	*
86	* @warning In some setups (i.e. when using change-propagation) jobs may
87	*  still be retried even when this is false if the job fails due to a
88	*  timeout unless it is also configured in change-prop config (T358939).
89	* @return bool Whether this job can be retried on failure by job runners
90	* @since 1.21
91	*/
92	public function allowRetries();
93
94	/**
95	* @return int Number of actually "work items" handled in this job
96	* @see $wgJobBackoffThrottling
97	* @since 1.23
98	*/
99	public function workItemCount();
100
101	/**
102	* @return int|null UNIX timestamp of when the job was runnable, or null
103	* @since 1.26
104	*/
105	public function getReadyTimestamp();
106
107	/**
108	* Do any final cleanup after run(), deferred updates, and all DB commits happen
109	* @param bool $status Whether the job, its deferred updates, and DB commit all succeeded
110	* @since 1.27
111	*/
112	public function tearDown( $status );
113
114	/**
115	* @return string
116	*/
117	public function getLastError();
118
119	/**
120	* @return string Debugging string describing the job
121	*/
122	public function toString();
123	}