Merge pull request #313 from mgbckr/master

Clean-up and documentation for backend

Author: fabianp

.gitignore

@@ -6,6 +6,7 @@ MANIFEST
 *.egg-info
 *.pyc
 *~
+.coverage
 
 # Ignore mprof generated files
 mprofile_*.dat

README.rst

@@ -407,6 +407,25 @@ file ~/.ipython/ipy_user_conf.py to add the following lines::
     import memory_profiler
     memory_profiler.load_ipython_extension(ip)
 
+===============================
+Memory tracking backends
+===============================
+`memory_profiler` supports different memory tracking backends including: 'psutil', 'psutil_pss', 'psutil_uss', 'posix', 'tracemalloc'.
+If no specific backend is specified the default is to use "psutil" which measures RSS aka “Resident Set Size”. 
+In some cases (particularly when tracking child processes) RSS may overestimate memory usage (see `example/example_psutil_memory_full_info.py` for an example).
+For more information on "psutil_pss" (measuring PSS) and "psutil_uss" please refer to:
+https://psutil.readthedocs.io/en/latest/index.html?highlight=memory_info#psutil.Process.memory_full_info 
+
+Currently, the backend can be set via the CLI
+
+    $ python -m memory_profiler --backend psutil my_script.py
+
+and is exposed by the API
+
+    >>> from memory_profiler import memory_usage
+    >>> mem_usage = memory_usage(-1, interval=.2, timeout=1, backend="psutil")
+
+    
 ============================
  Frequently Asked Questions
 ============================
@@ -424,7 +443,6 @@ file ~/.ipython/ipy_user_conf.py to add the following lines::
       `psutil <http://pypi.python.org/pypi/psutil>`_ module.
 
 
-
 ===========================
  Support, bugs & wish list
 ===========================
@@ -486,6 +504,8 @@ cleanup.
 
 `Juan Luis Cano <https://github.com/Juanlu001>`_ modernized the infrastructure and helped with various things.
 
+`Martin Becker <https://github.com/mgbckr>`_ added PSS and USS tracking via the psutil backend.
+
 =========
  License
 =========

test/test_psutil_memory_full_info.py …ples/exxample_psutil_memory_full_info.pytest/test_psutil_memory_full_info.py renamed to examples/exxample_psutil_memory_full_info.py test/test_psutil_memory_full_info.py renamed to examples/exxample_psutil_memory_full_info.py

@@ -152,7 +152,7 @@ def _ps_util_full_tool(memory_metric):
         process = psutil.Process(pid)
         try:
             if not hasattr(process, 'memory_full_info'):
-                raise NotImplementedError("Backend `psutil_pss` and `psutil_uss` requires psutil > 4.0.0")
+                raise NotImplementedError("Backend `{}` requires psutil > 4.0.0".format(memory_metric))
 
             meminfo_attr = 'memory_full_info'
             meminfo = getattr(process, meminfo_attr)()
@@ -309,6 +309,12 @@ def memory_usage(proc=-1, interval=.1, timeout=None, timestamps=False,
         the subprocess. Useful for long-running processes.
         Implies timestamps=True.
 
+    backend : str, optional
+        Current supported backends: 'psutil', 'psutil_pss', 'psutil_uss', 'posix', 'tracemalloc'
+        If `backend=None` the default is "psutil" which measures RSS aka “Resident Set Size”. 
+        For more information on "psutil_pss" (measuring PSS) and "psutil_uss" please refer to:
+        https://psutil.readthedocs.io/en/latest/index.html?highlight=memory_info#psutil.Process.memory_full_info 
+
     max_iterations : int
         Limits the number of iterations (calls to the process being monitored). Relevent
         when the process is a python function.
@@ -1318,9 +1324,9 @@ def flush(self):
         default=False, action='store_true',
         help='also include memory used by child processes')
     parser.add_argument('--backend', dest='backend', type=str, action='store',
-        choices=['tracemalloc', 'psutil', 'posix'], default='psutil',
+        choices=['tracemalloc', 'psutil', 'psutil_pss', 'psutil_uss', 'posix'], default='psutil',
         help='backend using for getting memory info '
-             '(one of the {tracemalloc, psutil, posix})')
+             '(one of the {tracemalloc, psutil, posix, psutil_pss, psutil_uss, posix})')
     parser.add_argument("program", nargs=REMAINDER,
         help='python script or module followed by command line arguements to run')
     args = parser.parse_args()