You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/threadpool.md
+96-9Lines changed: 96 additions & 9 deletions
Original file line number
Diff line number
Diff line change
@@ -8,6 +8,8 @@ The default method, called one-thread-per-connection, creates a new thread for e
8
8
9
9
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.
10
10
11
+
<imgsrc="../_static/thread-pool-diagram.png"alt="Thread pool diagram"width="250" />
12
+
11
13
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:
12
14
13
15
1. The thread pool starts with a set number of thread groups.
@@ -56,23 +58,73 @@ Starting with 8.0.14, Percona Server for MySQL uses the upstream implementation
56
58
57
59
Implemented in 8.0.12-1: We ported the `Thread Pool` feature from Percona Server for MySQL 5.7.
58
60
59
-
## Priority connection scheduling
61
+
## Thread pool priority queues
62
+
63
+
The thread pool limits the number of concurrently running queries to improve
64
+
performance under high load. Even when concurrency is constrained, the number
65
+
of open transactions can remain high. The thread pool manages these connections
66
+
using priority queues.
67
+
68
+
When a new connection starts a transaction, the thread pool evaluates whether
69
+
to place it in the high-priority queue. It does so if both of the following
70
+
conditions are true:
71
+
72
+
- The connection has an open transaction.
73
+
- The connection has a non-zero number of high-priority tickets, as defined by
74
+
the `thread_pool_high_prio_tickets` variable.
75
+
76
+
Each time the thread pool schedules work, it checks the high-priority queue
77
+
first. If that queue is empty, it pulls from the low-priority queue. This
78
+
behavior ensures that transactions already in progress receive preferential
79
+
treatment.
80
+
81
+
If `thread_pool_high_prio_tickets` is set to `0`, all connections go to the
82
+
low-priority queue. If the value is greater than `0`, each new connection
83
+
receives that number of high-priority tickets. The thread pool decrements a
84
+
ticket each time it prioritizes a connection.
85
+
86
+
## Configuring `thread_pool_high_prio_mode`
87
+
88
+
The `thread_pool_high_prio_mode` variable controls how the thread pool assigns
89
+
priority to connections, and accepts the following values:
90
+
91
+
*`transactions`: Prioritizes statements that are part of an open transaction
92
+
(default).
93
+
94
+
*`statements`: Prioritizes all statements from a connection with available
95
+
high-priority tickets.
96
+
97
+
*`none`: Disables high-priority scheduling. All connections go to the
98
+
low-priority queue.
99
+
100
+
101
+
102
+
### Static configuration
103
+
104
+
To set the variable persistently, add the following to your `my.cnf` file:
105
+
106
+
```ini
107
+
[mysqld]
108
+
thread_pool_high_prio_mode = transactions
109
+
```
110
+
111
+
### Dynamic configuration
60
112
61
-
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.
113
+
You can also change this setting at runtime without restarting:
62
114
63
-
The thread pool adds the connection to the high-priority queue and decrements the ticket if the connection has the following attributes:
115
+
```
116
+
mysql> SET GLOBAL thread_pool_high_prio_mode = 'transactions';
117
+
```
64
118
65
-
* Has an open transaction
119
+
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:
66
120
67
-
*Has a non-zero number of high-priority tickets
121
+
*Restart the server, or
68
122
69
-
Otherwise, the variable adds the connection to the low-priority queue with the initial value.
123
+
* Have connected clients disconnect and reconnect manually.
70
124
71
-
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.
125
+
This dynamic adjustment enables fine-tuning thread scheduling behavior in production systems without downtime.
72
126
73
-
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.
74
127
75
-
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
76
128
77
129
## Low-priority queue throttling
78
130
@@ -123,6 +175,28 @@ This variable can limit the time an idle thread should wait before exiting.
| Limited benefit at low loads | Thread pool offers marginal gains below ~512–1000 connections. | Use default threading for small workloads. Evaluate before enabling. |
330
+
| No effect on existing sessions | Dynamic changes only affect new connections. | Prompt clients to reconnect or plan for a rolling restart. |
331
+
| Long-running query contention | Extended queries block worker threads, reducing throughput. | Isolate long-running queries to separate servers or use query timeouts. |
332
+
| Thread starvation risk | High-priority queues may crowd out low-priority connections. | Monitor queue activity; balance ticket settings and connection patterns. |
333
+
| Complexity in tuning | Poor variable configuration can degrade performance. | Test settings in staging; tune iteratively based on observed behavior. |
334
+
| Limited monitoring | Native tools offer minimal queue and saturation visibility. | Integrate with monitoring systems (e.g., PMM, Prometheus) for better insight. |
335
+
| Static design | Not a plugin; cannot be toggled dynamically. | Decide at deployment; changes require a configuration update and restart. |
0 commit comments