Class VirtualThreadContext

java.lang.Object
cloud.opencode.base.log.enhance.VirtualThreadContext
public final class VirtualThreadContext extends Object
Virtual Thread Context Propagation - JDK 25+ 虚拟线程上下文传播 - JDK 25+

Provides utilities for propagating log context (MDC/NDC) across Virtual Threads. Traditional ThreadLocal-based MDC does not automatically inherit to Virtual Threads, so this class provides wrapping utilities to capture and restore context.

提供跨虚拟线程传播日志上下文（MDC/NDC）的工具。 传统基于 ThreadLocal 的 MDC 不会自动继承到虚拟线程， 因此本类提供包装工具来捕获和恢复上下文。

Usage Example | 使用示例:

LogContext.setTraceId("trace-123");
LogContext.setUserId("user-456");

// Virtual Thread automatically inherits log context
VirtualThreadContext.startVirtualThread(() -> {
    // traceId and userId are accessible here
    OpenLog.info("Async processing");
});

// Using ExecutorService
ExecutorService executor = VirtualThreadContext.newVirtualThreadExecutor();
executor.submit(() -> {
    OpenLog.info("Task in pool");  // Context propagated
});

Features | 主要功能:

  • MDC/NDC context propagation to virtual threads - MDC/NDC 上下文传播到虚拟线程
  • Wrappers for Runnable, Callable, Function, CompletableFuture - Runnable、Callable、Function、CompletableFuture 的包装器
  • Virtual thread executor with context propagation - 带上下文传播的虚拟线程执行器
  • Async execution helpers (runAsync, supplyAsync) - 异步执行辅助方法（runAsync、supplyAsync）

Security | 安全性:

  • Thread-safe: Yes (captures and restores context safely) - 线程安全: 是（安全地捕获和恢复上下文）
  • Null-safe: Yes (handles null context maps) - 空值安全: 是（处理 null 上下文映射）
Since:
JDK 25, opencode-base-log V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • startVirtualThread

      public static Thread startVirtualThread(Runnable task)
      Creates and starts a Virtual Thread with propagated log context 创建并启动带日志上下文传播的虚拟线程
      Parameters:
      task - the task to execute | 要执行的任务
      Returns:
      the started virtual thread | 已启动的虚拟线程

    • virtualThreadBuilder

      public static Thread.Builder.OfVirtual virtualThreadBuilder(String name)
      Creates a Virtual Thread builder with context propagation 创建带上下文传播的虚拟线程构建器
      Parameters:
      name - the thread name | 线程名
      Returns:
      thread builder | 线程构建器

    • newVirtualThreadExecutor

      public static ExecutorService newVirtualThreadExecutor()
      Creates a Virtual Thread ExecutorService with context propagation 创建带上下文传播的虚拟线程执行器服务
      Returns:
      executor service | 执行器服务

    • newVirtualThreadExecutor

      public static ExecutorService newVirtualThreadExecutor(String namePrefix)
      Creates a named Virtual Thread ExecutorService with context propagation 创建命名的带上下文传播的虚拟线程执行器服务
      Parameters:
      namePrefix - the thread name prefix | 线程名前缀
      Returns:
      executor service | 执行器服务

    • wrap

      public static Runnable wrap(Runnable runnable)
      Wraps a Runnable to propagate log context 包装 Runnable 以传播日志上下文
      Parameters:
      runnable - the original runnable | 原始 runnable
      Returns:
      wrapped runnable with context propagation | 带上下文传播的包装 runnable

    • wrap

      public static <T> Callable<T> wrap(Callable<T> callable)
      Wraps a Callable to propagate log context 包装 Callable 以传播日志上下文
      Type Parameters:
      T - the return type | 返回类型
      Parameters:
      callable - the original callable | 原始 callable
      Returns:
      wrapped callable with context propagation | 带上下文传播的包装 callable

    • wrap

      public static <T,R> Function<T,R> wrap(Function<T,R> function)
      Wraps a Function to propagate log context 包装 Function 以传播日志上下文
      Type Parameters:
      T - the input type | 输入类型
      R - the return type | 返回类型
      Parameters:
      function - the original function | 原始 function
      Returns:
      wrapped function with context propagation | 带上下文传播的包装 function

    • wrap

      public static <T> CompletableFuture<T> wrap(CompletableFuture<T> future)
      Wraps a CompletableFuture to propagate log context to subsequent stages 包装 CompletableFuture 以传播日志上下文到后续阶段
      Type Parameters:
      T - the result type | 结果类型
      Parameters:
      future - the original future | 原始 future
      Returns:
      wrapped future with context propagation | 带上下文传播的包装 future

    • runAsync

      public static CompletableFuture<Void> runAsync(Runnable task)
      Runs a task asynchronously on a Virtual Thread with context propagation 在虚拟线程上异步运行任务并传播上下文
      Parameters:
      task - the task to run | 要运行的任务
      Returns:
      CompletableFuture that completes when task finishes | 任务完成时的 CompletableFuture

    • supplyAsync

      public static <T> CompletableFuture<T> supplyAsync(Callable<T> supplier)
      Supplies a value asynchronously on a Virtual Thread with context propagation 在虚拟线程上异步提供值并传播上下文
      Type Parameters:
      T - the result type | 结果类型
      Parameters:
      supplier - the supplier | 供应者
      Returns:
      CompletableFuture with result | 包含结果的 CompletableFuture

    • runWithContext

      public static void runWithContext(String traceId, String userId, Runnable task)
      Executes a task with specific context values 使用特定上下文值执行任务
      Parameters:
      traceId - the trace ID | 追踪 ID
      userId - the user ID | 用户 ID
      task - the task | 任务

    • callWithContext

      public static <T> T callWithContext(String traceId, String userId, Callable<T> task) throws Exception
      Executes a task with specific context values and returns result 使用特定上下文值执行任务并返回结果
      Type Parameters:
      T - the result type | 结果类型
      Parameters:
      traceId - the trace ID | 追踪 ID
      userId - the user ID | 用户 ID
      task - the task | 任务
      Returns:
      the result | 结果
      Throws:
      Exception - if task fails | 如果任务失败