diff options
author | Giampaolo Rodola <g.rodola@gmail.com> | 2020-02-15 01:53:16 +0100 |
---|---|---|
committer | Giampaolo Rodola <g.rodola@gmail.com> | 2020-02-15 01:53:16 +0100 |
commit | d03c176c0478ed96a529be103318c42fa2f0af9d (patch) | |
tree | 34c30f24f6115f3cdc3cd2fbd9af6a4f3690016f | |
parent | 8bc5a180e96445fcd9e96fa6aebf8bc698910d96 (diff) | |
download | psutil-d03c176c0478ed96a529be103318c42fa2f0af9d.tar.gz |
update doc
-rw-r--r-- | docs/index.rst | 45 |
1 files changed, 18 insertions, 27 deletions
diff --git a/docs/index.rst b/docs/index.rst index ea5f15bd..1a5c2434 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -861,24 +861,26 @@ Functions Return an iterator yielding a :class:`Process` class instance for all running processes on the local machine. - Every instance is only created once and then cached into an internal table - which is updated every time an element is yielded. - Cached :class:`Process` instances are checked for identity so that you're - safe in case a PID has been reused by another process, in which case the - cached instance is updated. - This is preferred over :func:`psutil.pids()` for iterating over processes. - Sorting order in which processes are returned is based on their PID. + This should be preferred over :func:`psutil.pids()` to iterate over processes + as it's safe from race condition. + + Every :class:`Process` instance is only created once, and then cached for the + next time :func:`psutil.process_iter()` is called (if PID is still alive). + Also it makes sure process PIDs are not reused. + *attrs* and *ad_value* have the same meaning as in :meth:`Process.as_dict()`. - If *attrs* is specified :meth:`Process.as_dict()` is called internally and - the resulting dict is stored as a ``info`` attribute which is attached to the - returned :class:`Process` instances. + If *attrs* is specified :meth:`Process.as_dict()` result will be stored as a + ``info`` attribute attached to the returned :class:`Process` instances. If *attrs* is an empty list it will retrieve all process info (slow). + If *new_only* is true this function will yield only new processes which appeared since the last time it was called. - Example usage:: + Sorting order in which processes are returned is based on their PID. + + Example:: >>> import psutil - >>> for proc in psutil.process_iter(attrs=['pid', 'name', 'username']): + >>> for proc in psutil.process_iter(('pid', 'name', 'username')): ... print(proc.info) ... {'name': 'systemd', 'pid': 1, 'username': 'root'} @@ -886,30 +888,19 @@ Functions {'name': 'ksoftirqd/0', 'pid': 3, 'username': 'root'} ... - Example of a dict comprehensions to create a ``{pid: info, ...}`` data - structure:: + A dict comprehensions to create a ``{pid: info, ...}`` data structure:: >>> import psutil - >>> procs = {p.pid: p.info for p in psutil.process_iter(attrs=['name', 'username'])} + >>> procs = {p.pid: p.info for p in psutil.process_iter(('name', 'username'))} >>> procs {1: {'name': 'systemd', 'username': 'root'}, 2: {'name': 'kthreadd', 'username': 'root'}, 3: {'name': 'ksoftirqd/0', 'username': 'root'}, ...} - Example showing how to filter processes by name (see also - `process filtering <#filtering-and-sorting-processes>`__ section for more - examples):: - - >>> import psutil - >>> [p.info for p in psutil.process_iter(attrs=['pid', 'name']) if 'python' in p.info['name']] - [{'name': 'python3', 'pid': 21947}, - {'name': 'python', 'pid': 23835}] + Get new processes since last call:: - Get new processes only (since last call):: - - >>> import psutil - >>> for proc in psutil.process_iter(attrs=['pid', 'name'], new_only=True): + >>> for proc in psutil.process_iter(('pid', 'name'), new_only=True): ... print(proc.info) ... |