86 lines
9.1 KiB
Markdown
86 lines
9.1 KiB
Markdown
---
|
|
title: "Spring ExecutorConfigurationSupport JavaDoc — setWaitForTasksToCompleteOnShutdown / setAwaitTerminationSeconds"
|
|
source_type: official-doc
|
|
url: https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/scheduling/concurrent/ExecutorConfigurationSupport.html
|
|
archive_url:
|
|
related_branches: [feature-background-job-async-contract]
|
|
related_projects: [ca-skeleton]
|
|
tags: [official-doc, ca-skeleton, runtime, spring-framework, graceful-shutdown]
|
|
created: 2026-06-11
|
|
---
|
|
|
|
# Spring ExecutorConfigurationSupport JavaDoc — setWaitForTasksToCompleteOnShutdown / setAwaitTerminationSeconds
|
|
|
|
> Layer: `raw/` — Spring Framework 공식 JavaDoc 원문 발췌·출처 기록.
|
|
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 별도 작성. 원본은 raw에 영구 보관.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-background-job-async-contract]] | D8 — `setWaitForTasksToCompleteOnShutdown(true)` + `setAwaitTerminationSeconds(N)` 조합이 in-flight job 을 컨테이너 종료와 정합시키는 공식 API 라는 근거 (default 는 await 없이 즉시 interrupt) |
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/scheduling/concurrent/ExecutorConfigurationSupport.html
|
|
- 아카이브 URL: (미제공)
|
|
- 저자 / 조직: Spring Framework (VMware / Broadcom)
|
|
- 발행일: Spring Framework 7.0.8 (현재 current 빌드 기준)
|
|
- 마지막 확인일: 2026-06-11
|
|
|
|
## 왜 저장했는지 / Why archived
|
|
|
|
`feature-background-job-async-contract` 브랜치의 D8 결정("graceful shutdown = executor await termination ≤ 19s") 이 `UNSUPPORTED_DECISION` 으로 마킹되어 있었음. `setWaitForTasksToCompleteOnShutdown` 의 default 가 `false`(즉시 interrupt)이고, `setAwaitTerminationSeconds` 로 종료 대기를 활성화해야 in-flight job 이 컨테이너 종료 전에 완료됨을 공식 JavaDoc 으로 증명하기 위해 보관.
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§setWaitForTasksToCompleteOnShutdown] "Set whether to wait for scheduled tasks to complete on shutdown, not interrupting running tasks and executing all tasks in the queue."
|
|
|
|
> [§setWaitForTasksToCompleteOnShutdown] "The default is `false`, with a coordinated lifecycle stop first (unless `\"acceptTasksAfterContextClose\"` has been set) and then an immediate shutdown through interrupting ongoing tasks and clearing the queue. Switch this flag to `true` if you prefer fully completed tasks at the expense of a longer shutdown phase. The executor will not go through a coordinated lifecycle stop phase then but rather only stop and wait for task completion on its own shutdown."
|
|
|
|
> [§setAwaitTerminationSeconds] "Set the maximum number of seconds that this executor is supposed to block on shutdown in order to wait for remaining tasks to complete their execution before the rest of the container continues to shut down. This is particularly useful if your remaining tasks are likely to need access to other resources that are also managed by the container."
|
|
|
|
> [§setAwaitTerminationSeconds] "As a rule of thumb, specify a significantly higher timeout here if you set \"waitForTasksToCompleteOnShutdown\" to `true` at the same time, since all remaining tasks in the queue will still get executed - in contrast to the default shutdown behavior where it's just about waiting for currently executing tasks that aren't reacting to thread interruption."
|
|
|
|
> [§initiateShutdown] "Initiate a shutdown on the underlying ExecutorService, rejecting further task submissions."
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| EXEC-CS-C1 | `setWaitForTasksToCompleteOnShutdown` 의 default 는 `false` — 즉 기본 동작은 ongoing task 를 interrupt 하고 queue 를 clear 하는 즉시 종료 | [§setWaitForTasksToCompleteOnShutdown] "The default is `false`, with a coordinated lifecycle stop first [...] and then an immediate shutdown through interrupting ongoing tasks and clearing the queue." | `official-reference` | Spring Framework 7.x `ExecutorConfigurationSupport` 를 상속하는 모든 executor (ThreadPoolTaskExecutor, ThreadPoolTaskScheduler 등) | 특정 Spring Boot 버전에서 auto-configuration 이 이 값을 override 한다는 것은 증명하지 않음 |
|
|
| EXEC-CS-C2 | `setWaitForTasksToCompleteOnShutdown(true)` 로 설정 시 running task 를 interrupt 하지 않고 queue 의 모든 task 도 실행 완료 후 종료함 | [§setWaitForTasksToCompleteOnShutdown] "Set whether to wait for scheduled tasks to complete on shutdown, not interrupting running tasks and executing all tasks in the queue." | `official-reference` | 위 동일 | 완료 보장 시간 (최대 대기 시간) 을 자동으로 설정하지는 않음 — `setAwaitTerminationSeconds` 로 별도 설정 필요 |
|
|
| EXEC-CS-C3 | `setAwaitTerminationSeconds(N)` 은 컨테이너가 계속 종료되기 전 executor 가 최대 N 초 동안 block 하며 잔여 task 완료를 대기하게 함 | [§setAwaitTerminationSeconds] "Set the maximum number of seconds that this executor is supposed to block on shutdown in order to wait for remaining tasks to complete their execution before the rest of the container continues to shut down." | `official-reference` | 위 동일 | N 초 이내에 task 가 반드시 완료된다는 것은 증명하지 않음 (max 대기) |
|
|
| EXEC-CS-C4 | `waitForTasksToCompleteOnShutdown=true` 일 때는 queue 에 남은 모든 task 도 실행되므로 `awaitTerminationSeconds` 를 "significantly higher" 값으로 설정해야 함 (공식 rule-of-thumb) | [§setAwaitTerminationSeconds] "As a rule of thumb, specify a significantly higher timeout here if you set \"waitForTasksToCompleteOnShutdown\" to `true` at the same time, since all remaining tasks in the queue will still get executed" | `official-reference` | 위 동일 | "significantly higher" 의 정량값을 정의하지 않음 — 도메인 task 실행 시간 측정 후 프로젝트가 결정해야 함 |
|
|
| EXEC-CS-C5 | `initiateShutdown()` 은 추가 task 제출을 거부하지만 non-blocking 이며 기존 task 완료는 허용 — 전체 shutdown 전 early signal 로 사용 | [§initiateShutdown] "Initiate a shutdown on the underlying ExecutorService, rejecting further task submissions." + "This step is non-blocking and can be applied as an early shutdown signal before following up with a full `shutdown()` call later on." | `official-reference` | 위 동일 | `initiateShutdown()` 자체가 task 완료 대기를 보장하지는 않음 — 그것은 `shutdown()` + `awaitTerminationSeconds` 의 역할 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- 이 자료가 직접 증명하는 것:
|
|
- `EXEC-CS-C1`: `setWaitForTasksToCompleteOnShutdown` 의 Spring 공식 default 는 `false` (즉시 interrupt)
|
|
- `EXEC-CS-C2`: `true` 로 설정 시 running task + queued task 모두 interrupt 없이 완료까지 실행
|
|
- `EXEC-CS-C3`: `setAwaitTerminationSeconds` 가 컨테이너 종료 흐름을 block 하는 최대 대기 시간 API 임
|
|
- `EXEC-CS-C4`: `waitForTasksToCompleteOnShutdown=true` 와 함께 사용 시 timeout 을 "significantly higher" 로 설정해야 한다는 공식 rule-of-thumb
|
|
- `EXEC-CS-C5`: `initiateShutdown()` 의 non-blocking 성격과 early signal 용도
|
|
- 이 자료가 증명하지 않는 것:
|
|
- 특정 timeout 값 (예: 19s) 이 최적임을 보장하지 않음 — 도메인 task 실행 시간 기반 결정 필요
|
|
- Spring Boot auto-configuration 이 이 값을 자동으로 설정하는지 여부 (별도 Spring Boot reference 필요)
|
|
- k8s `terminationGracePeriodSeconds` 와 이 timeout 의 관계 — 별도 k8s 공식 doc 인용 필요
|
|
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
|
- ca-tmpl 의 `ThreadPoolTaskExecutor` bean 에 이 두 설정이 실제로 적용되는지 코드 확인 (`actually-implemented` 등급 확보)
|
|
- 19s timeout 의 적합성: background job 의 실제 최대 실행 시간을 측정해 결정해야 함 (현재 `UNSUPPORTED_IMPL_DECISION`)
|
|
- k8s `terminationGracePeriodSeconds=20s` 공식 doc 인용 추가 권고 (D8 의 나머지 근거)
|
|
|
|
## 메모 / Notes
|
|
|
|
- Spring Framework 7.0.8 기준 확인 (2026-06-11 current 빌드). Spring Boot 버전 호환성 별도 확인 권고.
|
|
- `waitForTasksToCompleteOnShutdown=true` 설정 시 coordinated lifecycle stop phase 를 거치지 않고 own shutdown 에서 직렬 처리함 — `acceptTasksAfterContextClose` 와 의미 중복 부분 있음 (JavaDoc 설명 참조).
|
|
- `DEFAULT_PHASE = Integer.MAX_VALUE / 2` — executor 가 일반 SmartLifecycle 보다 늦게 시작하고 일찍 종료하는 이유.
|
|
- 추가로 봐야 할 동일 출처 페이지: `ThreadPoolTaskExecutor` JavaDoc (subclass) + Spring Boot `TaskExecutionAutoConfiguration` source
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc: (k8s `terminationGracePeriodSeconds` 공식 doc — D8 완성에 필요, 미보관)
|
|
- D8 의 나머지 UNSUPPORTED_DECISION 해소를 위해 필요한 자료: k8s Pod lifecycle 공식 doc
|
|
- 이 자료를 인용한 wiki 요약: (생성 시 `[[wiki/concepts/executor-graceful-shutdown]]`)
|