Help Center> GaussDB> Distributed_8.x> Configuring Running Parameters> GUC Parameters> Thread Pool
Updated on 2024-06-03 GMT+08:00
View PDF

Thread Pool

enable_thread_pool

Parameter description: Specifies whether to enable the thread pool function. This is a POSTMASTER parameter. Set it based on instructions provided in Table 1. You are advised to disable this parameter in performance-sensitive scenarios with low-concurrency and persistent connection and enable this parameter in other scenarios.

Value range: Boolean

  • on indicates that the thread pool function is enabled.
  • off indicates that the thread pool function is disabled.

Default value: on

thread_pool_attr

Parameter description: Specifies the detailed attributes of the thread pool function. This parameter is valid only when enable_thread_pool is set to on. Only the sysadmin user can access this parameter.

Parameter type: string.

Unit: none

Value range:

This parameter consists of three parts: 'thread_num', 'group_num', and 'cpubind_info'. The meanings of the three parts are as follows:

  • thread_num is the total number of initial threads in the thread pool, which can be dynamically expanded. The value ranges from 0 to 4096. The value 0 indicates that the database automatically configures the number of threads in the thread pool based on the number of CPU cores. If the value is greater than 0, the number of threads in the thread pool is the same as the value of thread_num. You are advised to set the thread pool size based on the hardware configuration. The formula is as follows: Value of thread_num = Number of CPU cores x 3–5. The maximum value of thread_num is 4096.
  • group_num indicates the number of thread groups in the thread pool. The value ranges from 0 to 64. The value 0 indicates that the database automatically configures the number of thread groups in the thread pool based on the number of NUMA groups. If the value is greater than 0, the number of thread groups in the thread pool is the same as the value of group_num.
  • cpubind_info specifies whether the thread pool is bound to a core. The available configuration modes are as follows: 1. '(nobind)': The thread is not bound to a core. 2. '(allbind)': Use all CPU cores that can be queried in the current system to bind threads. 3. '(nodebind: 1, 2)': Use the CPU cores in NUMA groups 1 and 2 to bind threads. 4. '(cpubind: 0-30)': Use CPU cores 0 to 30 to bind threads. 5. '(numabind: 0-30)': Use CPU cores 0 to 30 in the NUMA group to bind threads. This parameter is case-insensitive.

Default value:

  • Independent deployment: '1024,2,(nobind)' (60-core CPU/480 GB memory and 32-core CPU/256 GB memory); '512,2,(nobind)' (16-core CPU/128 GB memory); '256,2,(nobind)' (8-core CPU/64 GB memory); '128,2,(nobind)' (4-core CPU/32 GB memory); '64,2,(nobind)' (4-core CPU/16 GB memory)

Setting method: This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Setting suggestion: When the memory is sufficient and the CPU performance is good, increase the value of this parameter if the service requires more connections.

static_thread_pool_num

Parameter description: Specifies the number of threads used to create a static thread pool (static pool). This parameter takes effect only on distributed CNs after enable_thread_pool is enabled. This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Value range: an integer ranging from 0 to 1024.

Default value: 3

CN default value: 10% x group_num x thread_num. For details about group_num and thread_num, see thread_pool_attr. In actual configuration, the sum of thread_num and static_thread_pool_num is no more than the value of min (4096, max_connections) and the value of static_thread_pool_num is no less than the number of DN shards multiplied by the value of group_num.

Example: static_thread_pool_num = 10% x 1024 x 2 = 204

  • A static thread pool is created to prevent DNs from exhausting threads of the CN thread pool and ensure that available threads are connected to DNs to execute services.
  • Ensure that the sum of thread_pool_attr and static_thread_pool_num must be no more than the value of min(4096, max_connections). Otherwise, the static pool cannot be created. Also, the value of static_thread_pool_num must be greater than the number of DN shards multiplied by the value of group_num.
  • static_thread_pool_num is a virtual value and does not take effect immediately after being set. When the CN thread pool is fully loaded or exhausted, the CN creates a number of threads specified by static_thread_pool_num. These threads make up a static pool.
  • The CN static pool is used for single-DN connection services and evenly allocates threads to each DN shard in the cluster. The calculation formula is as follows: static_thread_pool_num/n (n indicates the number of DN shards). If the number of threads used exceeds the calculated fixed quota, an error is reported.
  • If the static pool thread is held by the multi-DN connection service, an error is reported and the threads are returned.
  • Non default thread groups cannot be created in a static pool in multi-tenant mode.
  • If static_thread_pool_num is set to 0, the static pool function is disabled. If you do not want the static pool to control multiple DN connections, disable this function.
  • Restrictions on creating a static thread pool: The prerequisite is that the thread pool is enabled on the distributed CN. The current function resolves DN shard faults and ensures that the CN has available threads for services to ensure continuous services. If the design does not include the solution for the fully occupied thread pool due to single-CN query, querying services only on a single CN at the same time are not controlled or counted in statistics.

thread_pool_stream_attr

Parameter description: Specifies the detailed attributes of the stream thread pool function. This parameter is valid only when enable_thread_pool is set to on and only takes effect on DNs. Only the sysadmin user can access this parameter. This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Value range: a string, consisting of one or more characters.

This parameter consists of four parts: 'stream_thread_num, stream_proc_ratio, group_num, cpubind_info'. The meanings of the four parts are as follows:

  • stream_thread_num indicates the total number of threads in the stream thread pool. The value ranges from 0 to 4096. The value 0 indicates that the database automatically configures the number of threads in the thread pool based on the number of CPU cores. If the value is greater than 0, the number of threads in the thread pool is the same as the value of stream_thread_num. You are advised to set the thread pool size based on the hardware configuration. The formula is as follows: Value of stream_thread_num = Number of CPU cores x 3–5. The maximum value of stream_thread_num is 4096.
  • stream_proc_ratio indicates the ratio of proc resources reserved for stream threads. The value is a floating-point number. The default value is 0.2. The reserved proc resources are calculated as follows: Value of stream_proc_ratio x Value of stream_thread_num.
  • group_num indicates the number of thread groups in the thread pool. The value ranges from 0 to 64. The value 0 indicates that the database automatically configures the number of thread groups in the thread pool based on the number of NUMA groups. If the value is greater than 0, the number of thread groups in the thread pool is the same as the value of group_num. The value of group_num in thread_pool_stream_attr must be the same as that in thread_pool_attr. If they are set to different values, the value of group_num in thread_pool_attr is used.
  • cpubind_info specifies whether the thread pool is bound to a core. The available configuration modes are as follows: 1. '(nobind)': The thread is not bound to a core. 2. '(allbind)': Use all CPU cores that can be queried in the current system to bind threads. 3. '(nodebind: 1, 2)': Use the CPU cores in NUMA groups 1 and 2 to bind threads. 4. '(cpubind: 0-30)': Use CPU cores 0 to 30 to bind threads. 5. '(numabind: 0-30)': Use CPU cores 0 to 30 in the NUMA group to bind threads. This parameter is case-insensitive. The value of cpubind_info in thread_pool_stream_attr must be the same as that in thread_pool_attr. If they are set to different values, the value of cpubind_info in thread_pool_attr is used.

Default value:

stream_thread_num: 16

stream_proc_ratio: 0.2

group_num and cpubind_info: For details, see thread_pool_attr.

resilience_threadpool_reject_cond

Parameter description: Specifies the percentage of thread pool usage for escape from overload. This parameter takes effect only when the GUC parameters enable_thread_pool and use_workload_manager are enabled. This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Value range: a string, consisting of one or more characters.

This parameter consists of recover_threadpool_percent and overload_threadpool_percent. The meanings of the two parts are as follows:

  • recover_threadpool_percent: specifies the thread pool usage when the thread pool recovers to the normal state. When the thread pool usage is less than the value of this parameter, the escape from overload function is disabled and new connections are allowed. The value ranges from 0 to INT_MAX. The value indicates a percentage.
  • overload_threadpool_percent: specifies thread pool usage when the thread pool is overloaded. If the thread pool usage is greater than the value of this parameter, the current thread pool is overloaded. In this case, the escape from overload function is enabled to kill sessions and forbid new connections. The value ranges from 0 to INT_MAX. The value indicates a percentage.

Default value: '0,0', indicating that the thread pool escape function is disabled.

Example:

resilience_threadpool_reject_cond = '50,90'

When the thread pool usage exceeds 90%, new connections are forbidden and stacked sessions are killed. When the thread pool usage decreases to 50%, session killing is stopped and new connections are allowed.

  • The thread pool usage can be queried in the DBE_PERF.local_threadpool_status view. The initial number of threads in the thread pool can be obtained by querying the thread_pool_attr parameter.
  • If this parameter is set to a small value, the thread pool escape from overload process is frequently triggered. As a result, ongoing sessions are forcibly logged out, and new connections fail to be connected for a short period of time. Therefore, exercise caution when setting this parameter based on the actual thread pool usage.
  • If the use_workload_manager parameter is disabled and the bypass_workload_manager parameter is enabled, this parameter also takes effect. The bypass_workload_manager parameter is of the SIGHUP type; therefore, after the reload mode is set, you need to restart the database for the setting to take effect.
  • The values of recover_threadpool_percent and overload_threadpool_percent can be 0 at the same time. In addition, the value of recover_threadpool_percent must be smaller than that of overload_threadpool_percent. Otherwise, the setting does not take effect.
Parent topic: GUC Parameters