1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
/*
* SonarQube
* Copyright (C) 2009-2025 SonarSource SA
* mailto:info AT sonarsource DOT com
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 3 of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program; if not, write to the Free Software Foundation,
* Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
package org.sonar.ce.queue;
import java.util.Collection;
import java.util.List;
import java.util.Optional;
import javax.annotation.Nullable;
import org.sonar.ce.task.CeTask;
import org.sonar.db.DbSession;
import org.sonar.db.ce.CeActivityDto;
import org.sonar.db.ce.CeQueueDto;
/**
* Queue of pending Compute Engine tasks. Both producer and consumer actions
* are implemented.
* <p>
* This class is decoupled from the regular task type {@link org.sonar.db.ce.CeTaskTypes#REPORT}.
* </p>
*/
public interface CeQueue {
/**
* Build an instance of {@link CeTaskSubmit} required for {@link #submit(CeTaskSubmit, SubmitOption...)}. It allows
* to enforce that task ids are generated by the queue. It's used also for having access
* to the id before submitting the task to the queue.
*/
CeTaskSubmit.Builder prepareSubmit();
/**
* Submits a task to the queue. The task is processed asynchronously.
* <p>
* Convenience method for calling {@link #submit(CeTaskSubmit, SubmitOption...)} without any {@link SubmitOption}
* and which does not returning an {@link Optional}.
* <p>
* This method is equivalent to calling {@link #massSubmit(Collection, SubmitOption...)} with a singleton list and no
* option.
*/
CeTask submit(CeTaskSubmit submission);
/**
* Submits a task to the queue. The task is processed asynchronously.
* <p>
* This method is equivalent to calling {@code massSubmit(Collections.singletonList(submission))}.
*
* @return empty if {@code options} contains {@link SubmitOption#UNIQUE_QUEUE_PER_ENTITY UNIQUE_QUEUE_PER_MAIN_COMPONENT}
* and there's already a queued task, otherwise the created task.
*/
Optional<CeTask> submit(CeTaskSubmit submission, SubmitOption... options);
/**
* Submits a task to the queue. The task is processed asynchronously.
* <p>
* This method is equivalent to calling {@code massSubmit(Collections.singletonList(submission))}.
*
* @return empty if {@code options} contains {@link SubmitOption#UNIQUE_QUEUE_PER_ENTITY UNIQUE_QUEUE_PER_MAIN_COMPONENT}
* and there's already a queued task, otherwise the created task.
*/
Optional<CeTask> submit(DbSession dbSession, CeTaskSubmit submission, SubmitOption... options);
/**
* Submits multiple tasks to the queue at once. All tasks are processed asynchronously.
* <p>
* This method will perform significantly better that calling {@link #submit(CeTaskSubmit, SubmitOption...)} in a loop.
* </p>
*/
List<CeTask> massSubmit(Collection<CeTaskSubmit> submissions, SubmitOption... options);
/**
* Cancels a task in status {@link org.sonar.db.ce.CeQueueDto.Status#PENDING}. An unchecked
* exception is thrown if the status is not {@link org.sonar.db.ce.CeQueueDto.Status#PENDING}.
*/
void cancel(DbSession dbSession, CeQueueDto ceQueueDto);
/**
* Removes all the tasks from the queue, except the tasks with status
* {@link org.sonar.db.ce.CeQueueDto.Status#IN_PROGRESS} are ignored. They are marked
* as {@link org.sonar.db.ce.CeActivityDto.Status#CANCELED} in past activity.
* This method can be called at runtime, even if workers are being executed.
*
* @return the number of canceled tasks
*/
int cancelAll();
/**
* Mark a task in status {@link org.sonar.db.ce.CeQueueDto.Status#IN_PROGRESS} as failed. An unchecked
* exception is thrown if the status is not {@link org.sonar.db.ce.CeQueueDto.Status#IN_PROGRESS}.
*
* The {@code dbSession} is committed.
* @throws RuntimeException if the task is concurrently removed from the queue
*/
void fail(DbSession dbSession, CeQueueDto ceQueueDto, @Nullable String errorType, @Nullable String errorMessage);
/**
* Requests workers to stop peeking tasks from queue. Does nothing if workers are already paused or being paused.
* The workers that are already processing tasks are not interrupted.
* This method is not restricted to the local workers. All the Compute Engine nodes are paused.
*/
void pauseWorkers();
/**
* Resumes workers so that they can peek tasks from queue.
* This method is not restricted to the local workers. All the Compute Engine nodes are paused.
*/
void resumeWorkers();
WorkersPauseStatus getWorkersPauseStatus();
/**
* Removes all the tasks from the queue, whatever their status. They are marked
* as {@link CeActivityDto.Status#CANCELED} in past activity.
* This method can NOT be called when workers are being executed, as in progress
* tasks can't be killed.
*
* @return the number of canceled tasks
*/
int clear();
enum SubmitOption {
UNIQUE_QUEUE_PER_ENTITY,
UNIQUE_QUEUE_PER_TASK_TYPE
}
enum WorkersPauseStatus {
/**
* Pause triggered but at least one task is still in-progress
*/
PAUSING,
/**
* Paused, no tasks are in-progress. Tasks are pending.
*/
PAUSED,
/**
* Not paused nor pausing
*/
RESUMED
}
}
|
