1
0

IJobList.php 4.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171
  1. <?php
  2. /**
  3. * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
  4. * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
  5. * SPDX-License-Identifier: AGPL-3.0-only
  6. */
  7. namespace OCP\BackgroundJob;
  8. /**
  9. * Interface IJobList
  10. *
  11. * This interface provides functions to register background jobs
  12. *
  13. * To create a new background job create a new class that inherits from either
  14. * \OCP\BackgroundJob\Job, \OCP\BackgroundJob\QueuedJob or
  15. * \OCP\BackgroundJob\TimedJob and register it using ->add($job, $argument),
  16. * $argument will be passed to the run() function of the job when the job is
  17. * executed.
  18. *
  19. * A regular job will be executed every time cron.php is run, a QueuedJob will
  20. * only run once and a TimedJob will only run at a specific interval which is to
  21. * be specified in the constructor of the job by calling
  22. * $this->setInterval($interval) with $interval in seconds.
  23. *
  24. * This interface should be used directly and not implemented by an application.
  25. * The implementation is provided by the server.
  26. *
  27. * @since 7.0.0
  28. */
  29. interface IJobList {
  30. /**
  31. * Add a job to the list
  32. *
  33. * @param IJob|class-string<IJob> $job
  34. * @param mixed $argument The argument to be passed to $job->run() when the job is executed
  35. * @since 7.0.0
  36. */
  37. public function add($job, $argument = null): void;
  38. /**
  39. * Add a job to the list but only run it after the given timestamp
  40. *
  41. * For cron background jobs this means the job will likely run shortly after the timestamp
  42. * has been reached. For ajax background jobs the job might only run when users are active
  43. * on the instance again.
  44. *
  45. * @param class-string<IJob> $job
  46. * @param mixed $argument The serializable argument to be passed to $job->run() when the job is executed
  47. * @since 28.0.0
  48. */
  49. public function scheduleAfter(string $job, int $runAfter, $argument = null): void;
  50. /**
  51. * Remove a job from the list
  52. *
  53. * @param IJob|class-string<IJob> $job
  54. * @param mixed $argument
  55. * @since 7.0.0
  56. */
  57. public function remove($job, $argument = null): void;
  58. /**
  59. * Remove a job from the list by id
  60. *
  61. * @param int $id
  62. * @since 30.0.0
  63. */
  64. public function removeById(int $id): void;
  65. /**
  66. * check if a job is in the list
  67. *
  68. * @param IJob|class-string<IJob> $job
  69. * @param mixed $argument
  70. * @since 7.0.0
  71. */
  72. public function has($job, $argument): bool;
  73. /**
  74. * Get jobs matching the search
  75. *
  76. * @param IJob|class-string<IJob>|null $job
  77. * @return array<IJob>
  78. * @since 25.0.0
  79. * @deprecated 26.0.0 Use getJobsIterator instead to avoid duplicated job objects
  80. */
  81. public function getJobs($job, ?int $limit, int $offset): array;
  82. /**
  83. * Get jobs matching the search
  84. *
  85. * @param IJob|class-string<IJob>|null $job
  86. * @return iterable<IJob>
  87. * @since 26.0.0
  88. */
  89. public function getJobsIterator($job, ?int $limit, int $offset): iterable;
  90. /**
  91. * Get the next job in the list
  92. *
  93. * @param bool $onlyTimeSensitive Whether we get only time sensitive jobs or not
  94. * @param class-string<IJob>[]|null $jobClasses List of job classes to restrict which next job we get
  95. * @return ?IJob the next job to run. Beware that this object may be a singleton and may be modified by the next call to buildJob.
  96. * @since 7.0.0 - In 24.0.0 parameter $onlyTimeSensitive got added; In 30.0.0 parameter $jobClasses got added
  97. */
  98. public function getNext(bool $onlyTimeSensitive = false, ?array $jobClasses = null): ?IJob;
  99. /**
  100. * @since 7.0.0
  101. */
  102. public function getById(int $id): ?IJob;
  103. /**
  104. * @since 23.0.0
  105. */
  106. public function getDetailsById(int $id): ?array;
  107. /**
  108. * set the job that was last ran to the current time
  109. *
  110. * @since 7.0.0
  111. */
  112. public function setLastJob(IJob $job): void;
  113. /**
  114. * Remove the reservation for a job
  115. *
  116. * @since 9.1.0
  117. */
  118. public function unlockJob(IJob $job): void;
  119. /**
  120. * set the lastRun of $job to now
  121. *
  122. * @since 7.0.0
  123. */
  124. public function setLastRun(IJob $job): void;
  125. /**
  126. * set the run duration of $job
  127. *
  128. * @since 12.0.0
  129. */
  130. public function setExecutionTime(IJob $job, int $timeTaken): void;
  131. /**
  132. * Reset the $job so it executes on the next trigger
  133. *
  134. * @since 23.0.0
  135. */
  136. public function resetBackgroundJob(IJob $job): void;
  137. /**
  138. * Checks whether a job of the passed class was reserved to run
  139. * in the last 6h
  140. *
  141. * @param string|null $className
  142. * @return bool
  143. * @since 27.0.0
  144. */
  145. public function hasReservedJob(?string $className): bool;
  146. /**
  147. * Returns a count of jobs per Job class
  148. *
  149. * @return list<array{class:class-string, count:int}>
  150. * @since 30.0.0
  151. */
  152. public function countByClass(): array;
  153. }