Skip to content

README.md

Latest commit

 

History

History
107 lines (82 loc) · 3.21 KB

README.md

File metadata and controls

107 lines (82 loc) · 3.21 KB
Raw

PageInvaders

PageInvaders is a desktop virtual-memory simulator for Operating Systems classes. Page requests move through a TLB, page table, loader, and physical frames while the app shows page hits, faults, dirty evictions, EMAT, fault rate, and thrashing.

The app is intentionally small: Python, pygame, and SQLite from the standard library. There is no web server and no network dependency.

Project Files

File Purpose
main.py pygame UI, menu, animation, controls, report overlay, and save action.
engine.py Headless simulation model: TLB, page table, frames, metrics, scenarios, and FIFO/LRU/OPT replacement strategies.
db.py SQLite persistence for saved run reports.
requirements.txt Runtime dependency list.

Generated folders such as build/, dist/, __pycache__/, debug screenshots, and saved reports.db files are not part of the source tree.

Run From Source

python -m pip install -r requirements.txt
python main.py

Build The Executable

python -m pip install "pyinstaller>=6.0"
pyinstaller pageinvaders.spec

The executable is created at dist/PageInvaders.exe. The first saved report creates a reports.db file next to the executable. When running from source, reports.db is created next to db.py.

Controls

Action Control
Play or pause On-screen button or Space
Step while paused On-screen button or Right Arrow
Reset current run On-screen button
Change speed Speed button
Toggle TLB TLB button
Compare algorithms Run all 3
Open report Report button after a run completes
Return to menu Menu button or Esc

Simulation Model

engine.py keeps the simulation independent from pygame. The UI creates an Engine, subscribes to access events through EventBus, and renders the latest model state.

Each access follows this flow:

  1. Check the TLB if it is enabled.
  2. Read the page-table entry.
  3. Serve resident pages as hits.
  4. On a fault, use a free frame or ask the active replacement strategy for a victim.
  5. Update dirty/reference bits, counters, EMAT, rolling fault rate, and thrashing state.
  6. Publish one event for the UI animation and narration.

Replacement strategies:

Algorithm Victim rule
FIFO Oldest load_time
LRU Oldest last_used
OPT Resident page used furthest in the future

Scenarios

The menu includes built-in teaching scenarios:

Scenario Purpose
Belady's Anomaly Shows FIFO faults can increase with more frames.
Textbook Classic Uses a standard reference string for algorithm comparison.
Thrashing Tiny physical memory with wide random access.
Locality of Reference Demonstrates why LRU works well on localized traces.

Saved Reports

The report overlay can save a completed run to SQLite. db.py stores one row in runs and the per-step details in steps. You can inspect the database with any SQLite browser.

Configuration Defaults

Setting Default
Algorithm LRU
Pattern LOCALIZED
Frames 4
Virtual pages 16
Reference length 50
Write probability 0.20
Locality 0.85
TLB Enabled