PS-10071 [DOCS] - update Threadpool to add implementation 8.0

	new file:   docs/_static/thread-pool-diagram.png
	modified:   docs/threadpool.md

Author: patrickbirch

docs/_static/thread-pool-diagram.png

@@ -8,6 +8,38 @@ The default method, called one-thread-per-connection, creates a new thread for e
 
 MySQL supports thread pooling through the thread pool plugin, which replaces the default one-thread-per-connection model. When a statement arrives, the thread group either begins executing it immediately or queues it for later execution in a round-robin fashion. The high-priority queue consists of several thread groups, each managing client connections. Each thread group has a listener thread that listens for incoming statements from the connections assigned to the group. The thread pool exposes several system variables that can be used to configure its operation, such as thread_pool_size, thread_pool_algorithm, thread_pool_stall_limit, and others.
 
+
+## How thread pool works
+
+### Simplified Overview of the Thread Pool
+
+A thread pool allows MySQL to manage many client connections with greater 
+efficiency. Rather than launching a new thread for each connection, which is a resource-intensive approach, the server initializes a fixed set of reusable threads in advance.
+
+Here's the basic process:
+
+* When a client connects, the server assigns the connection to a specific thread
+  group.
+
+* Each thread group includes a listener responsible for detecting new queries.
+
+* Queries from clients enter one of two queues: high-priority or low-priority.
+
+* Worker threads within the group retrieve queries from these queues for 
+  execution.
+
+* Queries associated with active transactions and unused high-priority tickets 
+  are directed to the high-priority queue.
+
+* All other queries enter the low-priority queue and wait for an available 
+  worker.
+
+This approach avoids the overhead associated with excessive thread creation and 
+maintains server responsiveness, even during periods of high connection volume.
+
+
+<img src="../_static/thread-pool-diagram.png" alt="Thread pool diagram" width="250" />
+
 The thread pool plugin consists of several thread groups, each of which manages a set of client connections. As connections are established, the thread pool assigns them to thread groups using the round-robin method. This method assigns threads fairly and efficiently. Here's how it works:
 
 1. The thread pool starts with a set number of thread groups.
@@ -56,23 +88,73 @@ Starting with 8.0.14, Percona Server for MySQL uses the upstream implementation
 
 Implemented in 8.0.12-1: We ported the `Thread Pool` feature from Percona Server for MySQL 5.7.
 
-## Priority connection scheduling
+## Thread pool priority queues
+
+The thread pool limits the number of concurrently running queries to improve
+performance under high load. Even when concurrency is constrained, the number
+of open transactions can remain high. The thread pool manages these connections
+using priority queues.
 
-The thread pool limits the number of concurrently running queries. The number of open transactions may remain high. Connections with already-started transactions are added to the end of the queue. A high number of open transactions has implications for the currently running queries. The [thread_pool_high_prio_tickets](#thread_pool_high_prio_tickets) variable controls the high-priority queue policy and assigns tickets to each new connection.
+When a new connection starts a transaction, the thread pool evaluates whether
+to place it in the high-priority queue. It does so if both of the following
+conditions are true:
 
-The thread pool adds the connection to the high-priority queue and decrements the ticket if the connection has the following attributes:
+- The connection has an open transaction.
+- The connection has a non-zero number of high-priority tickets, as defined by
+  the `thread_pool_high_prio_tickets` variable.
 
-* Has an open transaction
+Each time the thread pool schedules work, it checks the high-priority queue
+first. If that queue is empty, it pulls from the low-priority queue. This
+behavior ensures that transactions already in progress receive preferential
+treatment.
 
-* Has a non-zero number of high-priority tickets
+If `thread_pool_high_prio_tickets` is set to `0`, all connections go to the
+low-priority queue. If the value is greater than `0`, each new connection
+receives that number of high-priority tickets. The thread pool decrements a
+ticket each time it prioritizes a connection.
 
-Otherwise, the variable adds the connection to the low-priority queue with the initial value.
+## Configuring `thread_pool_high_prio_mode`
 
-Each time, the thread pool checks the high-priority queue for the next connection. When the high-priority queue is empty, the thread pool picks connections from the low-priority queue. The default behavior is to put events from already started transactions into the high-priority queue.
+The `thread_pool_high_prio_mode` variable controls how the thread pool assigns
+priority to connections, and accepts the following values:
+
+* `transactions`: Prioritizes statements that are part of an open transaction
+  (default).
+  
+* `statements`: Prioritizes all statements from a connection with available
+  high-priority tickets.
+  
+* `none`: Disables high-priority scheduling. All connections go to the
+  low-priority queue.
+  
+
+
+### Static configuration
+
+To set the variable persistently, add the following to your `my.cnf` file:
+
+```ini
+[mysqld]
+thread_pool_high_prio_mode = transactions
+```
+
+### Dynamic configuration
+
+You can also change this setting at runtime without restarting:
+
+```
+mysql> SET GLOBAL thread_pool_high_prio_mode = 'transactions';
+```
+
+This change takes effect immediately for new connections only. Existing client sessions continue to operate under the previously active mode. To ensure all clients reflect the new behavior, either:
+
+* Restart the server, or
+
+* Have connected clients disconnect and reconnect manually.
+
+This dynamic adjustment enables fine-tuning thread scheduling behavior in production systems without downtime.
 
-If the value equals `0`, all connections are put into the low-priority queue. If the value exceeds zero, each connection could be put into a high-priority queue.
 
-The [thread_pool_high_prio_mode](#thread_pool_high_prio_mode) variable prioritizes all statements for a connection or assigns connections to the low-priority queue. To implement this new [thread_pool_high_prio_mode](#thread_pool_high_prio_mode) variable
 
 ## Low-priority queue throttling
 
@@ -123,6 +205,28 @@ This variable can limit the time an idle thread should wait before exiting.
 
 ### `thread_pool_high_prio_mode`
 
+---
+### `thread_pool_high_prio_mode`
+
+| Option         | Description                                                                 |
+| -------------- | --------------------------------------------------------------------------- |
+| Command-line:  | Yes                                                                         |
+| Config file:   | Yes                                                                         |
+| Scope:         | Global                                                                      |
+| Dynamic:       | Yes                                                                         |
+| Data type:     | Enumeration (`transactions`, `statements`, `none`)                         |
+| Default value: | `transactions`                                                              |
+
+Controls how the thread pool schedules high-priority work. When set to 
+`transactions`, only statements within an open transaction are eligible for 
+high-priority execution. The `statements` option prioritizes all statements 
+from connections that still have unused high-priority tickets. Setting this 
+variable to `none` disables high-priority queueing entirely.
+
+Changes take effect immediately for new connections. Existing sessions must 
+reconnect to adopt the new behavior.
+
+
 This variable provides more fine-grained control over high-priority scheduling globally or per connection.
 
 The following values are allowed:
@@ -248,3 +352,16 @@ This status variable shows the number of idle threads in the pool.
 
 This status variable shows the number of threads in the pool.
 
+### Limitations and recommendations
+
+| Limitation                        | Description                                                                 | Recommendation                                                              |
+|----------------------------------|-----------------------------------------------------------------------------|------------------------------------------------------------------------------|
+| Limited benefit at low loads     | Thread pool offers marginal gains below ~512–1000 connections.              | Use default threading for small workloads. Evaluate before enabling.        |
+| No effect on existing sessions   | Dynamic changes only affect new connections.                                | Prompt clients to reconnect or plan for a rolling restart.                  |
+| Long-running query contention    | Extended queries block worker threads, reducing throughput.                 | Isolate long-running queries to separate servers or use query timeouts.     |
+| Thread starvation risk           | High-priority queues may crowd out low-priority connections.                | Monitor queue activity; balance ticket settings and connection patterns.    |
+| Complexity in tuning             | Poor variable configuration can degrade performance.                        | Test settings in staging; tune iteratively based on observed behavior.      |
+| Limited monitoring               | Native tools offer minimal queue and saturation visibility.                 | Integrate with monitoring systems (e.g., PMM, Prometheus) for better insight. |
+| Static design                    | Not a plugin; cannot be toggled dynamically.                                | Decide at deployment; changes require a configuration update and restart.   |
+
+