feat: Add English documentation, switch license to MIT, and include JOSS paper.
This commit is contained in:
Lucas Guerra committed
1 parent
571d8e51d2
commit
cb05314232
10 files changed
+646
-4
No files matched your search
+208
@@ -0,0 +1,208 @@
|
||||
# 🖥️ 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! Feel free to open an [issue](https://github.com/lucasrguerra/pss/issues) or submit a Pull Request.
|
||||
|
||||
---
|
||||
|
||||
## 📜 License
|
||||
|
||||
Distributed under the [MIT License](./LICENSE). Developed by [Lucas Rayan Guerra](https://github.com/lucasrguerra).
|
||||
Reference in new issue
Block a user