Add should_run_in_parallel to public API

The function was added in a stable manner to enable backport to the 1.1
series, but from 1.2 onwards, we want this to be part of the public
interface so that others can rely on it too.

qiskit/utils/__init__.py

@@ -43,6 +43,7 @@
 
 .. autofunction:: local_hardware_info
 .. autofunction:: is_main_process
+.. autofunction:: should_run_in_parallel
 
 A helper function for calling a custom function with Python
 :class:`~concurrent.futures.ProcessPoolExecutor`. Tasks can be executed in parallel using this function.

qiskit/utils/parallel.py

@@ -127,8 +127,8 @@ def parallel_map(  # pylint: disable=dangerous-default-value
 
         result = [task(value, *task_args, **task_kwargs) for value in values]
 
-    This will parallelise the results if the number of ``values`` is greater than one, and the
-    current system configuration permits parallelization.
+    This will parallelise the results if the number of ``values`` is greater than one and
+    :func:`should_run_in_parallel` returns ``True``.  If not, it will run in serial.
 
     Args:
         task (func): Function that is to be called for each value in ``values``.

releasenotes/notes/parallel-check-public-7faed5f3e20e1d03.yaml

@@ -0,0 +1,7 @@
+---
+features_misc:
+  - |
+    A new function, :func:`qiskit.utils.should_run_in_parallel`, is available to determine whether
+    :func:`.parallel_map` will choose to run in parallel or degrade to running in serial.  This
+    decision is dependent on how many CPUs are available to Qiskit, what the :mod:`multiprocessing`
+    start method is, how many processes were requested.