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,14 @@ 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 order in which the libraries used for
+   concurrent execution, for the CPU parallel targets
+   (``@vectorize(target='parallel')``, ``@guvectorize(target='parallel')``
+   and ``@njit(parallel=True)``), are prioritized for use. The variable type is
+   string and by default is ``tbb omp workqueue``, with the priority taken based
+   on position from the left of the string, left most being the highest. Valid
+   values are any permutation of the three 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,25 @@ 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 selection priority
+----------------------------------------------
+
+By default the threading layers are searched in the order of ``'tbb'``,
+``'omp'``, then ``'workqueue'``. To change this search order whilst
+maintaining the selection of a threading layer based on availability, the
+environment variable :envvar:`NUMBA_THREADING_LAYER_PRIORITY` can be used.
+
+Note that it can also be set via
+:py:data:`numba.config.THREADING_LAYER_PRIORITY`.
+Similar to :py:data:`numba.config.THREADING_LAYER`,
+it must occur logically before any Numba based
+compilation for a parallel target has occurred.
+
+For example, to instruct Numba to choose ``omp`` first if available,
+then ``tbb`` and so on, set the environment variable as
+``NUMBA_THREADING_LAYER_PRIORITY="omp tbb workqueue"``.
+Or programmatically,
+``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,15 @@ def select_from_backends(backends):
                 return lib, backend
 
             t = str(config.THREADING_LAYER).lower()
-            namedbackends = ['tbb', 'omp', 'workqueue']
+            namedbackends = config.THREADING_LAYER_PRIORITY
+            if not (len(namedbackends) == 3 and
+                    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
@@ -4,6 +4,7 @@
 Tests the parallel backend
 """
 import faulthandler
+import itertools
 import multiprocessing
 import os
 import random
@@ -521,6 +522,80 @@ 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.
+
+        :return: threading_layer_priority, stderr
+            (containing ``@threading_layer@``)
+        """
+        env = os.environ.copy()
+        env['NUMBA_THREADING_LAYER'] = 'default'
+        env['NUMBA_THREADING_LAYER_PRIORITY'] = env_var
+
+        code = """import sys
+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))
+print("@%s@" % numba.threading_layer(), file=sys.stderr)
+"""
+        cmd = [
+            sys.executable,
+            '-c',
+            code,
+        ]
+        return self.run_cmd(cmd, env=env)
+
+    def test_valid_env_var(self):
+        default = ['tbb', 'omp', 'workqueue']
+        for p in itertools.permutations(default):
+            env_var = ' '.join(p)
+            threading_layer_priority, _ = self.each_env_var(env_var)
+            self.assertEqual(threading_layer_priority.strip(), env_var)
+
+    def test_invalid_env_var(self):
+        env_var = 'tbb omp workqueue notvalidhere'
+        with self.assertRaises(AssertionError) as raises:
+            self.each_env_var(env_var)
+        for msg in (
+            "THREADING_LAYER_PRIORITY invalid:",
+            "It must be a permutation of"
+        ):
+            self.assertIn(f"{msg}", str(raises.exception))
+
+    @skip_no_omp
+    def test_omp(self):
+        for env_var in ("omp tbb workqueue", "omp workqueue tbb"):
+            threading_layer_priority, out = self.each_env_var(env_var)
+            self.assertEqual(threading_layer_priority.strip(), env_var)
+            self.assertIn("@omp@", out)
+
+    @skip_no_tbb
+    def test_tbb(self):
+        for env_var in ("tbb omp workqueue", "tbb workqueue omp"):
+            threading_layer_priority, out = self.each_env_var(env_var)
+            self.assertEqual(threading_layer_priority.strip(), env_var)
+            self.assertIn("@tbb@", out)
+
+    def test_workqueue(self):
+        for env_var in ("workqueue tbb omp", "workqueue omp tbb"):
+            threading_layer_priority, out = self.each_env_var(env_var)
+            self.assertEqual(threading_layer_priority.strip(), env_var)
+            self.assertIn("@workqueue@", out)
+
+
 @skip_parfors_unsupported
 class TestMiscBackendIssues(ThreadLayerTestHelper):
     """