pss/README.en.md

🖥️ Process Scheduler Simulator

An interactive educational tool for visualizing and comparing classical CPU scheduling algorithms from Operating Systems.

---

✨ What is it?

The Process Scheduler Simulator (PSS) runs entirely in the browser, completely free of servers and system dependencies. You define the processes, choose the algorithm, and watch the simulation unfold in real time through the Gantt chart.

Ideal for:

• 📚 Operating Systems students who want to visualize what was once only theory
• 👩‍🏫 Instructors looking for an interactive classroom tool
• 🔍 Professionals revisiting OS fundamentals

A live demo is available at: https://pss.lucasrguerra.dev.br/

---

🚀 Quick Start

Prerequisites

• Node.js 20+
• npm 10+

Local installation and run

# Clone the repository
git clone https://github.com/lucasrguerra/pss.git
cd pss

# Install dependencies
npm install

# Start the development server
npm run dev

Open http://localhost:5173 in your browser.

Production build

npm run build
npm run preview

With Docker

docker compose up

---

🎮 How to use

1. Create your processes: In the left panel, add processes by defining name, arrival time, priority, and a sequence of bursts (CPU and I/O). Or use the random generator to get started quickly.
2. Configure the scheduler: Choose an algorithm and adjust the parameters (quantum for RR, aging for Priority, etc.).
3. Run the simulation: Use the Play/Pause/Step controls to run the simulation at the speed you want (0.25× to 4×).
4. Analyze the results: The Gantt chart shows each process's state in real time. At the end, the metrics panel displays turnaround, waiting time, throughput, and more.

💡 Tip: Load one of the built-in presets to see classic phenomena such as the FCFS convoy effect or priority starvation.

---

⚙️ Supported Algorithms

Algorithm	Preemptive?	Parameters
FCFS: First Come, First Served	❌	None
SJF: Shortest Job First	❌	None
SRTF: Shortest Remaining Time First	✅	None
Round Robin (RR)	✅	Quantum
Priority NP: Non-Preemptive Priority	❌	Aging (optional)
Priority P: Preemptive Priority	✅	Aging (optional)
HRRN: Highest Response Ratio Next	❌	None
Multilevel Queue	✅	Quantum per queue

See the algorithms documentation for details on how each one works.

---

📊 Computed Metrics

For each simulated process, PSS automatically computes:

• Response Time: time until the first CPU usage
• Turnaround Time: total time from arrival to completion
• Waiting Time: total time spent in the Ready queue
• CPU Time / I/O Time: effective time in each type of burst
• CPU Utilization: percentage of turnaround time spent on CPU
• Bound Type: automatic classification as CPU Bound, I/O Bound, or Balanced

Globally: averages for response/turnaround/waiting, throughput, and overall CPU utilization.

---

🗂️ Project Structure

src/
├── core/                    # Pure logic (no React)
│   ├── algorithms/          # Implementation of each algorithm
│   │   ├── base.ts          # Abstract class BaseScheduler
│   │   ├── fcfs.ts
│   │   ├── sjf.ts
│   │   ├── rr.ts
│   │   ├── priority.ts
│   │   ├── priority_rr.ts
│   │   ├── hrrn.ts
│   │   ├── multilevel.ts
│   │   └── index.ts         # Dispatch by algorithm
│   ├── engine.ts            # SimulationEngine, orchestrates the ticks
│   ├── metrics.ts           # Per-process and global metrics computation
│   ├── types.ts             # All TypeScript interfaces
│   └── presets.ts           # Pre-defined scenarios
│
├── store/                   # Global state with Zustand
├── components/              # React components
│   ├── ProcessPanel/        # Process creation and editing
│   ├── SchedulerPanel/      # Algorithm selection and parameters
│   ├── ControlBar/          # Play, Pause, Step, Reset, speed
│   ├── GanttChart/          # Interactive Gantt chart
│   ├── MetricsPanel/        # Table, charts, and global metrics
│   └── shared/              # Buttons, badges, tooltips, modals
│
└── hooks/                   # Custom hooks (animation loop, export, etc.)

---

📦 Available Presets

Load classic scenarios with a single click to explore OS phenomena:

Preset	What it demonstrates
classic_fcfs	Basic execution with FCFS, no I/O
convoy_effect	Convoy effect: one long process blocking many short ones
rr_demo	Fair time-sharing with Round Robin (quantum=3)
starvation	Low-priority processes never receive CPU
aging_fix	The same starvation scenario, solved with aging
io_heavy	Mix of CPU Bound vs. I/O Bound processes
multilevel_demo	Multiple queues with different priorities

---

🧪 Tests

# Run all unit tests
npm test

# Watch mode (re-runs on save)
npm run test:watch

# With coverage report
npm run test:coverage

Tests cover the simulation engine, all scheduling algorithms, and metrics computation.

---

🛠️ Technology Stack

Layer	Technology
UI Framework	React 18
Language	TypeScript 5
Build tool	Vite 6
Styling	Tailwind CSS 4
Global state	Zustand 5
Charts	Recharts
Icons	Lucide React
Testing	Vitest + Testing Library

---

📄 Additional Documentation

• 📐 Scheduling Algorithms: detailed description of each algorithm, tie-breaking rules, and examples
• 📏 Metrics: formulas and definitions for all computed metrics
• 📝 JOSS Paper: scientific paper submitted to the Journal of Open Source Software

Também disponível em: 🇧🇷 Português

---

🤝 Contributing

Contributions are welcome! Please read our CONTRIBUTING.md guide for details on our code of conduct, and the process for submitting Pull Requests to us.

---

📜 License

Distributed under the MIT License. Developed by Lucas Rayan Guerra.