sklam · Oct 5, 2021 · Jul 22, 2021 · Jul 22, 2021 · Jul 22, 2021 · Jul 22, 2021
diff --git a/docs/source/reference/envvars.rst b/docs/source/reference/envvars.rst
@@ -527,3 +527,15 @@ Threading Control
    * ``tbb`` - A threading layer backed by Intel TBB.
    * ``omp`` - A threading layer backed by OpenMP.
    * ``workqueue`` - A simple built-in work-sharing task scheduler.
+
+   .. envvar:: NUMBA_THREADING_LAYER_PRIORITY
+
+   This environment variable controls the priority of searching for
+   library used for concurrent execution
+   for the CPU parallel targets (``@vectorize(target='parallel')``,
+   ``@guvectorize(target='parallel')``  and ``@njit(parallel=True)``). The
+   variable type is string and by default is ``tbb omp workqueue`` which
+   prioritize the order of searching
+   threading layer based on what is available in the runtime. The valid values
+   are any permutation of the 3 choices (for more information about these see
+   :ref:`the threading layer documentation <numba-threading-layer>`).
diff --git a/docs/source/user/threading-layer.rst b/docs/source/user/threading-layer.rst
@@ -59,6 +59,21 @@ choosing a threading layer, the first is by selecting a threading layer that is
 safe under various forms of parallel execution, the second is through explicit
 selection via the threading layer name (e.g. ``tbb``).
 
+Setting the threading layer priority
+------------------------------------
+
+By default, The threading layers are searched in the order of
+'tbb', 'omp', and 'workqueue'.
+If you want to let Numba choice the threading layer
+based on availability automatically but with a different priority,
+it can be changed via the environment variable
+``NUMBA_THREADING_LAYER_PRIORITY`` or through assignment to
+``numba.config.THREADING_LAYER_PRIORITY``.
+
+For example, if you want Numba to choose ``omp`` first if available,
+then ``tbb`` and so on, you can set either
+``NUMBA_THREADING_LAYER_PRIORITY="omp tbb workqueue"`` or
+``numba.config.THREADING_LAYER_PRIORITY = ["omp", "tbb", "workqueue"]``.
 
 Selecting a threading layer for safe parallel execution
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/numba/core/config.py b/numba/core/config.py
@@ -306,6 +306,11 @@ def avx_default():
         DISABLE_JIT = _readenv("NUMBA_DISABLE_JIT", int, 0)
 
         # choose parallel backend to use
+        THREADING_LAYER_PRIORITY = _readenv(
+            "NUMBA_THREADING_LAYER_PRIORITY",
+            lambda string: string.split(),
+            ['tbb', 'omp', 'workqueue'],
+        )
         THREADING_LAYER = _readenv("NUMBA_THREADING_LAYER", str, 'default')
 
         # CUDA Configs

diff --git a/numba/np/ufunc/parallel.py b/numba/np/ufunc/parallel.py
@@ -422,7 +422,14 @@ def select_from_backends(backends):
                 return lib, backend
 
             t = str(config.THREADING_LAYER).lower()
-            namedbackends = ['tbb', 'omp', 'workqueue']
+            namedbackends = config.THREADING_LAYER_PRIORITY
+            if set(namedbackends) != {'tbb', 'omp', 'workqueue'}:
+                raise ValueError(
+                    "THREADING_LAYER_PRIORITY invalid: %s."
+                    "It must be a permutation of "
+                    "'tbb', 'omp', 'workqueue'"
+                    % namedbackends
+                )
 
             lib = None
             err_helpers = dict()

diff --git a/numba/tests/test_parallel_backend.py b/numba/tests/test_parallel_backend.py
@@ -521,6 +521,56 @@ def generate(cls):
 TestThreadingLayerSelection.generate()
 
 
+@skip_parfors_unsupported
+class TestThreadingLayerPriority(ThreadLayerTestHelper):
+
+    def each_env_var(self, env_var: str):
+        """Test setting priority via env var NUMBA_THREADING_LAYER_PRIORITY."""
+        env = os.environ.copy()
+        env['NUMBA_THREADING_LAYER'] = 'default'
+        env['NUMBA_THREADING_LAYER_PRIORITY'] = env_var
+
+        code = """import numba
+
+# trigger threading layer decision
+# hence catching invalid THREADING_LAYER_PRIORITY
+@numba.jit(
+    'float64[::1](float64[::1], float64[::1])',
+    nopython=True,
+    parallel=True,
+)
+def plus(x, y):
+    return x + y
+
+print(' '.join(numba.config.THREADING_LAYER_PRIORITY))
+"""
+        cmd = [
+            sys.executable,
+            '-c',
+            code,
+        ]
+        out, err = self.run_cmd(cmd, env=env)
+        self.assertEqual(out.strip(), env_var)
+
+    def test_valid_env_var(self):
+        import itertools
+
+        default = ['tbb', 'omp', 'workqueue']
+        for p in itertools.permutations(default):
+            env_var = ' '.join(p)
+            self.each_env_var(env_var)
+
+    def test_invalid_env_var(self):
+        env_var = 'tbb omp workqueue notvalidhere'
+        try:
+            self.each_env_var(env_var)
+        except AssertionError:
+            return
+        raise RuntimeError(
+            'Not catching invalid NUMBA_THREADING_LAYER_PRIORITY: %s' % env_var
+        )
+
+
 @skip_parfors_unsupported
 class TestMiscBackendIssues(ThreadLayerTestHelper):
     """