CPU

CPU

The CPU procedure is used to change the values stored in the read-only !CPU system variable, which in turn controls the way IDL uses the system processor or processors.

Note

Not all routines are affected by changes to the !CPU system variable. Those routines that are affected can override some of the values in the !CPU system variable by setting thread pool keywords, which change the way IDL uses the system processor(s) during a single invocation of the routine. A list of thread pool keywords appears at the end of the keywords list for each routine that is affected by the state of the !CPU system variable.

Syntax

CPU [, /RESET] [, RESTORE = structure] [,TPOOL_MAX_ELTS = NumMaxElts] [,TPOOL_MIN_ELTS = NumMinElts] [,TPOOL_NTHREADS = NumThreads] [,/VECTOR_ENABLE]

Arguments

None.

Keywords

RESET

Set this keyword to cause the CPU procedure to reset the values contained in the !CPU system variable to the values it had when IDL was started. See Restoring !CPU Values for more information on this topic. The RESET and RESTORE keywords are mutually exclusive; only one of them can be specified in a given call to CPU.

RESTORE

Set this keyword equal to a structure of type !CPU to set the !CPU system variable with the values contained in the structure. See Restoring !CPU Values for more information on this topic. The RESET and RESTORE keywords are mutually exclusive; only one of them can be specified in a given call to CPU.

TPOOL_MAX_ELTS

This keyword changes the value returned by !CPU.TPOOL_MAX_ELTS.

Set this keyword to a non-zero value to set the maximum number of data elements involved in a computation that uses the thread pool. If the number of elements in the computation exceeds the number contained in !CPU.TPOOL_MAX_ELTS, IDL will not use the thread pool for the computation. Setting this value to 0 removes any limit on maximum number of elements, and any computation with at least !CPU.TPOOL_MIN_ELTS will use the thread pool.

See Possible Drawbacks to the Use of the IDL Thread Pool for discussion of the circumstances under which it may be useful to specify a maximum number of elements for computations that use the thread pool.

TPOOL_MIN_ELTS

This keyword changes the value returned by !CPU.TPOOL_MIN_ELTS.

Set this keyword to a non-zero value to set the minimum number of data elements involved in a computation that uses the thread pool. If the number of elements in the computation is less than the number contained in !CPU.TPOOL_MIN_ELTS, IDL will not use the thread pool for the computation. Use this keyword to prevent IDL from using the thread pool on tasks that are too small to benefit from it.

See Possible Drawbacks to the Use of the IDL Thread Pool for discussion of the circumstances under which it may be useful to specify a minimum number of elements for computations that use the thread pool.

TPOOL_NTHREADS

This keyword changes the value returned by !CPU.TPOOL_NTHREADS.

Set this keyword to the number of threads IDL should use when performing computations that take advantage of the thread pool. By default, IDL will use !CPU.HW_NCPU threads, so that each thread will have the potential to run in parallel with the others. Set this keyword equal to 0 (zero) to ensure that !CPU.HW_NCPU threads will be used. Set this keyword equal to 1 (one) to disable use of the thread pool.

Note

For numerical computation, there is no benefit to using more threads than your system has CPUs. However, depending on the size of the problem and the number of other programs running on the system, there may be a performance advantage to using fewer CPUs. See Possible Drawbacks to the Use of the IDL Thread Pool for a discussion of the circumstances under which using fewer than the maximum number of CPUs makes sense.

If the IDL_CPU_TPOOL_NTHREADS environment variable has been set, then !CPU.TPOOL_NTHREADS is initialized with this value at startup. On systems shared by multiple users, you may wish to set this environment variable so that IDL uses the specified number of threads instead of defaulting to the number of CPUs present in the underlying hardware. For more information, see IDL_CPU_TPOOL_NTHREADS.

VECTOR_ENABLE

This keyword changes the value returned by !CPU.VECTOR_ENABLE.

Set this keyword to enable use of the system's vector unit (e.g. Macintosh Altivec/Velocity Engine) if one is present. Set this keyword equal to 0 (zero) explicitly disable such use. This keyword is ignored if the current system does not support a vector unit (that is, if !CPU.HW_VECTOR =0).

Restoring !CPU Values

It is sometimes necessary to alter the way IDL uses the system processor or processors for a section of code, and then to restore IDL to the settings in effect before the code section was executed. It is often possible to accomplish this using the thread pool keywords to specific routines; in some circumstances, however, this approach may be inconvenient or ineffective. For example:

If the section of code includes many routines for which alterations are required, the repetition of the keywords is inconvenient and error prone.

Binary and unary operators that use the thread pool do not accept keywords.

There is no keyword equivalent to the !CPU.VECTOR_ENABLE field.

Future versions of IDL may provide additional CPU options; adding keywords to your code to invoke these options could pose maintenance problems.

You may be working with IDL routines you did not write.

In all of these cases, the answer is to use the CPU procedure to alter the value of the !CPU system variable to suit the needs of your code, execute the code, and then reset !CPU to the state it had initially. It is possible to do this by using the individual keywords to CPU, as shown below:

save_cpu = !CPU               ; Save the current configuration 
CPU, TPOOL_NTHREADS=2, ...    ; Change the current configuration 
...                           ; Carry out a computation 
; Restore the CPU state 
CPU, TPOOL_MAX_ELTS=save_cpu.tpool_max_elts, $ 
   TPOOL_MIN_ELTS=save_cpu.tpool_min_elts, $ 
   TPOOL_NTHREADS=save_cpu.tpool_nthreads

There are two obvious problems with this approach: it is tedious and error prone, and if new versions of IDL add new CPU attributes, your code will require updates in order to reset them.

The RESTORE keyword to CPU solves both of these problems. When a structure of type !CPU is supplied using the RESTORE keyword, IDL adjusts the !CPU system variable to match the structure. Using RESTORE, the above example becomes:

save_cpu = !CPU 
CPU, TPOOL_NTHREADS=2, ... 
... 
CPU, RESTORE=save_cpu

The RESET keyword is similar to RESTORE, but it resets the !CPU system variable to the values it had when IDL first started. The syntax is:

CPU, /RESET

The RESET keyword is useful in ad hoc analysis, when you've made changes to the !CPU system variable manually (perhaps as an experiment), and you wish to bring !CPU back to its default state for your machine without exiting and restarting IDL.

RESET and RESTORE are mutually exclusive - only one of them can be used in a given call to the CPU procedure. However, they are allowed in conjunction with the other keywords to CPU. In such cases, the explicit keywords take precedence over the values from the RESET or RESTORE keywords. For example, the following statement changes the number of threads used by the IDL thread pool to 3, and sets all other CPU parameters to the values contained in a variable named save_cpu:

CPU, TPOOL_NTHREADS=3, RESTORE=save_cpu

Example

Configure !CPU so that by default, IDL will use two threads for computations that involve more than 5000 data values.

CPU, TPOOL_MIN_ELTS=5000, TPOOL_NTHREADS=2

Version History

Introduced: 5.5

RESET and RESTORE keywords: 6.1

CPU