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,90 +1,287 @@
 # 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
 
-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.
+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 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.
+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.
 
-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.
+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.
 
-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:
+## Version-specific notes
 
-1. The thread pool starts with a set number of thread groups.
+Thread pool support in Percona Server for MySQL evolved across releases. Review
+the following version details to avoid configuration errors and ensure
+compatibility.
 
-2. When a new task arrives, the pool needs to assign it to a group.
+  
+### Changed in 8.0.14
 
-3. It does this by going through the groups in order, one by one.
+Beginning with 8.0.14, the upstream implementation of `admin_port` replaced the
+previous mechanism that used `extra_port` and `extra_max_connections`.
 
-4. Let's say you have four thread groups. The assignment would work like this:
-   - Task 1 goes to Group 1
-   - Task 2 goes to Group 2
-   - Task 3 goes to Group 3
-   - Task 4 goes to Group 4
-   - Task 5 goes back to Group 1
-   
-5. This pattern continues, always moving to the next group and starting over when it reaches the end.
+  
+**What changed:**
 
-6. Each group handles its assigned tasks using its available threads.
+* `extra_port` and `extra_max_connections` are removed.
 
-This round-robin approach spreads work evenly across all groups. It prevents any single group from getting overloaded while others sit idle. This method helps maintain balanced performance across the system.
+* These variables are no longer recognized and cause server startup failure.
 
-MySQL executes statements using one thread per client connection. When the number of connections increases past a specific point, performance degrades.
-This feature introduces a dynamic thread pool, which enables the server to maintain top performance even with a large number of client connections. The server decreases the number of threads using the thread pool and reduces the context switching and hot lock contentions. The thread pool is most effective with `OLTP` workloads (relatively short CPU-bound queries).
+  
+**Migration steps:**
 
-Set the thread pool variable [thread_handling](#thread_handling) to `pool-of-threads` by adding the following line to `my.cnf`:
+* Remove all references to `extra_port` and `extra_max_connections` from the
+  configuration file before upgrading to 8.0.14 or later.
 
-```text
-thread_handling=pool-of-threads
+* Use the `admin_port` variable, as supported by upstream MySQL, to configure
+  administrative access if needed.
+
+  
+### Implemented in 8.0.12-1
+
+Percona Server for MySQL 8.0.12-1 introduced native support for the thread pool.
+This version ported the feature from Percona Server 5.7.
+
+## 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.
+
+### How the thread pool works
+
+When a client connects, the server assigns the connection to a thread group using a round-robin method. Each group contains a listener thread and worker threads. The listener monitors active connections and queues incoming statements.
+
+Each new query is routed to either the high-priority queue or the low-priority queue within the group. A query enters the high-priority queue if the connection has an open transaction and available high-priority tickets. All other queries are sent to the low-priority queue.
+
+Worker threads scan the high-priority queue first, then process queries from the low-priority queue when no high-priority items remain. After finishing a query, the thread becomes idle and waits for the next task. This reuse avoids excessive thread creation and maintains steady performance under load.
+
+The pool adapts to workload shifts by redistributing queued tasks and prioritizing available threads. The result is better system responsiveness with fewer total threads.
 
-Although the default values for the thread pool should provide good performance, additional tuning should be performed with the dynamic system variables. The goal is to minimize the number of open transactions on the server. Short-running transactions commit faster and deallocate server resources and locks.
+<img src="../_static/thread-pool-diagram.png" alt="Thread pool diagram" width="250" />
 
-Due to the following differences, this implementation is not compatible with upstream:
+### Thread groups
 
-* Built into the server, upstream implements the thread pool as a plugin
+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.
 
-* Does not minimize the number of concurrent transactions
 
-Priority Queue:
+```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%';
+```
 
-A queue that assigns a priority to each data element and processes them according to their priority. The data element with the highest priority is served first, regardless of its order in the queue. A priority queue can be implemented using an array, a linked list, a heap, or a binary search tree. It can also be ascending or descending, meaning that the highest priority is either the smallest or the largest value.
+This command displays queue lengths and thread statistics.
 
-## Version specific information
+### High-priority ticketing
 
-Starting with 8.0.14, Percona Server for MySQL uses the upstream implementation of the [`admin_port`](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_admin_port). The variables [extra_port](#extra_port) and [extra_max_connections](#extra_max_connections) are removed and not supported. Remove the `extra_port` and `extra_max_connections` variables from your configuration file before upgrading to 8.0.14 or higher. In 8.0.14 or higher, the variables cause a boot error, and the server refuses to start.
+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.
 
-Implemented in 8.0.12-1: We ported the `Thread Pool` feature from Percona Server for MySQL 5.7.
+#### Static configuration
 
-## Priority connection scheduling
+```ini
+[mysqld]
+thread_pool_high_prio_tickets = 5
+```
 
-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.
+#### Dynamic configuration
 
-The thread pool adds the connection to the high-priority queue and decrements the ticket if the connection has the following attributes:
+```mysql
+mysql> mysql> SET GLOBAL thread_pool_high_prio_tickets = 5;
+```
 
-* Has an open transaction
+Either of these configurations assign five tickets to each new connection.
 
-* Has a non-zero number of high-priority tickets
 
-Otherwise, the variable adds the connection to the low-priority queue with the initial value.
+### 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.
+
+### Configuration `thread_pool_high_prio_mode`
+
+To set the variable persistently, add the following to your `my.cnf` file:
+
+```ini
+[mysqld]
+thread_pool_high_prio_mode = transactions
+```
+
+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 flexibility allows scheduling behavior to be fine-tuned without disrupting active workloads.
+
+### 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
+
+
+
+### Configuration and monitoring
+
+Administrators can fine-tune thread pool behavior by adjusting dynamic and static variables.
+
+
+#### Static configuration
+
+```ini
+[mysqld]
+thread_pool_stall_limit = 100
+```
+
+#### Dynamic configuration
+
+```mysql
+mysql> SET GLOBAL thread_pool_stall_limit = 100;
+```
+
+This value, in milliseconds, limits how long a task can stall before being redistributed. As with other thread pool settings, existing sessions retain their previous values.
+
+#### Check the status
+
+```mysql
+mysql> SHOW ENGINE THREAD_POOL STATUS;
+```
+
+This command returns information about thread usage and group activity.
+
+## When to use the thread pool
+
+Choosing between the thread pool and the default threading model depends on
+system size, workload patterns, and performance goals. Use the guidelines below
+to decide which approach fits best.
+
+### Use the thread pool when:
+
+* The system experiences hundreds or thousands of concurrent connections.
+
+* Most queries are short, frequent, and CPU-bound (typical of OLTP workloads).
+
+* The server suffers from context switching, thread contention, or memory
+  overhead due to excessive threads.
+
+* Transactions should be prioritized, and precise query scheduling is required.
+
+* Thread count must remain predictable and resource usage needs tighter control.
+
+  
+### Use the default model when:
+
+* The deployment serves fewer than 500 concurrent clients.
+
+* Queries are long-running or resource-heavy and better suited to isolated
+  execution.
+
+* Thread overhead is not a problem, and the simplicity of one-thread-per-
+  connection is acceptable.
+
+* There is no pressing need to control concurrency or prioritize active
+  transactions.
+
+  
+Thread pooling offers greater control and efficiency, but only in workloads that
+justify that complexity. Measure concurrency patterns and CPU behavior before
+enabling the feature.
+
+## Thread Pool Configuration Reference Sheet
+
+A quick overview of system variables available for configuring the thread pool in Percona Server for MySQL.
+
+### General Variables
+
+| Variable name            | Default                     | Scope  | Dynamic | Config file | Description                                           |
+|--------------------------|-----------------------------|--------|---------|--------------|-------------------------------------------------------|
+| `thread_handling`        | `one-thread-per-connection` | Global | No      | Yes          | Chooses the thread model. Set to `pool-of-threads` to enable thread pooling. |
+| `thread_pool_size`       | `16`                        | Global | No      | Yes          | Defines the number of thread groups.                 |
+| `thread_pool_algorithm`  | `first-in, first-out`       | Global | Yes     | Yes          | Controls how queued queries are scheduled (`first-in, first-out` or `lowest_priority`). |
+
+### Priority Handling
+
+| Variable name                     | Default        | Scope  | Dynamic | Config file | Description                                                |
+|----------------------------------|----------------|--------|---------|--------------|------------------------------------------------------------|
+| `thread_pool_high_prio_tickets`  | `4294967295`   | Global | Yes     | Yes          | High-priority executions per connection.                   |
+| `thread_pool_high_prio_mode`     | `transactions` | Global | Yes     | Yes          | Determines when to assign high priority (`transactions`, `statements`, or `none`). |
+
+### Thread Management
+
+| Variable name             | Default | Scope  | Dynamic | Config file | Description                                         |
+|---------------------------|---------|--------|---------|--------------|-----------------------------------------------------|
+| `thread_pool_min_threads` | `4`     | Global | No      | Yes          | Minimum number of threads per group.               |
+| `thread_pool_max_threads` | `1000`  | Global | No      | Yes          | Maximum number of threads per group.               |
+| `thread_pool_stall_limit` | `6`     | Global | Yes     | Yes          | Time in milliseconds before retrying a stalled task. |
+
+### Observability Commands
+
+Use these SQL statements to view runtime metrics:
+
+```sql
+SHOW STATUS LIKE 'Threadpool%';
+SHOW ENGINE THREAD_POOL STATUS;
+```
+
+Note: For dynamic variables, changes apply only to new connections. Existing sessions retain their original settings until reconnect.
+
 
-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.
 
-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
 
-One case that can limit thread pool performance and even lead to deadlocks under high concurrency is when thread groups are oversubscribed due to active threads reaching the oversubscribe limit. Still, all/most worker threads are waiting on locks currently held by a transaction from another connection that is not currently in the thread pool.
 
-In this case, the oversubscribe limit does not account for those threads in the pool that marked themselves inactive. As a result, the number of threads (both active and waiting) in the pool grows until it hits the [`thread_pool_max_threads`](#thread_pool_max_threads) value. If the connection executing the transaction holding the lock has managed to enter the thread pool by then, we get a large (depending on the [`thread_pool_max_threads`](#thread_pool_max_threads) value) number of concurrently running threads and, thus, suboptimal performance. Otherwise, we get a deadlock as no more threads can be created to process those transaction(s) and release the lock(s).
 
-Such situations are prevented by throttling the low-priority queue when the total number of worker threads (both active and waiting ones) reaches the oversubscribe limit. If there are too many worker threads, do not start new transactions; create new threads until queued events from the already-started transactions are processed.
 
-## Handling long network waits
 
-Specific workloads (large result sets, BLOBs, slow clients) can wait longer on network I/O (socket reads and writes). Whenever the server waits, this should be communicated to the thread pool so it can start a new query by either waking a waiting thread or sometimes creating a new one. This implementation has been ported from *MariaDB* patch MDEV-156.
 
 ## System variables
 
@@ -121,8 +318,28 @@ This variable defines how the server handles threads for connections from the cl
 
 This variable can limit the time an idle thread should wait before exiting.
 
+
 ### `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: