pidstats: Add documentation for the reload() method

Mention python-perf as an alternative way of noticing thread lifetime
events (FORK, EXIT).

Requested-by: Guy Streeter <streeter@redhat.com>
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>

1 files changed, 14 insertions, 0 deletions

diff --git a/procfs/procfs.py b/procfs/procfs.py
index af51207..3d683c1 100755
--- a/procfs/procfs.py
+++ b/procfs/procfs.py
@@ -412,6 +412,20 @@ class pidstats:
 		return key in self.processes
 
 	def reload(self):
+	"""
+	This operation will trow away the current dictionary contents, if any, and
+	read all the pid files from /proc/, instantiating a 'process' instance for
+	each of them.
+
+	This is a high overhead operation, and should be avoided if the perf python
+	binding can be used to detect when new threads appear and existing ones
+	terminate.
+
+	In RHEL it is found in the python-perf rpm package.
+
+	More information about the perf facilities can be found in the 'perf_event_open'
+	man page.
+	"""
 		del self.processes
 		self.processes = {}
 		pids = os.listdir(self.basedir)