summaryrefslogtreecommitdiff
path: root/docs/index.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/index.rst')
-rw-r--r--docs/index.rst55
1 files changed, 40 insertions, 15 deletions
diff --git a/docs/index.rst b/docs/index.rst
index d7d32632..595130cd 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -194,34 +194,59 @@ CPU
.. versionchanged::
4.1.0 two new *interrupt* and *dpc* fields are returned on Windows.
-.. function:: cpu_count(logical=True)
-
- Return the number of logical CPUs in the system (same as `os.cpu_count`_
- in Python 3.4) or ``None`` if undetermined.
- "logical CPUs" means the number of physical cores multiplied by the number
- of threads that can run on each core (this is known as Hyper Threading).
- If *logical* is ``False`` return the number of physical cores only, or
- ``None`` if undetermined.
- On OpenBSD and NetBSD ``psutil.cpu_count(logical=False)`` always return
- ``None``.
+.. function:: cpu_count(kind="logical")
+
+ Return the number of CPUs in the system (various kinds) or ``None`` if
+ undetermined (same as `os.cpu_count`_).
+ The *kind* parameter dictates the desired CPU count to get:
+
+ - **logical**: the total number of CPUs in the system (same as `os.cpu_count`_).
+ Usually this is the number of cores multiplied by the number of threads
+ that can run on each core (this is known as Hyper Threading).
+ - **cores**: the number of physical CPU cores
+ - **sockets**: the number of physical CPU sockets on the motherboard
+ - **numa**: the number of CPU NUMA nodes
+
+ ======== =========== ========== ========== ======== ======== ======== ======= =======
+ Type Linux Windows macOS FreeBSD OpenBSD NetBSD SunOS AIX
+ ======== =========== ========== ========== ======== ======== ======== ======= =======
+ logical X X X X X X X X
+ cores X X X X X X
+ sockets X X X X
+ numa X X
+ ======== =========== ========== ========== ======== ======== ======== ======= =======
+
Example on a system having 2 cores + Hyper Threading:
+ .. code-block:: python
+
>>> import psutil
- >>> psutil.cpu_count()
+ >>> psutil.cpu_count(kind="logical")
4
- >>> psutil.cpu_count(logical=False)
+ >>> psutil.cpu_count(kind="cores")
2
+ >>> psutil.cpu_count(kind="sockets")
+ 1
- Note that ``psutil.cpu_count()`` may not necessarily be equivalent to the
- actual number of CPUs the current process can use.
+ Note that "logical" count may not necessarily be equivalent to the actual
+ number of CPUs the current process can use.
That can vary in case process CPU affinity has been changed, Linux cgroups
are being used or (in case of Windows) on systems using processor groups or
having more than 64 CPUs.
- The number of usable CPUs can be obtained with:
+ A reasonably reliable number of usable CPUs can be obtained with:
>>> len(psutil.Process().cpu_affinity())
1
+ .. versionchanged:: 5.8.1 "kind" parameter was added, "logical" parameter was
+ deprecated, "sockets" and "numa" CPU counts were added.
+
+ .. warning::
+ the original signature of this function was ``cpu_count(logical=True)``.
+ That signature got deprecated in 5.8.1. The old function invocations
+ ``cpu_count(<bool>)`` and ``cpu_count(logical=<str>)`` still work though,
+ but will raise a ``DeprecationWarning``.
+
.. function:: cpu_stats()
Return various CPU statistics as a named tuple: