From 37fbdfe123db097c6d47fe8f2c1719c65e048893 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith [Google LLC]" Date: Tue, 3 Oct 2023 04:57:44 +0000 Subject: [PATCH] Include multiprocessing in docs, reword. Adds PYTHON_CPU_COUNT help text. Mentions multiprocessing.cpu_count. rewords a few statements. --- Doc/c-api/init_config.rst | 6 +++--- Doc/library/multiprocessing.rst | 9 ++++++++- Doc/using/cmdline.rst | 13 +++++++------ Python/initconfig.c | 7 +++++-- 4 files changed, 23 insertions(+), 12 deletions(-) diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index c632e6a1e6a1b9..0240e25b6f1607 100644 --- a/Doc/c-api/init_config.rst +++ b/Doc/c-api/init_config.rst @@ -880,9 +880,9 @@ PyConfig .. c:member:: int cpu_count - If the value of :c:member:`~PyConfig.cpu_count` is not ``-1`` then it will override - the return value of :func:`os.cpu_count` and :func:`os.process_cpu_count` functions - into *cpu_count*. + If the value of :c:member:`~PyConfig.cpu_count` is not ``-1`` then it will + override the return values of :func:`os.cpu_count`, + :func:`os.process_cpu_count`, and :func:`multiprocessing.cpu_count`. Configured by the :samp:`-X cpu_count={n|default}` command line flag or the :envvar:`PYTHON_CPU_COUNT` environment variable. diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 2f0f1f800fdc94..5cec9d87a01cc6 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -996,13 +996,20 @@ Miscellaneous This number is not equivalent to the number of CPUs the current process can use. The number of usable CPUs can be obtained with - ``len(os.sched_getaffinity(0))`` + :func:`os.process_cpu_count` (or ``len(os.sched_getaffinity(0))``). When the number of CPUs cannot be determined a :exc:`NotImplementedError` is raised. .. seealso:: :func:`os.cpu_count` + :func:`os.process_cpu_count` + + .. versionchanged:: 3.13 + + The return value can also be overridden using the + :option:`-X cpu_count <-X>` flag or :envvar:`PYTHON_CPU_COUNT` as this is + merely a wrapper around the :mod:`os` cpu count APIs. .. function:: current_process() diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index aac0a5a85ae2ab..5c9d4b106742d2 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -546,11 +546,12 @@ Miscellaneous options report Python calls. This option is only available on some platforms and will do nothing if is not supported on the current system. The default value is "off". See also :envvar:`PYTHONPERFSUPPORT` and :ref:`perf_profiling`. - * :samp:`-X cpu_count={n}` overrides :func:`os.cpu_count` and :func:`os.process_cpu_count`. + * :samp:`-X cpu_count={n}` overrides :func:`os.cpu_count`, + :func:`os.process_cpu_count`, and :func:`multiprocessing.cpu_count`. *n* must be greater than or equal to 1. - This option is useful for users who need to limit CPU resources of a container system. - See also :envvar:`PYTHON_CPU_COUNT`. - If *n* is ``default``, :func:`os.cpu_count` and :func:`os.process_cpu_count` are not overridden. + This option may be useful for users who need to limit CPU resources of a + container system. See also :envvar:`PYTHON_CPU_COUNT`. + If *n* is ``default``, nothing is overridden. It also allows passing arbitrary values and retrieving them through the :data:`sys._xoptions` dictionary. @@ -1073,8 +1074,8 @@ conflict. .. envvar:: PYTHON_CPU_COUNT - If this variable is set to a positive integer, it overrides - :func:`os.cpu_count` and and :func:`os.process_cpu_count` return result. + If this variable is set to a positive integer, it overrides the return + values of :func:`os.cpu_count` and :func:`os.process_cpu_count`. See also the :option:`-X cpu_count <-X>` command-line option. diff --git a/Python/initconfig.c b/Python/initconfig.c index 210a8294fd57c0..ae458dc702bd12 100644 --- a/Python/initconfig.c +++ b/Python/initconfig.c @@ -231,8 +231,9 @@ The following implementation-specific options are available:\n\ This helps avoid denial of service attacks when parsing untrusted data.\n\ The default is sys.int_info.default_max_str_digits. 0 disables.\n\ \n\ --X cpu_count=[n|default]: override CPU count of os.cpu_count() and os.process_cpu_count().\n\ - This helps for users who need to limit CPU resources of a container system." +-X cpu_count=[n|default]: Override the return value of os.cpu_count(),\n\ + os.process_cpu_count(), and multiprocessing.cpu_count(). This can help users who need\n\ + to limit resources in a container." #ifdef Py_STATS "\n\ @@ -270,6 +271,8 @@ static const char usage_envvars[] = " locale coercion and locale compatibility warnings on stderr.\n" "PYTHONBREAKPOINT: if this variable is set to 0, it disables the default\n" " debugger. It can be set to the callable of your debugger of choice.\n" +"PYTHON_CPU_COUNT: Overrides the return value of os.process_cpu_count(),\n" +" os.cpu_count(), and multiprocessing.cpu_count() if set to a positive integer.\n" "PYTHONDEVMODE: enable the development mode.\n" "PYTHONPYCACHEPREFIX: root directory for bytecode cache (pyc) files.\n" "PYTHONWARNDEFAULTENCODING: enable opt-in EncodingWarning for 'encoding=None'.\n"