org.sonar.ce.queue.CeQueue Maven / Gradle / Ivy
/*
* SonarQube
* Copyright (C) 2009-2018 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 org.sonar.db.DbSession;
import org.sonar.db.ce.CeQueueDto;
/**
* Queue of pending Compute Engine tasks. Both producer and consumer actions
* are implemented.
*
* This class is decoupled from the regular task type {@link org.sonar.db.ce.CeTaskTypes#REPORT}.
*
*/
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.
*
* Convenience method for calling {@link #submit(CeTaskSubmit, SubmitOption...)} without any {@link SubmitOption}
* and which does not returning an {@link Optional}.
*
* 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.
*
* This method is equivalent to calling {@code massSubmit(Collections.singletonList(submission))}.
*
* @return empty if {@code options} contains {@link SubmitOption#UNIQUE_QUEUE_PER_COMPONENT UNIQUE_QUEUE_PER_COMPONENT}
* and there's already a queued task, otherwise the created task.
*/
Optional submit(CeTaskSubmit submission, SubmitOption... options);
/**
* Submits multiple tasks to the queue at once. All tasks are processed asynchronously.
*
* This method will perform significantly better that calling {@link #submit(CeTaskSubmit, SubmitOption...)} in a loop.
*
*/
List massSubmit(Collection 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();
/**
* 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();
enum SubmitOption {
UNIQUE_QUEUE_PER_COMPONENT
}
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
}
}