llm-wiki/raw/official-docs/spring-framework-threadpooltaskexecutor-javadoc.md

---
title: Spring Framework ThreadPoolTaskExecutor Javadoc (공식 API 문서)
source_type: official-doc
url: https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/scheduling/concurrent/ThreadPoolTaskExecutor.html
archive_url:
vendor: Spring (VMware / Broadcom)
related_branches: [feature-background-job-async-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, runtime, spring-framework, thread-pool, bounded-queue, pool-sizing]
created: 2026-06-11
---

# Spring Framework ThreadPoolTaskExecutor Javadoc (공식 API 문서)

> Layer: `raw/official-docs/` — Spring Framework 공식 Javadoc 원문 발췌·출처 기록.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 별도 작성. 원본은 raw에 영구 보관.

## Parent / 활용 branch

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-background-job-async-contract]] | D7 — `ThreadPoolTaskExecutor` 의 default 가 "unlimited queue capacity"(`Integer.MAX_VALUE`) 라는 negative evidence — 본 branch 가 이 default 를 명시적으로 금지(bounded queue 강제)하는 근거. |

## 출처 / Source

- 원본 URL: https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/scheduling/concurrent/ThreadPoolTaskExecutor.html
- 아카이브 URL: (없음 — 공식 Spring 문서 영구 URL)
- 저자 / 조직: Spring Framework (VMware / Broadcom)
- 발행일: Spring Framework 7.0.8 (문서 생성 시점 기준)
- 마지막 확인일: 2026-06-11

## 왜 저장했는지 / Why archived

`ThreadPoolTaskExecutor` 의 default `queueCapacity = Integer.MAX_VALUE` 는 unbounded queue 로 executor saturation 이 발생해도 rejection 이 일어나지 않아 메모리 과적재와 지연 폭발 위험이 있다. `feature-background-job-async-contract` D7 이 "bounded queue 강제 + AbortPolicy default" 를 결정하는 negative evidence (이 default 가 왜 위험한지) 로 사용한다.

## 핵심 인용 / Key quotes (verbatim)

> [§ Class description] "The default configuration is a core pool size of 1, with unlimited max pool size and unlimited queue capacity. This is roughly equivalent to Executors.newSingleThreadExecutor(), sharing a single thread for all tasks."

> [§ setQueueCapacity] "Default is Integer.MAX_VALUE."

> [§ setQueueCapacity] "Any positive value will lead to a LinkedBlockingQueue instance; any other value will lead to a SynchronousQueue instance."

> [§ setTaskDecorator] "The primary use case is to set some execution context around the task's invocation, or to provide some monitoring/statistics for task execution."

> [§ setMaxPoolSize] "Set the ThreadPoolExecutor's maximum pool size. Default is Integer.MAX_VALUE."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| SF-TPTE-C1 | `ThreadPoolTaskExecutor` 의 default queueCapacity 는 `Integer.MAX_VALUE` (unbounded) 이다 | [§ setQueueCapacity] "Default is Integer.MAX_VALUE." | `official-vendor-doc` | Spring Framework `ThreadPoolTaskExecutor` 모든 버전 (7.x 기준) | 이 default 를 그대로 두면 반드시 OOM 이 발생한다는 것은 증명하지 않음 — 트래픽·힙 설정에 따라 다름 |
| SF-TPTE-C2 | queueCapacity 에 양수 값을 설정하면 `LinkedBlockingQueue`, 0 이하면 `SynchronousQueue` 가 생성된다 | [§ setQueueCapacity] "Any positive value will lead to a LinkedBlockingQueue instance; any other value will lead to a SynchronousQueue instance." | `official-vendor-doc` | Spring Framework `ThreadPoolTaskExecutor` | queueCapacity 를 음수로 두는 것이 best practice 임을 증명하지 않음 |
| SF-TPTE-C3 | default maxPoolSize 는 `Integer.MAX_VALUE` (unlimited) 이다 | [§ setMaxPoolSize] "Set the ThreadPoolExecutor's maximum pool size. Default is Integer.MAX_VALUE." | `official-vendor-doc` | Spring Framework `ThreadPoolTaskExecutor` | maxPoolSize 를 낮게 설정해야 한다는 권고를 직접 포함하지 않음 |
| SF-TPTE-C4 | `TaskDecorator` 의 primary use case 는 task 실행 주변에 execution context 를 설정하거나 monitoring/statistics 를 제공하는 것이다 | [§ setTaskDecorator] "The primary use case is to set some execution context around the task's invocation, or to provide some monitoring/statistics for task execution." | `official-vendor-doc` | Spring Framework `ThreadPoolTaskExecutor` 의 `setTaskDecorator` API | MDC 4-key 전파 또는 SecurityContext 전파가 자동으로 동작함을 증명하지 않음 — TaskDecorator 구현체 작성이 별도로 필요 |
| SF-TPTE-C5 | `TaskDecorator` 는 `#submit` 호출 시 예외 전파가 제한된다 — exposed `Runnable` 이 `FutureTask` 여서 예외가 전파되지 않으며 `Future#get` 으로 평가해야 한다 | [§ setTaskDecorator] "In case of #submit calls, the exposed Runnable will be a FutureTask which does not propagate any exceptions; you might have to cast it and call Future#get to evaluate exceptions." | `official-vendor-doc` | Spring Framework `ThreadPoolTaskExecutor` 의 `setTaskDecorator` + `submit()` 조합 | `execute()` 경로의 예외 핸들링 방식에는 해당하지 않음 |

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `SF-TPTE-C1`: `ThreadPoolTaskExecutor` 를 설정 없이 사용하면 queueCapacity 가 `Integer.MAX_VALUE` 임 — D7 의 "bounded queue 강제" 결정의 negative evidence.
  - `SF-TPTE-C2`: queueCapacity 양수 → `LinkedBlockingQueue`, 0 이하 → `SynchronousQueue` 분기 — D7 의 구체 구현 선택(양수 bounded value)의 API 근거.
  - `SF-TPTE-C3`: maxPoolSize default 도 `Integer.MAX_VALUE` — pool size 명시적 설정 없이는 스레드가 무한 생성 가능하다는 negative evidence.
  - `SF-TPTE-C4`: `TaskDecorator` 가 execution context 설정(MDC, SecurityContext 등)에 공식 권고 API 임 — D5 의 "TaskDecorator 1개로 MDC 전파" 결정의 API 근거.
  - `SF-TPTE-C5`: `submit()` 경로에서 `TaskDecorator` 내 예외가 자동 전파되지 않음 — async exception handling 설계 시 `FutureTask` 예외 평가 패턴 명시 필요.
- 이 자료가 증명하지 않는 것:
  - 특정 queueCapacity 수치(예: 200)가 ca-tmpl 부하에 적합하다는 것 — 별도 부하 테스트 필요.
  - AbortPolicy 가 CallerRunsPolicy 보다 낫다는 공식 권고 — JDK `ThreadPoolExecutor` 문서 또는 실측 필요.
  - MDC 4-key 가 `TaskDecorator` 로 caller→worker 정확히 전파됨 — 구현체 + contract test 필요.
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-tmpl 의 실제 `ThreadPoolTaskExecutor` bean 설정이 queueCapacity 를 양수 bounded value 로 설정하는지 코드 검증.
  - Spring Boot `@EnableAsync` + `ThreadPoolTaskExecutorBuilder` 사용 시 default override 방식 확인.

## 메모 / Notes

- Spring Framework 7.0.8 기준 Javadoc 이지만, `queueCapacity Integer.MAX_VALUE` default 는 이전 버전(5.x, 6.x)에서도 동일 — 버전 스코프는 Cluster에서 관리.
- `queueCapacity = 0` → `SynchronousQueue` 패턴은 `Executors.newCachedThreadPool()` 에 상응하지만 maxPoolSize 를 함께 설정하지 않으면 스레드 폭발 위험 — D7 에서 명시적 max 설정 필요.
- `TaskDecorator` exception 제한(`SF-TPTE-C5`)은 `@Async` 메서드에서 `AsyncUncaughtExceptionHandler` 를 따로 등록해야 하는 이유와 연결 — D5 와 연계 검토.

## Related / 관련

- 같은 주제 다른 official-doc: JDK `ThreadPoolExecutor` Javadoc (`java.util.concurrent.ThreadPoolExecutor`) — rejectionHandler 정책 상세 기술
- 이 자료를 인용한 wiki 요약: `[[wiki/concepts/thread-pool-task-executor]]` (생성 시)