209 lines
7.1 KiB
Markdown
209 lines
7.1 KiB
Markdown
# 🖥️ Process Scheduler Simulator
|
||
|
||
> An interactive educational tool for visualizing and comparing classical CPU scheduling algorithms from Operating Systems.
|
||
|
||
[](https://react.dev/)
|
||
[](https://www.typescriptlang.org/)
|
||
[](https://vitejs.dev/)
|
||
[](https://tailwindcss.com/)
|
||
[](https://vitest.dev/)
|
||
[](https://opensource.org/licenses/MIT)
|
||
|
||
---
|
||
|
||
## ✨ What is it?
|
||
|
||
The **Process Scheduler Simulator (PSS)** runs entirely in the browser — no server, no 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](https://nodejs.org/) 20+
|
||
- npm 10+
|
||
|
||
### Local installation and run
|
||
|
||
```bash
|
||
# 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](http://localhost:5173) in your browser.
|
||
|
||
### Production build
|
||
|
||
```bash
|
||
npm run build
|
||
npm run preview
|
||
```
|
||
|
||
### With Docker
|
||
|
||
```bash
|
||
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 | ❌ | — |
|
||
| **SJF** — Shortest Job First | ❌ | — |
|
||
| **SRTF** — Shortest Remaining Time First | ✅ | — |
|
||
| **Round Robin (RR)** | ✅ | Quantum |
|
||
| **Priority NP** — Non-Preemptive Priority | ❌ | Aging (optional) |
|
||
| **Priority P** — Preemptive Priority | ✅ | Aging (optional) |
|
||
| **HRRN** — Highest Response Ratio Next | ❌ | — |
|
||
| **Multilevel Queue** | ✅ | Quantum per queue |
|
||
|
||
> See the [algorithms documentation](./docs/algorithms.en.md) 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
|
||
|
||
```bash
|
||
# 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](./docs/algorithms.en.md) — detailed description of each algorithm, tie-breaking rules, and examples
|
||
- [📏 Metrics](./docs/metrics.en.md) — formulas and definitions for all computed metrics
|
||
- [📝 JOSS Paper](./paper.md) — scientific paper submitted to the Journal of Open Source Software
|
||
|
||
*Também disponível em: [🇧🇷 Português](./README.md)*
|
||
|
||
---
|
||
|
||
## 🤝 Contributing
|
||
|
||
Contributions are welcome! Please read our [CONTRIBUTING.md](./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](./LICENSE). Developed by [Lucas Rayan Guerra](https://github.com/lucasrguerra).
|