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

@@ -1,12 +1,118 @@
 # Thread pool
 
-Thread pooling can improve performance and scalability for MySQL databases. This technique reuses a fixed number of threads to handle multiple client connections and execute statements. It reduces the overhead of creating and destroying threads and avoids the contention and context switching that can occur when there are too many threads.
+## Introduction
+
+Thread pooling improves performance and scalability for MySQL-compatible databases by
+reusing a fixed number of pre-created threads to manage multiple client
+sessions. This design reduces resource overhead, lowers contention, and avoids
+context switching bottlenecks during high concurrency.
+
+The default MySQL method creates one thread per client connection. This approach
+works efficiently under moderate connection loads. As the number of active
+connections increases, especially beyond 20,000, system overhead becomes
+significant and throughput decreases.
+
+Percona Server for MySQL includes an integrated thread pool that replaces the
+default model. The thread pool manages connections more efficiently by queuing
+work and reusing threads, especially in OLTP environments with many short-lived
+queries.
+
+## Core concepts and usage examples
+
+### Fixed pool of threads
+
+The server initializes a defined number of threads at startup and reuses them
+to process incoming queries.
+
+
+```ini
+[mysqld]
+thread_handling = pool-of-threads
+```
+This setting activates the thread pool model.
+
+### Thread groups
+
+The thread pool organizes threads into groups. Each group contains a listener thread, a set of worker threads, and handles a portion of the client connections.
+
+
+```ini
+[mysqld]
+thread_pool_size = 8
+```
+
+This configuration spreads work across eight thread groups.
+
+### Priority queues
+
+Each thread group maintains a high-priority queue and a low-priority queue. New queries are added to one of the two based on ticket availability and transaction state. The thread pool always checks the high-priority queue first.
+
+```mysql
+mysql> SHOW STATUS LIKE 'Threadpool%';
+```
+
+This command displays queue lengths and thread statistics.
+
+### High-priority ticketing
+
+Each connection begins with a set number of high-priority tickets. These tickets allow prioritization for a limited number of queries. One ticket is used every time the thread pool promotes a query to the high-priority queue.
+
+```ini
+[mysqld]
+thread_pool_high_prio_tickets = 5
+```
+
+This assigns five tickets to each new connection.
+
+
+### High-priority modes
+
+The `thread_pool_high_prio_mode` setting controls how the thread pool schedules queries using tickets.
+
+```mysql
+mysql> SET GLOBAL thread_pool_high_prio_mode = 'transactions';
+```
+
+This setting limits prioritization to queries within open transactions.
+
+
+### Adaptive scheduling
+
+The server assigns new connections to thread groups using a round-robin method. This approach balances workload evenly and prevents any group from becoming a bottleneck.
+
+
+Connection 1 goes to Group 1
+
+Connection 2 goes to Group 2
+
+Connection 3 goes to Group 3
+
+Connection 4 goes to Group 4
+
+Connection 5 returns to Group 1
+
+<img src="../_static/thread-pool-diagram.png" alt="Thread pool diagram" width="250" />
+
+### Configuration and monitoring
+
+Administrators can fine-tune thread pool behavior by adjusting dynamic and static variables.
+
+```ini
+[mysqld]
+thread_pool_stall_limit = 100
+```
+
+This value, in milliseconds, limits how long a task can stall before being redistributed.
+
+```mysql
+mysql> SHOW ENGINE THREAD_POOL STATUS;
+```
+
+This command returns information about thread usage and group activity.
+
 
-If you have fewer than 20,000 connections, using the thread pool does not provide significant benefits. It’s better to keep thread pooling disabled and use the default method.
 
-The default method, called one-thread-per-connection, creates a new thread for each client that connects to the MySQL server. This thread manages all queries and responses for that connection until it’s closed. This approach works well for a moderate number of connections, but it can become inefficient as the number of connections increases.
 
-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.
 
 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:
 
@@ -56,23 +162,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.
+
+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 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.
 
-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.
+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.
 
-The thread pool adds the connection to the high-priority queue and decrements the ticket if the connection has the following attributes:
+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.
 
-* Has an open transaction
+## Configuring `thread_pool_high_prio_mode`
 
-* Has a non-zero number of high-priority tickets
+The `thread_pool_high_prio_mode` variable controls how the thread pool assigns
+priority to connections, and accepts the following values:
 
-Otherwise, the variable adds the connection to the low-priority queue with the initial value.
+* `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.
+  
 
-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.
 
-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.
+### 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.
+
 
-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 +279,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 +426,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.   |
+
+