Processor Affinity Overview

Starting from version 3.5.27, it is possible to configure processor affinity for both the Wrapper process and its controlled JVM process.

Processor affinity enables you to specify that a process will only execute on designated Central Processing Units (CPUs) rather than on any CPU.

Each of the Wrapper process and the JVM process have their own properties to configure processor affinity, but if you only specify those of the Wrapper, by default the controlled JVM process will inherit the same configuration and automatically execute using the same CPU(s) as the Wrapper process.

NOTE

The ability to configure CPU affinity was added in version 3.5.27 for both Windows and Linux.
Since version 3.5.28, it is also possible to configure cpu affinity for AIX, FreeBSD, HP-UX and Solaris. However, it should be noted that on HP-UX and Solaris it is only possible to bind one CPU per process (the Wrapper or the JVM process).
Due to the fact that Mac OSX does not export interfaces to identify processors, it is currently not possible to implement process affinity on this system.
Processor affinity feature was not tested on systems with more than 64 logical processors.

The properties used to configure the processor affinity for the Wrapper process are described below:

wrapper.cpu_affinity.set (Required)
wrapper.cpu_affinity.default (Optional)
wrapper.cpu_affinity.<n> (At least one property is required)
wrapper.cpu_affinity.strict (Optional)

The properties used to configure the processor affinity for the JVM process are described below:

wrapper.java.cpu_affinity.set (Required)
wrapper.java.cpu_affinity.default (Optional)
wrapper.java.cpu_affinity.<n>
wrapper.java.cpu_affinity.strict (Optional)

<n> component:

The "<n>" component of the above properties is an integer number in the range of "1" to "256" and designating a specific CPU. It should be less than or equal to the actual number of CPUs present on the machine where the Wrapper will be executed.

NOTE

If you try to set CPU affinity at the system level (for example, from the task manager or from the command prompt), you may sometimes notice that the first CPU is assigned with the index 0. Actually, there is no standard that defines how CPUs should be indexed and some Operating Systems may start numbering them from 0 while others will start from 1. We decided to designate the first CPU with index 1 when configuring the Wrapper.

Processor Affinity properties for the Wrapper process

wrapper.cpu_affinity.set

Compatibility :	3.5.27
Editions :
Platforms :

Defines whether the processor affinity is enabled or disabled for the Wrapper. The default value is FALSE, meaning that the Wrapper will run on any CPUs.

Set the property to TRUE to turn on affinity setting at the Wrapper level.

Example:

wrapper.cpu_affinity.set=TRUE

wrapper.cpu_affinity.default

Compatibility :	3.5.27
Editions :
Platforms :

Set this property to TRUE to initially allow all CPUs to the Wrapper. Set it to FALSE to initially block all CPUs to the Wrapper. The default value is FALSE.

This property is intended to be overridden by at least one of the wrapper.cpu_affinity.<n> properties in order to create exception(s) for individual CPUs.

Example 1 (disable all CPU by default):

wrapper.cpu_affinity.default=FALSE

Example 2 (enable all CPU by default):

wrapper.cpu_affinity.default=TRUE

NOTE

If wrapper.cpu_affinity.default is set to TRUE but none of the wrapper.cpu_affinity.<n> properties are set to FALSE, this will have the same effect as if the processor affinity was turned off.

On the contrary, if wrapper.cpu_affinity.default is set to FALSE but none of the wrapper.cpu_affinity.<n> properties is set to TRUE, this will raise an exception because the Wrapper will not be allowed to run on any CPUs of the machine (see wrapper.cpu_affinity.strict).

wrapper.cpu_affinity.<n>

Compatibility :	3.5.27
Editions :
Platforms :

This set of properties is used to authorize or block individual CPUs to the Wrapper process. You can authorize/block one or several processors by adding one line per targeted CPU.

The "<n>" component of this property is an integer number counting up from "1" and designating a specific CPU. It should be less than or equal to the actual number of CPUs present on the machine where the Wrapper will be executed.

Example 1 (allows the Wrapper to run only on CPUs number 1 and 2):

wrapper.cpu_affinity.default=FALSE
wrapper.cpu_affinity.1=TRUE
wrapper.cpu_affinity.2=TRUE

Example 2 (prevent the Wrapper to run CPUs number 1 and 3):

wrapper.cpu_affinity.default=TRUE
wrapper.cpu_affinity.1=FALSE
wrapper.cpu_affinity.3=FALSE

NOTE

For HP-UX and Solaris, it is only possible to bind one CPU to the Wrapper. If the configuration is such that several CPUs are activated, the Wrapper will stop by default, or select the first active CPU if wrapper.cpu_affinity.strict was set to FALSE.

wrapper.cpu_affinity.strict

Compatibility :	3.5.27
Editions :
Platforms :

The default value of this property is TRUE, meaning that if the configuration properties of the Wrapper don't match the actual CPUs of the machine, the Wrapper will log the exceptions and eventually stop. To keep running without blocking on these exceptions, you can set wrapper.cpu_affinity.strict to FALSE. This will simply cause the Wrapper to log messages with a 'WARNING' status.

Example:

wrapper.cpu_affinity.strict=FALSE

WARNING

The exceptions can be the following:

Any of the CPUs defined with 'wrapper.cpu_affinity.<n>' was set to TRUE but it doesn't actually exist on the machine. By setting wrapper.cpu_affinity.strict=FALSE, the Wrapper will simply ignore the non-existent CPU(s).
The configuration is such as the Wrapper is not allowed to run on any CPUs of the machine. By setting wrapper.cpu_affinity.strict=FALSE, the Wrapper will execute on any CPUs of the machine (same as if the processor affinity was turned off).
For some reason, the operating system doesn't allow to allocate any of the specified CPUs. By setting wrapper.cpu_affinity.strict=FALSE, the Wrapper will execute on any CPUs of the machine (same as if the processor affinity was turned off).

Processor Affinity properties for the JVM process

wrapper.java.cpu_affinity.set

Compatibility :	3.5.27
Editions :
Platforms :

Defines whether the processor affinity is enabled or disabled for the JVM process. The default value is FALSE, meaning that the JVM process will run on any CPUs.

Set the property to TRUE to turn on affinity setting for the JVM.

Example:

wrapper.java.cpu_affinity.set=TRUE

wrapper.java.cpu_affinity.default

Compatibility :	3.5.27
Editions :
Platforms :

Set this property to TRUE to initially allow all CPUs to the JVM process. Set it to FALSE to initially block all CPUs to the JVM process. The default value is FALSE.

This property is intended to be overridden by at least one of the wrapper.cpu_affinity.<n> properties in order to create exception(s) for individual CPUs.

Example 1 (disable all CPU by default):

wrapper.java.cpu_affinity.default=FALSE

Example 2 (enable all CPU by default):

wrapper.java.cpu_affinity.default=TRUE

NOTE

If wrapper.java.cpu_affinity.default is set to TRUE but none of the wrapper.java.cpu_affinity.<n> properties are set to FALSE, this will cause the JVM process to run on any CPUs.

On the contrary, if wrapper.java.cpu_affinity.default is set to FALSE but none of the wrapper.java.cpu_affinity.<n> properties is set to TRUE, this will raise an exception because the JVM process will not be allowed to run on any CPUs of the machine (see wrapper.java.cpu_affinity.strict).

wrapper.java.cpu_affinity.<n>

Compatibility :	3.5.27
Editions :
Platforms :

This set of properties is used to authorize or block individual CPUs to the JVM process. You can authorize/block one or several processors by adding one line per targeted CPU.

Example 1 (allows the JVM process to run only on CPUs number 1 and 2):

wrapper.java.cpu_affinity.default=FALSE
wrapper.java.cpu_affinity.1=TRUE
wrapper.java.cpu_affinity.2=TRUE

Example 2 (prevent the JVM process to run CPUs number 1 and 3):

wrapper.java.cpu_affinity.default=TRUE
wrapper.java.cpu_affinity.1=FALSE
wrapper.java.cpu_affinity.3=FALSE

NOTE

For HP-UX and Solaris, it is only possible to bind one CPU to the JVM process. If the configuration is such that several CPUs are activated, the Wrapper will stop by default, or select the first active CPU if wrapper.java.cpu_affinity.strict was set to FALSE.

wrapper.java.cpu_affinity.strict

Compatibility :	3.5.27
Editions :
Platforms :

The default value of this property is TRUE meaning that if the configuration properties of the JVM process don't match the actual CPUs of the machine, the Wrapper will log the exceptions and eventually stop. To keep running without blocking on these exceptions, you can set wrapper.java.cpu_affinity.strict to FALSE. This will simply cause the Wrapper to log messages with a 'WARNING' status.

Example:

wrapper.java.cpu_affinity.strict=FALSE

WARNING

The exceptions can be the following:

Any of the CPUs defined with 'wrapper.java.cpu_affinity.<n>' was set to TRUE but it doesn't actually exist on the machine. By setting wrapper.java.cpu_affinity.strict=FALSE, the Wrapper will simply ignore the non-existent CPU(s).
The configuration is such as the Wrapper is not allowed to run on any CPUs of the machine. By setting wrapper.java.cpu_affinity.strict=FALSE, the JVM process will execute on any CPUs of the machine.
For some reason, the Operating System doesn't allow to allocate any of the specified CPUs. By setting wrapper.java.cpu_affinity.strict=FALSE, the JVM process will execute on any CPUs of the machine.

Processor Affinity Overview

NOTE

NOTE

Processor Affinity properties for the Wrapper process

wrapper.cpu_affinity.set

wrapper.cpu_affinity.default

NOTE

wrapper.cpu_affinity.<n>

NOTE

wrapper.cpu_affinity.strict

WARNING

Processor Affinity properties for the JVM process

wrapper.java.cpu_affinity.set

wrapper.java.cpu_affinity.default

NOTE

wrapper.java.cpu_affinity.<n>

NOTE

wrapper.java.cpu_affinity.strict

WARNING

Configuration Properties:

Debugging:

Help Pages:

Currently logged on:

Customers