IJobList.php 4.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171
  1. <?php
  2. /**
  3. * @copyright Copyright (c) 2016, ownCloud, Inc.
  4. *
  5. * @author Joas Schilling <coding@schilljs.com>
  6. * @author Morris Jobke <hey@morrisjobke.de>
  7. * @author Noveen Sachdeva <noveen.sachdeva@research.iiit.ac.in>
  8. * @author Robin Appelman <robin@icewind.nl>
  9. * @author Robin McCorkell <robin@mccorkell.me.uk>
  10. * @author Côme Chilliet <come.chilliet@nextcloud.com>
  11. *
  12. * @license AGPL-3.0
  13. *
  14. * This code is free software: you can redistribute it and/or modify
  15. * it under the terms of the GNU Affero General Public License, version 3,
  16. * as published by the Free Software Foundation.
  17. *
  18. * This program is distributed in the hope that it will be useful,
  19. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  21. * GNU Affero General Public License for more details.
  22. *
  23. * You should have received a copy of the GNU Affero General Public License, version 3,
  24. * along with this program. If not, see <http://www.gnu.org/licenses/>
  25. *
  26. */
  27. namespace OCP\BackgroundJob;
  28. /**
  29. * Interface IJobList
  30. *
  31. * This interface provides functions to register background jobs
  32. *
  33. * To create a new background job create a new class that inherits from either
  34. * \OC\BackgroundJob\Job, \OC\BackgroundJob\QueuedJob or
  35. * \OC\BackgroundJob\TimedJob and register it using ->add($job, $argument),
  36. * $argument will be passed to the run() function of the job when the job is
  37. * executed.
  38. *
  39. * A regular job will be executed every time cron.php is run, a QueuedJob will
  40. * only run once and a TimedJob will only run at a specific interval which is to
  41. * be specified in the constructor of the job by calling
  42. * $this->setInterval($interval) with $interval in seconds.
  43. *
  44. * This interface should be used directly and not implemented by an application.
  45. * The implementation is provided by the server.
  46. *
  47. * @since 7.0.0
  48. */
  49. interface IJobList {
  50. /**
  51. * Add a job to the list
  52. *
  53. * @param IJob|class-string<IJob> $job
  54. * @param mixed $argument The argument to be passed to $job->run() when the job is executed
  55. * @since 7.0.0
  56. */
  57. public function add($job, $argument = null): void;
  58. /**
  59. * Add a job to the list but only run it after the given timestamp
  60. *
  61. * For cron background jobs this means the job will likely run shortly after the timestamp
  62. * has been reached. For ajax background jobs the job might only run when users are active
  63. * on the instance again.
  64. *
  65. * @param class-string<IJob> $job
  66. * @param mixed $argument The serializable argument to be passed to $job->run() when the job is executed
  67. * @since 28.0.0
  68. */
  69. public function scheduleAfter(string $job, int $runAfter, $argument = null): void;
  70. /**
  71. * Remove a job from the list
  72. *
  73. * @param IJob|class-string<IJob> $job
  74. * @param mixed $argument
  75. * @since 7.0.0
  76. */
  77. public function remove($job, $argument = null): void;
  78. /**
  79. * check if a job is in the list
  80. *
  81. * @param IJob|class-string<IJob> $job
  82. * @param mixed $argument
  83. * @since 7.0.0
  84. */
  85. public function has($job, $argument): bool;
  86. /**
  87. * Get jobs matching the search
  88. *
  89. * @param IJob|class-string<IJob>|null $job
  90. * @return array<IJob>
  91. * @since 25.0.0
  92. * @deprecated 26.0.0 Use getJobsIterator instead to avoid duplicated job objects
  93. */
  94. public function getJobs($job, ?int $limit, int $offset): array;
  95. /**
  96. * Get jobs matching the search
  97. *
  98. * @param IJob|class-string<IJob>|null $job
  99. * @return iterable<IJob>
  100. * @since 26.0.0
  101. */
  102. public function getJobsIterator($job, ?int $limit, int $offset): iterable;
  103. /**
  104. * get the next job in the list
  105. *
  106. * @since 7.0.0 - In 24.0.0 parameter $onlyTimeSensitive got added
  107. */
  108. public function getNext(bool $onlyTimeSensitive = false): ?IJob;
  109. /**
  110. * @since 7.0.0
  111. */
  112. public function getById(int $id): ?IJob;
  113. /**
  114. * @since 23.0.0
  115. */
  116. public function getDetailsById(int $id): ?array;
  117. /**
  118. * set the job that was last ran to the current time
  119. *
  120. * @since 7.0.0
  121. */
  122. public function setLastJob(IJob $job): void;
  123. /**
  124. * Remove the reservation for a job
  125. *
  126. * @since 9.1.0
  127. */
  128. public function unlockJob(IJob $job): void;
  129. /**
  130. * set the lastRun of $job to now
  131. *
  132. * @since 7.0.0
  133. */
  134. public function setLastRun(IJob $job): void;
  135. /**
  136. * set the run duration of $job
  137. *
  138. * @since 12.0.0
  139. */
  140. public function setExecutionTime(IJob $job, int $timeTaken): void;
  141. /**
  142. * Reset the $job so it executes on the next trigger
  143. *
  144. * @since 23.0.0
  145. */
  146. public function resetBackgroundJob(IJob $job): void;
  147. /**
  148. * Checks whether a job of the passed class was reserved to run
  149. * in the last 6h
  150. *
  151. * @param string|null $className
  152. * @return bool
  153. * @since 27.0.0
  154. */
  155. public function hasReservedJob(?string $className): bool;
  156. }