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

title, source_type, url, archive_url, vendor, related_branches, related_projects, tags, created

title	source_type	url	archive_url	vendor	related_branches	related_projects	tags	created
Spring Framework ThreadPoolTaskExecutor Javadoc (공식 API 문서)	official-doc	https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/scheduling/concurrent/ThreadPoolTaskExecutor.html		Spring (VMware / Broadcom)	feature-background-job-async-contract	ca-skeleton	official-doc ca-skeleton runtime spring-framework thread-pool bounded-queue pool-sizing	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]] (생성 시)