Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 3/22/2024
Public

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

Document Table of Contents

Threading Control

Intel® oneAPI Math Kernel Library (oneMKL) provides functions for OpenMP* threading control, discussed in this section.

IMPORTANT:

If Intel® oneAPI Math Kernel Library (oneMKL) operates within the Intel® Threading Building Blocks (Intel® TBB) execution environment, the environment variables for OpenMP* threading control, such asOMP_NUM_THREADS, and Intel® oneAPI Math Kernel Library (oneMKL) functions discussed in this section have no effect. If the Intel TBB threading technology is used, control the number of threads through the Intel TBB application programming interface. Read the documentation for the tbb::task_scheduler_init class at https://www.threadingbuildingblocks.org/docs/doxygen/a00150.html to find out how to specify the number of Intel TBB threads.

If Intel® oneAPI Math Kernel Library (oneMKL) operates within an OpenMP* execution environment, you can control the number of threads for Intel® oneAPI Math Kernel Library (oneMKL) using OpenMP* runtime library routines and environment variables (see the OpenMP* specification for details). Additionally Intel® oneAPI Math Kernel Library (oneMKL) providesoptionalthreading control functions and environment variables that enable you to specify the number of threads for Intel® oneAPI Math Kernel Library (oneMKL) and to control dynamic adjustment of the number of threadsindependentlyof the OpenMP* settings. The settings made with the Intel® oneAPI Math Kernel Library (oneMKL) threading control functions and environment variables do not affect OpenMP* settings but take precedence over them.

If functions are used, Intel® oneAPI Math Kernel Library (oneMKL) environment variables may control Intel® oneAPI Math Kernel Library (oneMKL) threading. For details of those environment variables, see the Intel® oneAPI Math Kernel Library (oneMKL) Developer Guide.

You can specify the number of threads for Intel® oneAPI Math Kernel Library (oneMKL) function domains with the mkl_set_num_threads or mkl_domain_set_num_threads function. While mkl_set_num_threads specifies the number of threads for the entire Intel® oneAPI Math Kernel Library (oneMKL), mkl_domain_set_num_threads does it for a specific function domain. The following table lists the function domains that support independent threading control. The table also provides named constants to pass to threading control functions as a parameter that specifies the function domain.

oneMKL Function Domains

Function Domain

Named Constant

Basic Linear Algebra Subroutines (BLAS)

MKL_DOMAIN_BLAS

Fast Fourier Transform (FFT) functions, except Cluster FFT functions

MKL_DOMAIN_FFT

Vector Math (VM) functions

MKL_DOMAIN_VML

Parallel Direct Solver (PARDISO) functions

MKL_DOMAIN_PARDISO

All Intel® oneAPI Math Kernel Library (oneMKL) functions except the functions from the domains where the number of threads is set explicitly.

MKL_DOMAIN_ALL

WARNING:

Do not increase the number of OpenMP threads used for cluster_sparse_solver between the first call and the factorization or solution phase. Because the minimum amount of memory required for out-of-core execution depends on the number of OpenMP threads, increasing it after the initial call can cause incorrect results.

Both mkl_set_num_threads and mkl_domain_set_num_threads functions set the number of threads for all subsequent calls to Intel® oneAPI Math Kernel Library (oneMKL) from all applications threads. Use themkl_set_num_threads_local function to specify different numbers of threads for Intel® oneAPI Math Kernel Library (oneMKL) on different execution threads of your application. The thread-local settings take precedence over the global settings. However, the thread-local settings may have undesirable side effects (see the description of themkl_set_num_threads_local function for details).

By default, Intel® oneAPI Math Kernel Library (oneMKL) canadjust the specified number of threads dynamically. For example, Intel® oneAPI Math Kernel Library (oneMKL) may use fewer threads if the size of the computation is not big enough or not create parallel regions when running within an OpenMP* parallel region. Although Intel® oneAPI Math Kernel Library (oneMKL) may actually use a different number of threads from the number specified, the library does not create parallel regions with more threads than specified. If dynamic adjustment of the number of threads is disabled, Intel® oneAPI Math Kernel Library (oneMKL) attempts to use the specified number of threads in internal parallel regions (for more information, see the Intel® oneAPI Math Kernel Library (oneMKL) Developer Guide). Use the mkl_set_dynamic function to control dynamic adjustment of the number of threads.