Garbage Collector

Installation · Examples · System Requirements · Usage · Advanced Features · View Modes · Controls · How It Works

A Garbage Collector for Visualising Allocation, Deallocation, Kernel Mode Memory Management, Mark & Sweep Algorithm with a Visual Force Directed Graph

Advanced Features

Memory Visualisation

The garbage collector provides detailed memory visualisation:

Feature	Description
Memory Map	Shows physical memory layout with allocated blocks
Real-time Memory Usage	Tracks memory allocation and fragmentation over time
System Call Monitoring	Visualises kernel interactions for memory management
Region-based Visualisation	Separate views for heap, stack, and metadata regions

System Call Tracking

The visualiser traces and displays system calls related to memory management:

System Call Category	Description
Memory Allocation	Shows calls like VirtualAlloc, HeapAlloc, malloc, mmap
Memory Deallocation	Tracks VirtualFree, HeapFree, free, munmap
Synchronisation	Monitors mutex operations during garbage collection
Performance Metrics	Displays timing information for each system call

View Modes

The visualiser supports multiple view modes:

View Mode	Focus	Description
Memory View	Memory blocks, system calls	Highlights memory allocation, deallocation, and related system interactions.
Graph View	Object references, garbage collection	Emphasises object relationships and the garbage collection process.
Hybrid View	Memory and object relationships	Combines memory and object views for a comprehensive understanding.

System Requirements

Requirement	Details
Python Version	3.6+
Libraries	PyGame, psutil
Operating System	Windows, Linux, or macOS (system call display adapts to platform)
RAM	Minimum 4GB recommended for larger object graphs

Detailed API Reference

GarbageCollector Class

# Create a garbage collector with custom settings
gc = GarbageCollector(
    threshold=100,            # Object count that triggers collection
    auto_collect=True,        # Enable automatic collection
    collection_interval=5.0,  # Seconds between auto collections
    generations=3             # Number of generations (for future use)
)

# Manual control
gc.pause()                    # Pause garbage collection
gc.resume()                   # Resume garbage collection
gc.collect()                  # Force immediate collection

# Statistics
stats = gc.stats()            # Get comprehensive GC statistics

Examples

Creating Object Networks

# Create a Binary Tree Structure
def create_binary_tree(gc, depth=4):
    def build_tree(depth):
        if depth <= 0:
            return None
            
        node = gc.create_object(f"node-{depth}")
        if depth == 4:  # Make root node
            gc.add_root(node)
            
        left = build_tree(depth-1)
        right = build_tree(depth-1)
        
        if left:
            node.add_reference(left)
        if right:
            node.add_reference(right)
            
        return node
        
    return build_tree(depth)

# Create tree and visualize
tree_root = create_binary_tree(gc)
visualiser = GCVisualiser(gc)
visualiser.start()

Creating Memory Fragmentation Scenarios

# Simulate memory fragmentation patterns
def fragment_memory(gc):
    objects = []
    
    # Allocate many objects
    for i in range(100):
        obj = gc.create_object(f"frag-{i}")
        objects.append(obj)
    
    # Free every other object to create fragmentation
    for i in range(0, len(objects), 2):
        objects[i].references = []
        
    # Force collection
    gc.collect()
    
    # Allocate new objects that must fit between fragments
    for i in range(20):
        gc.create_object(f"new-{i}")

Installation

1. Clone the repository:

   git clone https://github.com/WillKirkmanM/garbage-collector.git
   cd garbage-collector
   

2. Install the dependencies:

   pip install pygame numpy
   

Usage

Run the demo to see the garbage collector in action:

python demo.py

Controls

Control	Action
Space	Pause/Resume animation
G	Force garbage collection
P	Pause/Resume garbage collector
C	Change layout (force-directed, circular, grid)
V	Toggle object values display
I	Toggle object IDs display
S	Toggle statistics display
Up/Down Arrows	Adjust animation speed
Left Click on Object	Show object details
Right Click on Object	Toggle root status

How It Works

The garbage collector uses a mark-and-sweep algorithm, visualised as follows:

Phase	Description	Visualisation
Mark Phase	Starting from root objects, all reachable objects are marked.	Blue circles become green, indicating they are reachable. Root objects have a white outline.
Sweep Phase	Unreachable (unmarked) objects are removed from memory.	Green circles turn red as they are swept, then gray as they are finalized.

Key to object colours:

Colour	Status
Blue	Allocated object
Green	Marked (reachable) object
Red	Object being swept (collected)
Gray	Finalized object
White Outline	Root object

Creating Your Own Scenarios

You can create your own scenarios by modifying the demo.py file or by using the garbage collector API directly:

from gc.collector import GarbageCollector
from gc.visualiser import GCVisualiser

# Create a garbage collector
gc = GarbageCollector()

# Create objects
obj1 = gc.create_object("root object", make_root=True)
obj2 = gc.create_object("referenced object")
obj3 = gc.create_object("unreachable object")

# Create references
obj1.add_reference(obj2)

# Run garbage collection
gc.collect()

# Visualize
visualiser = GCVisualiser(gc)
visualiser.start()