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	* @stable to implement
31	* @since 1.33
32	* @ingroup JobQueue
33	*/
34	interface RunnableJob extends IJobSpecification {
35	/** @var int Job must not be wrapped in the usual explicit LBFactory transaction round */
36	public const JOB_NO_EXPLICIT_TRX_ROUND = 1;
37
38	/**
39	* Run the job
40	* @return bool Success
41	*/
42	public function run();
43
44	/**
45	* @param string|null $field Metadata field or null to get all the metadata
46	* @return mixed|null Value; null if missing
47	*/
48	public function getMetadata( $field = null );
49
50	/**
51	* @param string $field Key name to set the value for
52	* @param mixed $value The value to set the field for
53	* @return mixed|null The prior field value; null if missing
54	*/
55	public function setMetadata( $field, $value );
56
57	/**
58	* @param int $flag JOB_* class constant
59	* @return bool
60	* @since 1.31
61	*/
62	public function hasExecutionFlag( $flag );
63
64	/**
65	* @return string|null Id of the request that created this job. Follows
66	*  jobs recursively, allowing to track the id of the request that started a
67	*  job when jobs insert jobs which insert other jobs.
68	* @since 1.27
69	*/
70	public function getRequestId();
71
72	/**
73	* @warning In some setups (i.e. when using change-propagation) jobs may
74	*  still be retried even when this is false if the job fails due to a
75	*  timeout unless it is also configured in change-prop config (T358939).
76	* @return bool Whether this job can be retried on failure by job runners
77	* @since 1.21
78	*/
79	public function allowRetries();
80
81	/**
82	* @return int Number of actually "work items" handled in this job
83	* @see $wgJobBackoffThrottling
84	* @since 1.23
85	*/
86	public function workItemCount();
87
88	/**
89	* @return int|null UNIX timestamp of when the job was runnable, or null
90	* @since 1.26
91	*/
92	public function getReadyTimestamp();
93
94	/**
95	* Do any final cleanup after run(), deferred updates, and all DB commits happen
96	* @param bool $status Whether the job, its deferred updates, and DB commit all succeeded
97	* @since 1.27
98	*/
99	public function tearDown( $status );
100
101	/**
102	* @return string
103	*/
104	public function getLastError();
105
106	/**
107	* @return string Debugging string describing the job
108	*/
109	public function toString();
110	}