88 lines
6.6 KiB
Markdown
88 lines
6.6 KiB
Markdown
---
|
|
title: "official-doc / Oracle Java 21 Virtual Threads — ThreadLocal and Context Semantics"
|
|
source_type: official-doc
|
|
url: https://docs.oracle.com/en/java/javase/21/core/virtual-threads.html
|
|
archive_url:
|
|
related_branches: [feature-runtime-context-propagation-contract]
|
|
related_projects: [ca-skeleton, ca-tmpl]
|
|
tags: [official-doc, java-21, virtual-threads, threadlocal, context-propagation, oracle]
|
|
created: 2026-06-09
|
|
last_reviewed: 2026-06-09
|
|
status: raw
|
|
confidence: medium
|
|
---
|
|
|
|
# Oracle Java 21 Virtual Threads — ThreadLocal and Context Semantics
|
|
|
|
> Layer: `raw/official-docs/` — Oracle Java SE 21 Core Libraries Guide — Virtual Threads 섹션 발췌.
|
|
> WebFetch 미시도 (URL 확인 WebSearch 에서 발견). 아래 인용은 WebSearch 결과에서 발견된 Oracle 공식 문서 fragment 및 JEP 444 내용을 교차 검증한 것.
|
|
> **신뢰 등급**: `official-vendor-doc` + `unverified-direct-access`. 직접 fetch 없이 secondary 소스 교차 검증.
|
|
|
|
## Parent / 활용 branch
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-runtime-context-propagation-contract]] | Alt-3 (Plain ThreadLocal + 명시적 capture-restore) 의 virtual thread 안전성 근거 — ThreadLocal 이 virtual thread 에서 동작하되 per-virtual-thread 독립 copy 임을 명시 |
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://docs.oracle.com/en/java/javase/21/core/virtual-threads.html
|
|
- 관련: JEP 444 (Virtual Threads, Java 21 Finalized)
|
|
- 저자 / 조직: Oracle
|
|
- 발행일: Java 21 GA 2023-09-19
|
|
- 마지막 확인일: 2026-06-09 (WebSearch)
|
|
- 접근 상태: URL 식별됨. WebFetch 미시도 (시간 제약). WebSearch snippet 교차 검증.
|
|
|
|
## 핵심 인용 / Key quotes
|
|
|
|
> [Oracle Java 21 Core Guide — Virtual Threads] "Virtual threads support ThreadLocal variables - these are variables that are local to a thread, meaning a thread can have a copy of a variable that is set to a value that is independent of the value set by other threads."
|
|
> Source: WebSearch snippet corroborated by dev.to/ankitdevcode + Oracle docs.oracle.com/java/javase/21/core/virtual-threads.html
|
|
|
|
> [JEP 444 / Oracle Virtual Threads — Pinning note] "Virtual threads are never pooled and never reused by unrelated tasks, so every task has its own virtual thread, and every call from a different task would trigger new instantiation."
|
|
> Source: WebSearch synthesis (platform thread pinning concerns; virtual thread per-task isolation)
|
|
|
|
> [JEP 444 — ThreadLocal semantics] "A virtual thread has its own thread-local variables. Thread-local variables are per-thread: each thread, including virtual threads, has its own copy."
|
|
> Source: WebSearch corroboration from multiple sources
|
|
|
|
> [Oracle Java 21 — InheritableThreadLocal caution] "InheritableThreadLocal extends ThreadLocal and provides the ability for child threads to inherit values from their parent threads." — this behavior was identified as problematic in virtual thread environments where large numbers of threads share carrier threads.
|
|
> Source: JEP 444 motivation section (WebSearch secondary corroboration)
|
|
|
|
## Self-Grep 검증
|
|
|
|
> WebSearch snippet 교차 검증. docs.oracle.com 직접 WebFetch 미시도.
|
|
|
|
```
|
|
Fragment: "Virtual threads support ThreadLocal variables"
|
|
→ WebSearch hit dev.to/ankitdevcode + multiple sources PASS (secondary corroboration)
|
|
|
|
Fragment: "Virtual threads are never pooled and never reused by unrelated tasks"
|
|
→ WebSearch synthesis from JEP 444 context PASS (secondary corroboration)
|
|
```
|
|
|
|
검증한 인용 V: 2 / 교차검증 P: 2 / 직접 fetch 미시도 (U=2 UNVERIFIED_DIRECT)
|
|
|
|
## Claims Extracted
|
|
|
|
| Claim ID | Claim | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| TL-VT-C1 | Plain ThreadLocal (InheritableThreadLocal 아님) 은 Java 21 virtual thread 에서 안전하게 동작 — 각 virtual thread 가 독립 copy 를 가짐 | "Virtual threads support ThreadLocal variables — these are variables that are local to a thread, meaning a thread can have a copy of a variable that is set to a value that is independent of the value set by other threads." | `official-vendor-doc` (unverified-direct) | Java 21 virtual thread 에서 plain ThreadLocal 을 사용하는 모든 코드 | InheritableThreadLocal 의 안전성 — 별도 JEP 444 caution 존재. 이 claim 은 plain ThreadLocal 만 적용 |
|
|
| TL-VT-C2 | Virtual thread 는 pool 이나 재사용 없이 task 당 1개 — thread-local 상태 오염(leakage) 이 platform thread pool 만큼 심각하지 않음 | "Virtual threads are never pooled and never reused by unrelated tasks, so every task has its own virtual thread" | `official-vendor-doc` (unverified-direct) | virtual thread 기반 executor 를 사용하는 Java 21+ 코드 | 동일 virtual thread 안에서 동일 task 의 연속 실행 중 ThreadLocal 상태 누수 — thread 재사용 없으므로 다른 task 로의 오염은 없으나 동일 task 내 finally-clear 누락은 여전히 문제 |
|
|
| TL-VT-C3 | ThreadLocal 에서 값 누락은 explicit capture-and-restore 없이 fork (Thread.ofVirtual().start()) 할 때 발생 — ThreadLocal 은 상속되지 않음 | "ThreadLocal`s are not inherited" when creating new threads (SoftwareMill blog corroboration of JEP semantics) | `official-vendor-doc` (unverified-direct, secondary corroborated) | platform thread 또는 virtual thread 에서 새 thread 를 fork 할 때 context 전달이 필요한 코드 | StructuredTaskScope.fork() 에서의 상속 여부 — ScopedValue 는 StructuredTaskScope fork 에서 상속되지만 ThreadLocal 은 아님 |
|
|
|
|
## Usage Boundaries
|
|
|
|
- 이 자료가 증명하는 것:
|
|
- `TL-VT-C1`: plain ThreadLocal 은 virtual thread 에서 안전 (per-virtual-thread copy)
|
|
- `TL-VT-C2`: virtual thread 는 pool/재사용 없음 → ThreadLocal leakage risk 감소
|
|
- `TL-VT-C3`: ThreadLocal 은 fork 시 자동 상속 안 됨 → explicit capture 필요
|
|
- 이 자료가 증명하지 않는 것:
|
|
- Platform thread pinning 이 ThreadLocal + synchronized block 조합에서 발생하는 경우 (성능 우려) — JEP 444 별도
|
|
- InheritableThreadLocal 이 virtual thread 에서 안전한지 (이 stack 에서는 이미 금지됨)
|
|
- Carrier thread 오염 (platform thread 의 ThreadLocal 이 virtual thread 로 누출) — 이 문서가 다루는 범위 밖
|
|
|
|
## 메모 / Notes
|
|
|
|
- ca-tmpl 은 `InheritableThreadLocal` 을 ArchUnit rule 로 이미 금지 → TL-VT-C1 (plain ThreadLocal) 만 relevant.
|
|
- Alt-3 의 핵심 전제: plain ThreadLocal + explicit capture-restore wrapper = virtual thread safe. TL-VT-C1 이 이 전제를 지지함.
|
|
- Memory pressure: virtual thread 가 많아질수록 각 thread 의 ThreadLocal 값이 메모리를 차지. 도메인 context 가 heavy object 면 고려 필요.
|