Thread Pool Monitoring

## What a ThreadPoolExecutor is A **ThreadPoolExecutor** is the standard Java class (in `java.util.concurrent`) that runs your tasks on a reusable set of background **worker threads** instead of spawning a fresh thread per task. You submit `Runnable`/`Callable` work; the pool runs it on a free thread or holds it in an internal **work queue** until a thread frees up. Key knobs: **corePoolSize** (threads kept alive even when idle), **maximumPoolSize** (hard ceiling on thread count), and the **queue**. ## The three sizing accessors - **`getPoolSize()`** returns the number of worker threads that *currently exist*, both idle and busy. It grows as the pool creates threads (up to maximumPoolSize) and can shrink when idle threads time out (if `allowCoreThreadTimeOut` is set or the count is above core). - **`getActiveCount()`** returns an *approximate* count of threads that are *actively executing a task* right now. So `getPoolSize() - getActiveCount()` is roughly the number of idle workers. - **`getLargestPoolSize()`** returns the **high-water mark**: the largest the pool ever reached over its lifetime. It only ever increases (until the pool ends). It answers 'did we ever need more threads than we have now?'. ## Why three numbers instead of one Each answers a different question. `getPoolSize()` = capacity allocated. `getActiveCount()` = capacity in use *now*. `getLargestPoolSize()` = peak capacity ever needed. Reading them together tells a story: | Observation | Interpretation | |---|---| | activeCount approx poolSize, both near maximumPoolSize | Pool is saturated; new work is queueing | | activeCount much less than poolSize | Pool is over-provisioned or load just dropped | | largestPoolSize == maximumPoolSize | The ceiling was hit at least once; consider raising max or check for blocking tasks | | largestPoolSize much less than maximumPoolSize | The pool never needed its full ceiling | ## The 'approximate' caveat `getActiveCount()` is documented as **approximate**. The executor holds an internal lock (`mainLock`) while it iterates its worker set to count active workers, but a worker can finish or start a task in the window around the call, so the returned value is a best-effort instantaneous estimate, not a transactional snapshot. This is fine for monitoring/dashboards but you must not build correctness logic (e.g. 'only submit if activeCount < N') on it, because it can race. ## Cost and safety All three are cheap O(1)-ish reads (getActiveCount walks workers but that set is small) and thread-safe to call from a separate monitoring thread. They are the first-line vital signs of a pool, usually paired with the queue size and getCompletedTaskCount() (covered separately) to form a full picture.