Class CaptchaPool

java.lang.Object
cloud.opencode.base.captcha.support.CaptchaPool
All Implemented Interfaces:
AutoCloseable
public final class CaptchaPool extends Object implements AutoCloseable
Captcha Pool - Pre-generates CAPTCHAs in background for instant retrieval 验证码池 - 在后台预生成验证码以实现即时获取

This class maintains a pool of pre-generated CAPTCHAs using a background virtual thread that fills the pool asynchronously. When the pool drops below a configurable refill threshold, the background thread wakes up and generates more CAPTCHAs. If the pool is empty when take() is called, a CAPTCHA is generated in real-time as a fallback.

此类使用后台虚拟线程维护一个预生成的验证码池，异步填充池。当池中数量低于 可配置的补充阈值时，后台线程将被唤醒并生成更多验证码。如果调用 take() 时池为空，将实时生成验证码作为降级方案。

Features | 主要功能:

  • Background pre-generation via virtual thread - 通过虚拟线程后台预生成
  • Configurable pool size and refill threshold - 可配置的池大小和补充阈值
  • Graceful fallback when pool is empty - 池为空时优雅降级
  • AutoCloseable for proper resource cleanup - 实现 AutoCloseable 以正确清理资源
  • Builder pattern for configuration - 构建器模式配置

Usage Examples | 使用示例:

// Create a pool with default settings
try (CaptchaPool pool = CaptchaPool.builder()
        .config(CaptchaConfig.defaults())
        .poolSize(200)
        .refillThreshold(0.3f)
        .build()) {

    // Get a pre-generated CAPTCHA instantly
    Captcha captcha = pool.take();

    // Check pool status
    int available = pool.size();
}

Performance | 性能特性:

  • Time complexity: O(1) for take() from pool, O(generation) for fallback - 时间复杂度: 从池获取 O(1)，降级生成 O(生成时间)
  • Space complexity: O(poolSize) - 空间复杂度: O(poolSize)

Security | 安全性:

  • Thread-safe: Yes (uses LinkedBlockingQueue and AtomicBoolean) - 线程安全: 是（使用 LinkedBlockingQueue 和 AtomicBoolean）
  • Null-safe: No (config must not be null) - 空值安全: 否（config 不能为 null）
Since:
JDK 25, opencode-base-captcha V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • builder

      public static CaptchaPool.Builder builder()
      Creates a new builder for CaptchaPool. 创建新的 CaptchaPool 构建器。
      Returns:
      a new builder | 新构建器

    • take

      public Captcha take()
      Takes a CAPTCHA from the pool. 从池中获取一个验证码。

      If the pool is empty, a CAPTCHA is generated in real-time as a fallback. This ensures that callers always receive a CAPTCHA even under high load.

      如果池为空，将实时生成验证码作为降级方案。 这确保了即使在高负载下调用者也能始终获得验证码。

      Returns:
      a CAPTCHA instance | 验证码实例
      Throws:
      IllegalStateException - if the pool has been closed | 如果池已关闭

    • size

      public int size()
      Returns the number of CAPTCHAs currently available in the pool. 返回池中当前可用的验证码数量。
      Returns:
      the current pool size | 当前池大小

    • isRunning

      public boolean isRunning()
      Returns whether the pool is running. 返回池是否正在运行。
      Returns:
      true if running | 如果正在运行则返回 true

    • close

      public void close()
      Shuts down the pool and interrupts the background fill thread. 关闭池并中断后台填充线程。

      After closing, take() will throw IllegalStateException. Any remaining CAPTCHAs in the pool are discarded.

      关闭后，take() 将抛出 IllegalStateException。 池中剩余的验证码将被丢弃。

      Specified by:
      close in interface AutoCloseable