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

- 원본 URL: https://docs.spring.io/spring-boot/reference/features/task-execution-and-scheduling.html
- 아카이브 URL: (미수집)
- 저자 / 조직: Spring Framework / VMware (Broadcom)
- 발행일: 지속 갱신 (현재 서빙 버전: Spring Boot 4.0.6 — API link 기준; 3.x 동일 semantics 적용)
- 마지막 확인일: 2026-05-28

> **버전 주의**: 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 / 관련

- Tomcat virtual thread 설정: (미수집 — Tomcat 공식 문서 또는 Spring Boot embedded container 절)
- SLF4J MDC thread-local 동작: (미수집)
- JEP 444 (Virtual Threads): (미수집)
- [[raw/branch-notes/feature-boundary-validation-mapping-contract]] — 이 자료를 활용하는 branch