Developer Guide

Developer Guide for Intel® oneAPI Math Kernel Library Windows*

ID 766692
Date 11/07/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

Techniques to Set the Number of Threads

Use the following techniques to specify the number of OpenMP threads to use in Intel® oneAPI Math Kernel Library (oneMKL):

  • Set one of the OpenMP or Intel® oneAPI Math Kernel Library (oneMKL) environment variables:
    • OMP_NUM_THREADS
    • MKL_NUM_THREADS
    • MKL_DOMAIN_NUM_THREADS
  • Call one of the OpenMP or Intel® oneAPI Math Kernel Library (oneMKL) functions:
    • omp_set_num_threads()
    • mkl_set_num_threads()
    • mkl_domain_set_num_threads()
    • mkl_set_num_threads_local()
NOTE:

A call to the mkl_set_num_threads or mkl_domain_set_num_threadsfunction changes the number of OpenMP threads available to all in-progress calls (in concurrent threads) and future calls to Intel® oneAPI Math Kernel Library (oneMKL) and may result in slow Intel® oneAPI Math Kernel Library (oneMKL) performance and/or race conditions reported by run-time tools, such as Intel® Inspector.

To avoid such situations, use the mkl_set_num_threads_local function (see the "Support Functions" section in the Intel® oneAPI Math Kernel Library (oneMKL) Developer Reference for the function description).

When choosing the appropriate technique, take into account the following rules:

  • The Intel® oneAPI Math Kernel Library (oneMKL) threading controls take precedence over the OpenMP controls because they are inspected first.
  • A function call takes precedence over any environment settings. The exception, which is a consequence of the previous rule, is that a call to the OpenMP subroutine omp_set_num_threads()does not have precedence over the settings of Intel® oneAPI Math Kernel Library (oneMKL) environment variables such asMKL_NUM_THREADS. See Using Additional Threading Control for more details.
  • You cannot change run-time behavior in the course of the run using the environment variables because they are read only once at the first call to Intel® oneAPI Math Kernel Library (oneMKL).

If you use the Intel TBB threading technology, read the documentation for the tbb::task_scheduler_init class at https://www.threadingbuildingblocks.org/documentation to find out how to specify the number of threads.