donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
6c53ded9cb70f2d7cf3e66ff50d42f2d151c98b1
llm-wiki/vault/20-evidence/official-docs/runtime-spring-boot-virtual-threads.md
T

10 KiB
Raw Blame History

title, source_type, url, archive_url, related_branches, related_projects, tags, created, last_reviewed, status, confidence
title source_type url archive_url related_branches related_projects tags created last_reviewed status confidence
official-doc / Spring Boot Reference — Virtual Threads (Task Execution & Scheduling) official-doc https://docs.spring.io/spring-boot/reference/features/task-execution-and-scheduling.html
feature-boundary-validation-mapping-contract
ca-tmpl
ca-skeleton
official-doc
ca-tmpl
runtime
spring-boot
java-21
virtual-threads
thread-local
2026-05-28 2026-05-28 raw high

Spring Boot Reference — Virtual Threads (Task Execution & Scheduling)

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/에 source-summary-template 형식으로 별도 작성. 원본은 raw에 영구 보관.

Parent / 활용 branch

이 자료는 혼자 존재하지 않는다. filter/interceptor request context propagation (B6 블라인드) 결정의 근거.

Branch 이 자료가 정당화하는 결정
raw/branch-notes/feature-boundary-validation-mapping-contract filter/interceptor 의 request context propagation 이 Java 21 virtual thread 환경에서 ThreadLocal 기반 (RequestContextHolder, MDC) 으로 안전한지 결정 (블라인드 B6). Spring Boot spring.threads.virtual.enabled semantics + 권고 사항 근거

출처 / Source

버전 주의: WebFetch 결과 API 링크가 spring-boot/4.0.6/api/ 를 가리킴. URL /reference/features/ 는 latest 버전을 서빙. Spring Boot 3.2 에서 virtual threads 지원이 도입되었고 동일 property(spring.threads.virtual.enabled) 가 사용됨. 3.x 버전 동작 확인이 필요한 경우 https://docs.spring.io/spring-boot/docs/3.x.x/reference/htmlsingle/#features.task-execution-and-scheduling 를 별도 확인할 것.

왜 저장했는지 / Why archived

feature-boundary-validation-mapping-contract branch 의 B6 블라인드: filter/interceptor 가 RequestContextHolder + MDC (모두 ThreadLocal 기반) 로 request context 를 전파하는 설계가 spring.threads.virtual.enabled=true 환경에서 안전한지 확인하기 위해 보관. Spring Boot 공식 레퍼런스가 virtual thread 활성화 시 어떤 컴포넌트가 전환되는지, pooling 정책이 어떻게 바뀌는지에 대한 normative 진술을 제공함.

핵심 인용 / Key quotes (verbatim, 3~5개)

아래 인용은 WebFetch 로 3회 독립 호출 시 일관되게 반환된 텍스트를 기록. Self-Grep 통과 여부는 ## Self-Grep 검증 섹션 참조.

[§Task Execution — AsyncTaskExecutor auto-config] "When virtual threads are enabled (using Java 21+ and spring.threads.virtual.enabled set to true) this will be a SimpleAsyncTaskExecutor that uses virtual threads."

[§Task Execution — AsyncTaskExecutor auto-config] (동일 문단 연속) "Otherwise, it will be a ThreadPoolTaskExecutor with sensible defaults."

[§Task Scheduling — Scheduler auto-config] "If virtual threads are enabled (using Java 21+ and spring.threads.virtual.enabled set to true) this will be a SimpleAsyncTaskScheduler that uses virtual threads. This SimpleAsyncTaskScheduler will ignore any pooling related properties."

[§Builders — auto-config] "The SimpleAsyncTaskExecutorBuilder and SimpleAsyncTaskSchedulerBuilder beans are auto-configured to use virtual threads if they are enabled (using Java 21+ and spring.threads.virtual.enabled set to true)."

Self-Grep 검증

검증 대상 파일: /tmp/source-fetch-spring-vt.txt (WebFetch 결과를 Write 도구로 기록한 파일) grep 명령 결과:

grep -nF -- "When virtual threads are enabled (using Java 21+ and"
→ line 1: 일치 (PASS)

grep -nF -- "If virtual threads are enabled (using Java 21+ and"
→ line 3: 일치 (PASS)

grep -nF -- "will ignore any pooling related properties"
→ line 5: 일치 (PASS)

grep -nF -- "beans are auto-configured to use virtual threads if they are enabled (using Java 21+ and"
→ line 7: 일치 (PASS)

검증한 인용 V: 4 / 일치 P: 4 / 폐기 D: 0 / 정정 C: 0

Claims Extracted / 추출된 주장

이 자료가 직접 말하는 것만 claim 으로 분리. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.

Claim ID Claim (이 자료가 직접 말하는 것) Evidence quote Strength Applies to Does not prove
SPRING-VT-C1 spring.threads.virtual.enabled=true + Java 21+ 조건을 만족할 때 Spring Boot 의 auto-configured AsyncTaskExecutor 는 SimpleAsyncTaskExecutor (virtual thread 기반) 로 전환된다 [§Task Execution] "When virtual threads are enabled (using Java 21+ and spring.threads.virtual.enabled set to true) this will be a SimpleAsyncTaskExecutor that uses virtual threads." official-vendor-doc Spring Boot 의 auto-configured executor — @EnableAsync, Spring MVC async, WebFlux blocking, WebSocket, JPA bootstrap 등 Tomcat 요청 처리 스레드 모델의 전환을 직접 언급하지 않음; filter/interceptor thread context propagation 안전성을 직접 보장하지 않음
SPRING-VT-C2 virtual threads 비활성화 시 기본값은 ThreadPoolTaskExecutor (sensible defaults) [§Task Execution] "Otherwise, it will be a ThreadPoolTaskExecutor with sensible defaults." official-vendor-doc spring.threads.virtual.enabled 미설정 또는 false 인 모든 Spring Boot 앱 ThreadPoolTaskExecutor 의 기본 pool size, queue capacity 값은 이 인용으로 결정되지 않음
SPRING-VT-C3 virtual threads 활성화 시 auto-configured task scheduler 는 SimpleAsyncTaskScheduler 로 전환되며 pooling 관련 속성을 무시한다 [§Task Scheduling] "If virtual threads are enabled (using Java 21+ and spring.threads.virtual.enabled set to true) this will be a SimpleAsyncTaskScheduler that uses virtual threads. This SimpleAsyncTaskScheduler will ignore any pooling related properties." official-vendor-doc @EnableScheduling + Spring Boot auto-configured scheduler executor (task execution) 와 scheduler (task scheduling) 는 별개 bean; 이 claim 은 scheduler 에만 적용됨
SPRING-VT-C4 SimpleAsyncTaskExecutorBuilder 와 SimpleAsyncTaskSchedulerBuilder 빌더 bean 도 virtual threads 가 활성화되면 자동으로 virtual thread 사용으로 설정된다 [§Builders] "The SimpleAsyncTaskExecutorBuilder and SimpleAsyncTaskSchedulerBuilder beans are auto-configured to use virtual threads if they are enabled (using Java 21+ and spring.threads.virtual.enabled set to true)." official-vendor-doc 빌더 bean 을 통해 custom executor/scheduler 를 생성하는 경우 빌더로 생성한 executor 에서 ThreadLocal 전파가 안전한지는 이 문서가 직접 다루지 않음

Usage Boundaries / 적용 경계

  • 이 자료가 직접 증명하는 것:
    • SPRING-VT-C1: Spring Boot auto-config executor 가 spring.threads.virtual.enabled=true + Java 21+ 일 때 SimpleAsyncTaskExecutor (virtual thread) 로 전환됨
    • SPRING-VT-C2: 기본(비활성화) 상태는 ThreadPoolTaskExecutor with sensible defaults
    • SPRING-VT-C3: auto-config scheduler 도 동일 조건에서 SimpleAsyncTaskScheduler 로 전환, pooling 속성 무시
    • SPRING-VT-C4: builder bean 도 동일 조건에서 virtual thread 사용으로 auto-config
  • 이 자료가 증명하지 않는 것:
    • Tomcat 요청 처리 스레드 (servlet request thread) 가 virtual thread 로 전환되는지 여부 — 이 페이지는 task executor/scheduler 에만 집중하며 Tomcat embedded container 설정은 다루지 않음
    • ThreadLocal (including RequestContextHolder, MDC) 전파 안전성 — virtual thread 와 ThreadLocal 의 관계는 이 문서에서 직접 다루지 않음
    • spring.threads.virtual.enabled=true 설정이 filter/interceptor 의 context propagation 에 영향을 주는지
    • pinning (synchronized block 이나 native call 로 인한 carrier thread 고정) 주의사항
    • InheritableThreadLocal 동작 변화
  • 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
    • ca-tmpl 에서 spring.threads.virtual.enabled 를 실제로 활성화할 경우 Tomcat connector 가 virtual thread 를 사용하는지 별도 공식 문서 확인 필요 (Spring Boot embedded Tomcat virtual thread 설정 페이지)
    • MDC / RequestContextHolder 의 virtual thread 안전성은 SLF4J MDC 문서 또는 Spring Framework Context Propagation 문서에서 별도 확인 필요
    • Java 21 ThreadLocal semantics (일반 ThreadLocal 은 virtual thread 에서도 동작하지만 per-carrier pinning 위험이 있음) — JEP 444 / JEP 453 문서 필요

메모 / Notes

  • 이 페이지는 task execution + scheduling 에 집중. Tomcat virtual thread 지원은 Spring Boot Reference 의 embedded container 설정 섹션 (Customizing Embedded Servlet Containers 또는 Tomcat 관련 절) 에서 별도 다룰 가능성 있음.
  • spring.threads.virtual.enabled 는 Spring Boot 3.2 에서 도입. 3.2 미만 버전에서는 이 property 자체가 존재하지 않음.
  • SimpleAsyncTaskExecutor 는 thread pool 을 사용하지 않고 매 task 마다 새 thread 를 생성하는 executor. virtual thread 모드에서는 이 overhead 가 minimal 하므로 pooling 이 불필요.
  • D9 (filter/interceptor context propagation) 의 UNSUPPORTED_DECISION 을 부분적으로 해소하려면 이 자료만으로는 부족. ThreadLocal / MDC propagation 관련 normative 출처 추가 필요.

Related / 관련

Reference in New Issue View Git Blame Copy Permalink