agent_stack_sz - Agent stack size configuration parameter

Configuration type

Database manager

Applies to

• Database server with local and remote clients
• Database server with local clients
• Partitioned database server with local and remote clients

Parameter type

Configurable

Default [range]

Linux (32-bit)

256 [16 - 1024]

Linux (64-bit) and UNIX

1024 [256 - 32768]

Windows

16 [8 - 1000]

Note: The default value is subject to change by the DB2 Configuration Advisor after initial database creation.

Unit of measure

Pages (4 KB)

When allocated

On Linux and UNIX operating systems, stack space (process virtual memory) is allocated as needed or reused in the main DB2 server process when a thread is created. Stack memory is used or committed as necessary.

On Windows operating systems, agent_stack_sz represents the initial committed stack memory when a thread is created. Additional stack memory is used or committed as necessary.

When freed

On Linux and UNIX operating systems, stack space (process virtual memory) is retained for reuse when threads terminate and are freed when the DB2 server shuts down.

On Windows operating systems, stack space and memory are freed when a thread terminates.

On Linux and UNIX operating systems, agent_stack_sz is rounded up to the next largest power-of-2 based value. The default settings should be sufficient for most workloads.

On Windows operating systems, the agent_stack_sz configuration parameter is used to set the initial committed stack size for each agent. Regardless of the setting, each agent stack can grow to the minimum reserved stack size of 256 KB on 32-bit versions of Windows and 2 MB on 64-bit versions of Windows. If you exceed the minimum reserved stack size, the agent stack might run out of space and return an error.

Windows operating systems use the concepts of a "reserved" stack, which is the maximum to which the stack can grow, and the "committed" stack, which is the amount of memory committed to the stack when it is created. In addition, a guard page is added to the specified committed stack size in order to determine the minimum reserved stack space required. For example, with agent_stack_sz (committed stack) set to 16, one (1) guard page is added. This means that the reserved stack size must be at least 17 pages. The maximum, or reserved, agent stack size can be increased by setting the agent_stack_sz configuration parameter, which determines the size of the committed stack, to a value that results in a minimum reserved stack size larger than the default reserve stack size of 64 pages. Note that Windows operating systems use multiples of 1 MB for setting reserved stack sizes greater than 256 KB. For example, on 32-bit Windows operating systems, setting the agent_stack_sz configuration parameter to a value within the range of 64 - 255 4-KB pages results in a maximum stack usage of 1 MB because (64 * 4 KB) + 4 KB guard page = 260 KB. This exceeds the 256 KB threshold so the value is rounded up to 1 MB for the reserved stack area. If you set the agent_stack_sz configuration parameter to 255, then the size of the reserved stack is (255 * 4 KB) + 4 KB guard page = 1024 KB, making 255 the maximum setting before exceeding the 1 MB threshold.

You can change the default reserve stack size by using the db2hdr utility to change the header information for the db2syscs.exe file. The advantage of changing the default reserved stack size using the db2hdr utility is that it provides a finer granularity, therefore allowing you to set the stack size to be a minimum required stack size. This conserves virtual address space on 32-bit Windows. However, you must restart DB2 for a change to the db2syscs.exe process to take effect, and this method must be repeated with any Fix Pack upgrade.

Recommendations:

If you are working with large or complex XML data in a 32-bit Windows operating system, you should update the value of agent_stack_sz to at least 64 4-KB pages. Complex XML schemas might require the value of agent_stack_sz to be much higher during schema registration or during XML document validation.

This limit is sufficient for most database operations.

Notes

• Agent stack memory does not count towards instance memory usage.
• While agent_stack_sz can be configured with a high stack space allocation for maximum usage, on average, only a small amount of allocated stack space is used by a thread. It is only this smaller amount which requires system memory.
• On HP-UX operating systems, thread stack space requires a swap reservation. The approximate total swap requirement is equal to:

  Peak number of threads * agent_stack_sz

  The value of agent_stack_sz in this calculation is rounded up to the next highest power-of-2 value.