ThreadLocal và ScopedValue: per-thread state không leak trên pool

TL;DR: Đôi khi ta cần thứ vừa "toàn cục trong tầm với của code" vừa riêng cho mỗi thread — điều ad-hoc và stack confinement (giam trong phạm vi hẹp) không cho được. ThreadLocal là cơ chế chính thức: mỗi thread một bản riêng, lưu trong ThreadLocalMap của chính object Thread, nên get/set đơn luồng không cần đồng bộ hóa. Nhưng trên thread pool — nơi thread không bao giờ chết — quên gọi remove() là rò cả dữ liệu (request sau thấy ngữ cảnh request trước) lẫn bộ nhớ (value bị strong reference giữ vô hạn). Kỷ luật là remove() trong finally. ScopedValue (final Java 25, preview ở Java 21) đóng lỗ hổng đó bằng thiết kế: ràng giá trị vào một phạm vi where(...).run(...), immutable, tự unbound khi khối kết thúc — không có API để quên dọn.

Bài trước giam dữ liệu trong phạm vi hẹp: một thread, một stack frame. Nhưng có nhu cầu ngược: một giá trị cần với tới từ khắp nơi trong code (như biến toàn cục) nhưng vẫn riêng mỗi thread — correlation ID cho log, user đã xác thực, một SimpleDateFormat không thread-safe. Bài này đi nốt trục confinement: ThreadLocal, cái bẫy rò rỉ kinh điển của nó trên thread pool, và ScopedValue — phiên bản hiện đại vá đúng cái bẫy đó.

1. ThreadLocal: mỗi thread một ngăn tủ riêng

ThreadLocal là cơ chế chính thức cho per-thread state: hình dung nó như cái tủ nhiều ngăn giữa văn phòng, mỗi thread một ngăn mang tên mình, và thread A gọi get luôn nhận đúng giá trị chính A đã set.

Use case kinh điển là per-thread context: thứ không thread-safe nhưng tiện khi dùng như biến toàn cục suốt vòng đời của một thread. Ví dụ sách giáo khoa là SimpleDateFormat — thay vì khóa nó, ta phát cho mỗi thread một bản riêng:

public final class TicketDateFormat {
    private static final ThreadLocal<DateFormat> FORMAT =
        ThreadLocal.withInitial(() -> new SimpleDateFormat("yyyy-MM-dd"));
    public static String format(Date date) {
        return FORMAT.get().format(date);   // moi thread dung SimpleDateFormat cua rieng no
    }
}

withInitial khai báo cách tạo giá trị ban đầu: lần đầu thread gọi get, lambda dựng riêng cho nó một SimpleDateFormat. Hai thread không bao giờ chạm cùng một formatter, nên cái không thread-safe trở nên an toàn mà không tốn khóa. Use case phổ biến khác trên server là giữ ngữ cảnh request — correlation ID cho log, user đã xác thực, hay một JDBC Connection (kết nối database, không thread-safe nên mỗi thread giữ một cái riêng) — cho tầng code sâu đọc mà không phải kéo qua từng tham số method.

2. ThreadLocal.get() tra cứu ở đâu, vì sao không cần đồng bộ hóa?

Trực giác dễ tưởng ThreadLocal là map từ thread sang giá trị, nằm trong object ThreadLocal. Thực tế ngược lại: dữ liệu nằm trong chính object Thread. Mỗi Thread mang field threadLocals kiểu ThreadLocal.ThreadLocalMap — hash map tí hon của riêng nó, key là các object ThreadLocal nó từng dùng. FORMAT.get() thực chất là mở threadLocals của Thread.currentThread() rồi tra bằng key FORMAT. Map đó chỉ thread chủ chạm tới, nên mọi get/set đều đơn luồng — không cần đồng bộ hóa. Dữ liệu đi theo thread.

Một chi tiết cài đặt quyết định câu chuyện rò rỉ: entry trong ThreadLocalMap giữ key qua WeakReference — tham chiếu yếu, không ngăn GC thu hồi object nó trỏ tới — còn value giữ qua strong reference. Nhờ vậy, khi object ThreadLocal không còn ai dùng, key bị GC thu và entry thành "stale entry", được dọn nhân tiện lúc thread gọi set/get/remove lần sau. Nhưng không gì bảo đảm việc dọn xảy ra, và value vẫn bị strong reference giữ chặt chừng nào entry còn trong map.

flowchart LR
    P["Thread pool"] --> T["Worker thread (song rat lau)"]
    T --> M["ThreadLocalMap"]
    M --> E["Entry"]
    E -.->|"weak ref (key)"| K["ThreadLocal"]
    E ==>|"strong ref (value)"| V["Value cua request cu"]
    style V fill:#FCA5A5
    style K fill:#6EE7B7

Thread còn sống thì map còn sống, entry chưa gỡ thì value còn bị trỏ tới — GC bó tay. Thread thường chết đi kéo map chết theo; thread trong pool không bao giờ chết.

3. Pitfall: ThreadLocal gặp thread pool

Thread trong pool tái sử dụng hết request này tới request khác. Xét filter gán user vào ThreadLocal mà quên dọn:

// SAI: set ma khong remove -- thread quay ve pool van om gia tri cu
public class AuthFilter {
    private static final ThreadLocal<User> CURRENT_USER = new ThreadLocal<>();
    public void doFilter(Request req, Chain chain) {
        CURRENT_USER.set(authenticate(req));   // gan user cua request nay
        chain.proceed(req);                    // tang sau doc CURRENT_USER.get()
        // thieu remove()
    }
}

CURRENT_USER.get() của request B trả về Alice — user của request trước. Thread W quay về pool vẫn ôm nguyên entry cũ; B không set nên đọc trúng giá trị thừa. Đây là lỗi lẫn ngữ cảnh mang màu sắc bảo mật: B hành động dưới danh nghĩa Alice. Hậu quả thứ hai là bộ nhớ: mỗi worker găm một User cùng mọi thứ nó trỏ tới, sống vô hạn vì thread pool không chết — rò rỉ âm thầm, pool vài trăm thread thì tích tụ đáng kể.

Lời giải là kỷ luật remove — đặt gì vào ThreadLocal trong một tác vụ thì gỡ ra khi tác vụ kết thúc, an toàn nhất trong khối finally. Trước khi xem đáp án, tự điền vào chỗ /* ? */:

private static final ThreadLocal<String> REQUEST_ID = new ThreadLocal<>();
public void handle(Request req) {
    REQUEST_ID.set(req.id());
    try {
        process(req);                 // cac tang sau doc REQUEST_ID.get()
    } finally {
        /* ? -- gi o day de thread quay ve pool khong om ngu canh cu? */
    }
}

Chỗ trống là REQUEST_ID.remove();. finally bảo đảm việc gỡ xảy ra kể cả khi process ném exception. Bỏ qua remove không gây lỗi ngay — nó âm thầm tích tụ, và đó chính là điều khiến nó nguy hiểm. ThreadLocal mạnh về cô lập dữ liệu, nhưng đẩy sang ta trách nhiệm vòng đời: ai đặt thì người đó phải dọn.

4. InheritableThreadLocal — kế thừa một lần lúc tạo thread con

ThreadLocal cô lập triệt để: thread con khởi đầu với ngăn trống. InheritableThreadLocal là nhánh phụ cho khi ta muốn con vẫn gắn đúng ngữ cảnh của cha (ví dụ correlation ID): tại thời điểm thread con được tạo, nó sao chép giá trị từ InheritableThreadLocal của cha sang ngăn của mình — một lần chụp ảnh, và vì là sao chép tham chiếu nên chỉ an toàn với giá trị immutable.

Giới hạn nằm ở đúng chỗ ta hay cần nó nhất: kế thừa chỉ xảy ra khi một thread trực tiếp tạo thread khác. Với executor (worker dựng sẵn) không có "lúc tạo con" nào để chụp, nên ngữ cảnh không qua được ranh giới submit; với virtual thread tạo hàng loạt, sao chép cả bản đồ ngữ cảnh mỗi lần spawn là chi phí không nhỏ. Điểm gãy này đặt nền cho ScopedValue.

5. ScopedValue — ràng giá trị vào phạm vi, không vào thread

Thay vì gắn giá trị vào một thread rồi tin có ai đó sẽ dọn, ScopedValue ràng giá trị vào một phạm vi có biên giới rõ ràng, chỉ tồn tại trong lúc một khối code đang chạy. Nó immutable trong phạm vi ấy, không hề có set — khác biệt nền tảng so với ThreadLocal.

private static final ScopedValue<String> REQUEST_ID = ScopedValue.newInstance();
public void handle(Request req) {
    ScopedValue.where(REQUEST_ID, req.id())
        .run(() -> process(req));    // REQUEST_ID.get() hop le o moi noi BEN TRONG khoi nay
    // ra khoi day, REQUEST_ID khong con bound -- khong can, va khong the, remove()
}

Giá trị bound đúng cho khoảng thời gian khối lambda chạy, kể cả các lời gọi sâu bên trong, rồi tự unbound khi run trả về. Không có bước dọn thủ công nên cũng không có khả năng quên dọn — cửa sổ rò rỉ mà ThreadLocal mở ra trên thread pool bị đóng kín bằng chính cấu trúc API. Bất biến cũng loại bỏ lớp lỗi tầng code sâu lén set lại ngữ cảnh: cần giá trị khác thì bind chồng một phạm vi con, giá trị cũ tự hiện lại khi khối con kết thúc.

Ở đây ScopedValue xuất hiện như công cụ confinement: mỗi phạm vi giam giá trị của nó, immutable và có vòng đời bao đóng. Câu chuyện lớn hơn — ngữ cảnh truyền xuống hàng loạt virtual thread mà không phải sao chép — thuộc về bài ScopedValue ở quy mô virtual thread, sau khi Structured Concurrency dựng bộ khung fork/join.

6. Liên hệ các bài khác

• Confinement: ad-hoc và stack — hai nấc confinement trước; bài này đi nốt trục sang per-thread state toàn cục-trong-tầm-với.
• Process và Thread — mỗi thread giữ riêng stack và ngữ cảnh thực thi; nền để hiểu vì sao dữ liệu ThreadLocal đi theo thread, nằm trong ThreadLocalMap của chính object Thread.
• ScopedValue ở quy mô virtual thread — nơi ScopedValue phát huy trọn vẹn: ngữ cảnh kế thừa theo phạm vi xuống tác vụ con, ở quy mô virtual thread.
• Immutability — vì sao "immutable" là chìa khóa khiến ScopedValue an toàn khi chia sẻ xuống nhiều tầng.

7. 📚 Deep Dive Oracle

8. Tóm tắt

• Dữ liệu ThreadLocal nằm trong ThreadLocalMap của chính Thread → get/set không khóa; nhưng trên thread pool (thread không chết) quên remove() rò cả dữ liệu lẫn bộ nhớ (WeakReference chỉ giữ key, không cứu value). Kỷ luật: remove() trong finally.
• ScopedValue đóng cửa sổ rò rỉ bằng thiết kế — phạm vi bao đóng + immutable + không có API để quên dọn. Là công cụ confinement ở đây; câu chuyện truyền ngữ cảnh ở quy mô virtual thread thuộc bài Structured Concurrency.

9. Tự kiểm tra

Bài tiếp theo: Immutability — thread safety bằng cách không thay đổi