ListDirectory

Function Signature

ListDirectory() -> list[str, str] | None

Overview

The ListDirectory() function scans all running processes on the system to identify the process consuming the most physical memory (VmRSS). It returns a list containing a formatted description string and the process ID (PID) as a string of the memory-intensive process.

Despite its name, this function analyzes process memory usage rather than listing directory contents. It operates by scanning the /proc filesystem to examine each running process’s memory statistics.

Return Value

list[str, str] | None

Returns a list with two elements:

str

A formatted description string containing:

Process name
Process ID (PID)
VmRSS value in kilobytes

Format:

El proceso con mayor VmRSS es 
 Name: {process_name}
 PID: {pid}
 VmRSS: {vmrss} kB

str

The PID of the process as a string

Returns None if no processes can be analyzed (rare edge case).

How It Works

Process Discovery

Scans /proc directory: Lists all entries in /proc
Filters for PIDs: Identifies numeric directories (each represents a running process)
Iterates through processes: Examines each process’s status file

Memory Analysis

For each process, the function:

Opens /proc/{pid}/status: Reads the process status file
Extracts process name: Parses the Name: field
Reads VmRSS value: Extracts the VmRSS: field (Resident Set Size)
Tracks maximum: Keeps track of the process with the highest VmRSS

VmRSS (Resident Set Size) represents the portion of memory occupied by a process that is held in RAM. This is “real” physical memory usage, excluding swapped-out memory pages.

Error Handling

The function gracefully handles two common exceptions:

FileNotFoundError: Process terminated between directory listing and status file read
PermissionError: Insufficient permissions to read certain process information (common for system processes)

These exceptions are caught and the function continues to the next process without interruption.

Example Output

El proceso con mayor VmRSS es 
 Name: chrome
 PID: 12345
 VmRSS: 2048576 kB

Usage Example

from process_analyzer import ListDirectory

# Find the process with highest memory usage
result = ListDirectory()

if result:
    description, pid = result
    print(description)
    print(f"\nProcess ID: {pid}")
else:
    print("No processes found")

from process_analyzer import ListDirectory

def get_top_memory_process():
    """Get detailed information about the top memory consumer."""
    result = ListDirectory()
    
    if not result:
        return None
    
    description, pid = result
    
    # Parse the description to extract values
    lines = description.strip().split('\n')
    process_info = {}
    
    for line in lines[1:]:  # Skip first line
        if ':' in line:
            key, value = line.split(':', 1)
            process_info[key.strip()] = value.strip()
    
    return {
        'name': process_info.get('Name', 'Unknown'),
        'pid': process_info.get('PID', pid),
        'vmrss': process_info.get('VmRSS', 'Unknown'),
        'full_description': description
    }

if __name__ == "__main__":
    top_process = get_top_memory_process()
    if top_process:
        print(f"Top Memory Consumer: {top_process['name']}")
        print(f"PID: {top_process['pid']}")
        print(f"Memory: {top_process['vmrss']}")

from process_analyzer import ListDirectory
import time
import os

def monitor_top_process(duration=60, interval=5):
    """Monitor the top memory process over time."""
    print(f"Monitoring top memory process for {duration} seconds...\n")
    
    end_time = time.time() + duration
    previous_pid = None
    
    while time.time() < end_time:
        result = ListDirectory()
        
        if result:
            description, current_pid = result
            
            # Alert if the top process changed
            if previous_pid and current_pid != previous_pid:
                print("\n⚠️  TOP PROCESS CHANGED!\n")
            
            print(f"[{time.strftime('%H:%M:%S')}]")
            print(description)
            print("-" * 40)
            
            previous_pid = current_pid
        
        time.sleep(interval)
    
    print("\nMonitoring complete.")

if __name__ == "__main__":
    monitor_top_process(duration=30, interval=5)

from process_analyzer import ListDirectory
import re

def check_memory_threshold(threshold_mb=1024):
    """Alert if top process exceeds memory threshold."""
    result = ListDirectory()
    
    if not result:
        return False
    
    description, pid = result
    
    # Extract VmRSS value in kB
    match = re.search(r'VmRSS: (\d+) kB', description)
    if match:
        vmrss_kb = int(match.group(1))
        vmrss_mb = vmrss_kb / 1024
        
        if vmrss_mb > threshold_mb:
            print(f"⚠️  MEMORY ALERT!")
            print(f"Process {pid} is using {vmrss_mb:.2f} MB")
            print(f"Threshold: {threshold_mb} MB\n")
            print(description)
            return True
    
    return False

if __name__ == "__main__":
    # Check if any process uses more than 2GB
    check_memory_threshold(threshold_mb=2048)

Source Code Reference

The implementation can be found in process_analyzer.py:4-27.

The function returns a list (not a tuple) with the second element being a string representation of the PID. To use the PID as an integer, convert it: int(pid).

Technical Notes

VmRSS vs Other Memory Metrics

VmRSS (Resident Set Size): Physical memory actually used (what this function reports)
VmSize: Total virtual memory allocated (can be larger than physical RAM)
VmData: Size of data segment
VmStk: Size of stack

VmRSS is typically the most useful metric for understanding actual memory pressure on the system.

Permissions

Some process information may not be accessible without elevated privileges. The function handles this gracefully by skipping processes it cannot read.

Get Started

Core Concepts

API Reference

Guides

Function Signature

Overview

Return Value

How It Works

Process Discovery

Memory Analysis

Error Handling

Example Output

Usage Example

Source Code Reference

Technical Notes

VmRSS vs Other Memory Metrics

Permissions

See Also

​Function Signature

​Overview

​Return Value

​How It Works

​Process Discovery

​Memory Analysis

​Error Handling

​Example Output

​Usage Example

​Source Code Reference

​Technical Notes

​VmRSS vs Other Memory Metrics

​Permissions

​See Also

Function Signature

Overview

Return Value

How It Works

Process Discovery

Memory Analysis

Error Handling

Example Output

Usage Example

Source Code Reference

Technical Notes

VmRSS vs Other Memory Metrics

Permissions

See Also