[Linux] expose process locked memory (#2994)

Fixes #1109.

Author: giampaolo

docs/api.rst

@@ -1701,6 +1701,8 @@ Process class
     +-------------+----------------+--------------------+
     | hugetlb     |                |                    |
     +-------------+----------------+--------------------+
+    | locked      |                |                    |
+    +-------------+----------------+--------------------+
 
     Linux:
 
@@ -1721,6 +1723,8 @@ Process class
       < 2.6.34.
     - :field:`hugetlb`: resident memory backed by huge pages. Set to 0 on Linux
       < 4.4.
+    - :field:`locked`: locked memory that cannot be
+      :term:`swapped out <swap-out>`. Typically locked via :manpage:`mlock(2)`.
 
     macOS:
 

docs/changelog.rst

@@ -49,6 +49,8 @@ Changelog
   no longer set to ``0``.
 - :gh:`2977`: new :func:`bytes2human` utility function, converting a number of
   bytes to a human-readable string (e.g. ``9.8K``).
+- :gh:`1109`, [Linux]: :meth:`Process.memory_extras` returns a new
+  :field:`locked` field: locked virtual memory (:manpage:`mlock(2)`).
 - :gh:`1452`, :gh:`2993`, [Linux, macOS, Windows]:
   :meth:`Process.memory_footprint` returns a new :field:`shared` field:
   resident memory shared with other processes.

docs/migration.rst

@@ -167,7 +167,8 @@ New memory_extras() method
 platform-specific memory metrics which complement :meth:`Process.memory_info`:
 
 - Linux: :field:`peak_rss`, :field:`peak_vms`, :field:`rss_anon`,
-  :field:`rss_file`, :field:`rss_shmem`, :field:`swap_anon`, :field:`hugetlb`.
+  :field:`rss_file`, :field:`rss_shmem`, :field:`swap_anon`, :field:`hugetlb`,
+  :field:`locked`.
 - macOS: :field:`phys_footprint`, :field:`peak_footprint`.
 - Windows: :field:`virtual`, :field:`peak_virtual`, :field:`paged_pool`,
   :field:`nonpaged_pool`, :field:`peak_paged_pool`,

psutil/_ntuples.py

@@ -420,6 +420,7 @@ class pmem_extras(NamedTuple):
         rss_shmem: int
         swap_anon: int
         hugetlb: int
+        locked: int
 
     # psutil.Process().memory_full_info()
     pfullmem = namedtuple("pfullmem", pmem._fields + ("uss", "pss", "swap"))

psutil/_pslinux.py

@@ -1915,6 +1915,7 @@ def memory_extras(
         _rssshmem_re=re.compile(br"RssShmem:\s+(\d+)"),
         _vmswap_re=re.compile(br"VmSwap:\s+(\d+)"),
         _hugetlb_re=re.compile(br"HugetlbPages:\s+(\d+)"),
+        _vmlck_re=re.compile(br"VmLck:\s+(\d+)"),
     ):
         # Read /proc/{pid}/status.
         # RssAnon/RssFile/RssShmem were added in Linux 4.5;
@@ -1933,6 +1934,7 @@ def parse(regex):
             rss_shmem=parse(_rssshmem_re),
             swap_anon=parse(_vmswap_re),
             hugetlb=parse(_hugetlb_re),
+            locked=parse(_vmlck_re),
         )
 
     if HAS_PROC_SMAPS_ROLLUP or HAS_PROC_SMAPS:

tests/test_linux.py

@@ -8,6 +8,7 @@
 
 import collections
 import contextlib
+import ctypes
 import errno
 import glob
 import io
@@ -2551,6 +2552,24 @@ def test_memory_extras(self):
         vmrss = int(re.search(br"VmRSS:\s+(\d+)", data).group(1)) * 1024
         assert mem.rss_anon + mem.rss_file + mem.rss_shmem == vmrss
 
+    def test_memory_extras_locked(self):
+        libc = ctypes.CDLL(None, use_errno=True)
+        size = mmap.PAGESIZE * 4
+        buf = mmap.mmap(-1, size)
+        self.addCleanup(buf.close)
+        view = ctypes.c_char.from_buffer(buf)
+        addr = ctypes.addressof(view)
+        del view
+        base = psutil.Process().memory_extras().locked
+        if libc.mlock(ctypes.c_void_p(addr), ctypes.c_size_t(size)) != 0:
+            err = ctypes.get_errno()
+            return pytest.skip(f"mlock() failed: {os.strerror(err)}")
+        self.addCleanup(
+            libc.munlock, ctypes.c_void_p(addr), ctypes.c_size_t(size)
+        )
+        after = psutil.Process().memory_extras().locked
+        assert after - base == size
+
     def test_memory_footprint_shared_self_mappings(self):
         # A page mapped twice by the same process counts as shared,
         # even with no other process involved.

tests/test_process.py

@@ -505,6 +505,7 @@ def test_memory_extras_fields_order(self):
                 "rss_shmem",
                 "swap_anon",
                 "hugetlb",
+                "locked",
             )
         elif MACOS:
             assert mem._fields == ("phys_footprint", "peak_footprint")