ParallelTaskRunner.kt
/*
Copyright (C) 2026 Sber
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
In any derivative products, you must retain the information of
owner of the original code and provide clear attribution to the project
https://dochub.info
The use of this product or its derivatives for any purpose cannot be a secret.
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Maintainers:
Sergeev Viktor <sergeevviktor017@gmail.com>, Sber - 2026
Contributors:
Sergeev Viktor <sergeevviktor017@gmail.com>, Sber - 2026
*/
package org.archtool.fileloader2.service.concurrent
import io.micrometer.context.ContextExecutorService
import io.micrometer.context.ContextSnapshotFactory
import jakarta.annotation.PreDestroy
import java.util.concurrent.ExecutionException
import java.util.concurrent.ExecutorCompletionService
import java.util.concurrent.ExecutorService
import java.util.concurrent.Future
import java.util.concurrent.LinkedBlockingQueue
import java.util.concurrent.RejectedExecutionException
import java.util.concurrent.ThreadPoolExecutor
import java.util.concurrent.TimeUnit
import org.archtool.fileloader2.configuration.properties.UploadProperties
import org.archtool.fileloader2.exception.ServiceOverloadedException
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.stereotype.Component
/**
* Параллельное выполнение набора задач с остановкой на первой ошибке.
*
* Задачи выполняются в общем для всех запросов пуле записи в S3. Результаты собираются через [ExecutorCompletionService] -
* очередь завершённых задач в порядке завершения, а не отправки. Поэтому об ошибке любой задачи становится известно
* сразу, а не после завершения задач, отправленных раньше: например, долгая запись большого файла не задерживает
* реакцию на быстро упавшую запись маленького.
*
* @param executor пул выполнения задач; задаётся явно только в тестах, в сервисе пул создаёт вторичный конструктор
*/
@Component
class ParallelTaskRunner(
private val executor: ExecutorService,
) {
/**
* Создаёт пул фиксированного размера с ограниченной очередью: если все потоки заняты, задачи ждут в очереди,
* а при её переполнении новые задачи отклоняются (RejectedExecutionException). Контекст запроса (трассировка)
* переносится в потоки пула, чтобы traceId был в журнале задач.
*
* @param uploadProperties настройки с размером пула и очереди (seaf.fileloader.upload.s3-write-*)
*/
@Autowired
constructor(uploadProperties: UploadProperties) :
this(createExecutor(uploadProperties.s3WritePoolSize, uploadProperties.s3WriteQueueCapacity))
/**
* Останавливает пул при остановке сервиса, прерывая выполняющиеся задачи.
*/
@PreDestroy
fun shutdown() {
executor.shutdownNow()
}
/**
* Выполняет задачи и ждёт завершения всех. Одна задача выполняется в вызывающем потоке, без пула.
* При любом выходе из метода, кроме успешного, уже отправленные задачи отменяются (выполняющиеся прерываются):
* при ошибке задачи, прерывании ожидания, отказе пула принять задачу и любой другой ошибке.
*
* @param tasks задачи; порядок выполнения не гарантируется
* @throws Throwable ошибка первой упавшей задачи, как её выбросила задача
* @throws InterruptedException вызывающий поток прерван во время ожидания; флаг прерывания восстановлен
* @throws ServiceOverloadedException пул не принял задачу: очередь переполнена или сервис останавливается
*/
fun runAll(tasks: List<() -> Unit>) {
if (tasks.size == 1) {
tasks.single().invoke()
return
}
val completionService = ExecutorCompletionService<Unit>(executor)
val futures = mutableListOf<Future<Unit>>()
try {
tasks.forEach { task -> futures.add(submit(completionService, task)) }
repeat(futures.size) { completionService.take().get() }
} catch (e: ExecutionException) {
throw e.cause ?: e
} catch (e: InterruptedException) {
Thread.currentThread().interrupt()
throw e
} finally {
// после успешного завершения все задачи выполнены, и отмена для них ничего не делает
cancelAll(futures)
}
}
/**
* Отправляет задачу в пул. Отказ пула оборачивается в [ServiceOverloadedException] здесь, а не выше: так отказ
* пула не спутать с RejectedExecutionException, выброшенным самой задачей.
*
* @param completionService сервис выполнения поверх пула
* @param task задача
* @return отправленная задача
* @throws ServiceOverloadedException пул не принял задачу
*/
private fun submit(completionService: ExecutorCompletionService<Unit>, task: () -> Unit): Future<Unit> {
try {
return completionService.submit { task() }
} catch (e: RejectedExecutionException) {
throw ServiceOverloadedException("Пул записи в S3 не принял задачу: ${e.message}", e)
}
}
/**
* Отменяет задачи, прерывая выполняющиеся. Завершённые задачи не затрагиваются.
*
* @param futures задачи
*/
private fun cancelAll(futures: List<Future<Unit>>) {
futures.forEach { it.cancel(true) }
}
companion object {
private const val THREAD_NAME_PREFIX = "s3-upload-"
/**
* @param poolSize число потоков
* @param queueCapacity сколько задач может ждать свободного потока
* @return пул с потоками s3-upload-N, переносящий контекст вызывающего потока в задачи
*/
private fun createExecutor(poolSize: Int, queueCapacity: Int): ExecutorService {
val threadFactory = Thread.ofPlatform().name(THREAD_NAME_PREFIX, 1).daemon(true).factory()
// AbortPolicy по умолчанию: при переполнении очереди submit выбрасывает RejectedExecutionException
val executor = ThreadPoolExecutor(
poolSize, poolSize,
0L, TimeUnit.MILLISECONDS,
LinkedBlockingQueue(queueCapacity),
threadFactory,
)
val snapshotFactory = ContextSnapshotFactory.builder().build()
return ContextExecutorService.wrap(executor) { snapshotFactory.captureAll() }
}
}
}