Attributes for CmtGetThreadPoolAttribute and CmtSetThreadPoolAttribute

This topic describes the attributes that you can use with the multithreading functions CmtGetThreadPoolAttribute and CmtSetThreadPoolAttribute:

Thread Stack Size ATTR_TP_THREAD_STACK_SIZE
Thread Security ATTR_TP_THREAD_SECURITY
Process Events While Waiting ATTR_TP_PROCESS_EVENTS_WHILE_WAITING
Thread Priority ATTR_TP_THREAD_PRIORITY
Maximum Number of Threads ATTR_TP_MAX_NUM_THREADS
Number of Threads ATTR_TP_NUM_THREADS
Number of Active Threads ATTR_TP_NUM_ACTIVE_THREADS

ATTR_TP_MAX_NUM_THREADS

Type: int

Description: This attribute specifies the maximum number of threads in the pool. You cannot reduce the maximum number of threads in the pool.

It is recommended that you either use a fixed number of threads or make the maximum number of threads proportional to the number of processors. For example, the maximum number or threads in the default thread pool is 2 + (2 * (number of processors)). You can use the function CmtGetNumberOfProcessors to determine the number of processors at run-time.

Pass UNLIMITED_THREAD_POOL_THREADS to indicate no limit on the maximum number of threads. In general, this is not recommended because too many threads in a process can result in poor program performance.

ATTR_TP_NUM_ACTIVE_THREADS

Type: int

Restrictions: Not settable.

Description: This attribute specifies the number of threads in the pool that are currently executing functions.

ATTR_TP_NUM_THREADS

Type: int

Restrictions: Not settable.

Description: This attribute specifies the current number of threads in the pool.

ATTR_TP_PROCESS_EVENTS_WHILE_WAITING

Type: int

Description: This attribute specifies whether the threads in the pool process events while they are idle. Any thread that creates a panel or window and does not destroy it must process events while it is idle. Failure to do so could cause the system to hang.

Note    It is not always obvious when a window is created. Various CVI and Windows SDK functions create hidden windows. For example, the operating system uses hidden windows to communicate between certain kinds of ActiveX servers and clients.

You cannot set this attribute after the first thread in the pool has been created by a call to CmtScheduleThreadPoolFunction, CmtScheduleThreadPoolFunctionAdv, or CmtPreAllocThreadPoolThreads.

Values: Name Value
FALSE 0
TRUE 1

ATTR_TP_THREAD_PRIORITY

Type: int

Description: This attribute specifies the priority at which the threads in the pool run. Use CmtScheduleThreadPoolFunctionAdv to specify the priority at which a particular function is run.

Linux Thread priority is not supported on Linux. The only valid value for this attribute is THREAD_PRIORITY_NORMAL.

The actual priority of the thread is based on this value and the priority class of the process to which the thread belongs. You can set the priority class of a process with the SDK function SetPriorityClass.

Values: Name Value
THREAD_PRIORITY_TIME_CRITICAL 15
THREAD_PRIORITY_HIGHEST 2
THREAD_PRIORITY_ABOVE_NORMAL 1
THREAD_PRIORITY_NORMAL 0
THREAD_PRIORITY_BELOW_NORMAL -1
THREAD_PRIORITY_LOWEST -2
THREAD_PRIORITY_IDLE -15

ATTR_TP_THREAD_SECURITY

Type: SECURITY_ATTRIBUTES *

Description: This attribute specifies the security attributes for threads in the thread pool. The security attributes are applied to each thread when it is created. You can use the security attributes to specify that a thread handle can be inherited by child processes. Pass NULL to specify that child processes cannot inheret thread handles and to use the default security for the threads. The SECURITY_ATTRIBUTES structure is defined in <windows.h>. Include <windows.h> in your source files that use this SECURITY_ATTRIBUTES. See the SDK documentation for more information about the contents of the SECURITY_ATTRIBUTES structure.

You cannot set this attribute after the first thread in the pool has been created by a call to CmtScheduleThreadPoolFunction, CmtScheduleThreadPoolFunctionAdv, or CmtPreAllocThreadPoolThreads.

ATTR_TP_THREAD_STACK_SIZE

Type: unsigned int

Description: This attribute specifies the suggested initial commit size, in bytes, of the stack for the threads in the pool. The system rounds this number to the nearest page. If this value is 0 or smaller than the default commit size, the size of the creating thread's stack is used instead of this value.

You cannot set this attribute after the first thread in the pool has been created by a call to CmtScheduleThreadPoolFunction, CmtScheduleThreadPoolFunctionAdv, or CmtPreAllocThreadPoolThreads.