pss/README.md

🖥️ Process Scheduler Simulator

Uma ferramenta educacional interativa para visualizar e comparar algoritmos clássicos de escalonamento de processos de Sistemas Operacionais.

---

✨ O que é?

O Process Scheduler Simulator (PSS) roda completamente no navegador, sem servidor e sem instalação de dependências de sistema. Você define os processos, escolhe o algoritmo, e assiste à simulação acontecer em tempo real através do diagrama de Gantt.

Ideal para:

• 📚 Estudantes de Sistemas Operacionais querendo visualizar o que antes era só teoria
• 👩‍🏫 Professores buscando uma ferramenta interativa para sala de aula
• 🔍 Profissionais revisitando fundamentos de SO

---

🚀 Quick Start

Pré-requisitos

• Node.js 20+
• npm 10+

Instalação e execução local

# Clone o repositório
git clone https://git.lucasrguerra.dev.br/lucasrguerra/pss.git
cd pss

# Instale as dependências
npm install

# Inicie o servidor de desenvolvimento
npm run dev

Acesse http://localhost:5173 no seu navegador.

Build de produção

npm run build
npm run preview

Com Docker

docker compose up --build

O Dockerfile compila o Vite dentro da própria imagem (Node 22) e entrega os arquivos estáticos por um nginx sem privilégios (usuário nginx, porta 8080). Não há artefato pré-construído no repositório.

Imagem publicada

Cada versão é publicada no registro de contêineres do Gitea (linux/arm64):

docker run -p 8080:8080 git.lucasrguerra.dev.br/lucasrguerra/pss:latest

Tags: latest, X.Y.Z, X.Y e sha-<commit>. A instância pública roda em pss.lucasrguerra.dev.br.

Integração contínua e releases

• .gitea/workflows/ci.yml: tipos (tsc -b), testes, Trivy (dependências e segredos), build da imagem, Trivy na imagem e um teste de fumaça (a SPA responde, cai no index nas rotas internas e entrega os assets com cache imutável). Roda nas branches e toda segunda-feira.
• .gitea/workflows/release.yml: na main e nas tags vX.Y.Z. Se o registro já tem a imagem do mesmo conteúdo (inputs-<hash>), nada é refeito: só as tags novas são aplicadas. Numa tag, cria a release no Gitea com as notas do CHANGELOG.
• Para lançar: atualize o CHANGELOG, a versão em package.json e o rótulo em src/components/Layout/Sidebar.tsx, faça o commit e envie a tag (git tag vX.Y.Z && git push gitea vX.Y.Z).

---

🎮 Como usar

1. Crie seus processos: No painel esquerdo, adicione processos definindo nome, tempo de chegada, prioridade e sequência de bursts (CPU e I/O). Ative a opção Usar Threads para criar threads dentro do processo, escolhendo o modelo (MANY_TO_ONE, ONE_TO_ONE ou MANY_TO_MANY) e a política intra-processo (FCFS, RR ou Priority).
2. Configure o escalonador: Escolha o algoritmo e ajuste os parâmetros (quantum para RR, aging para Priority, quantuns e boost para MLFQ, etc.).
3. Execute a simulação: Use os controles de Play/Pause/Step para rodar a simulação na velocidade que quiser (0.25× até 4×).
4. Analise os resultados: O diagrama de Gantt mostra em tempo real o estado de cada processo (e suas threads, quando configuradas). Ao final, o painel de métricas exibe turnaround, waiting time, throughput, e — na aba Threads — métricas individuais por thread.

💡 Dica: Carregue um dos presets disponíveis para ver fenômenos clássicos como o efeito de comboio do FCFS ou starvation com Priority Scheduling.

---

⚙️ Algoritmos Suportados

Algoritmo	Preemptivo?	Parâmetros
FCFS: First Come, First Served	❌	Nenhum
SJF: Shortest Job First	❌	Nenhum
SRTF: Shortest Remaining Time First	✅	Nenhum
Round Robin (RR)	✅	Quantum
Priority NP: Prioridade Não-Preemptiva	❌	Aging (opcional)
Priority P: Prioridade Preemptiva	✅	Aging (opcional)
Priority RR: Prioridade com Round Robin	✅	Quantum + Aging (opcional)
HRRN: Highest Response Ratio Next	❌	Nenhum
Multilevel Queue	✅	Quantum por fila
MLFQ: Multilevel Feedback Queue	✅	Quantuns por fila + intervalo de boost

Consulte a documentação dos algoritmos para detalhes sobre como cada um funciona.

---

📊 Métricas calculadas

Para cada processo simulado, o PSS calcula automaticamente:

• Response Time: tempo até o primeiro uso de CPU
• Turnaround Time: tempo total desde a chegada até o término
• Waiting Time: tempo total na fila Ready
• CPU Time / I/O Time: tempo efetivo em cada tipo de burst
• CPU Utilization: percentual do turnaround em CPU
• Bound Type: classificação automática em CPU Bound, I/O Bound ou Balanced

E globalmente: médias de response/turnaround/waiting, throughput e utilização global de CPU.

---

🗂️ Estrutura do Projeto

src/
├── core/                    # Lógica pura (sem React)
│   ├── algorithms/          # Implementação de cada algoritmo
│   │   ├── base.ts          # Classe abstrata BaseScheduler
│   │   ├── fcfs.ts
│   │   ├── sjf.ts
│   │   ├── rr.ts
│   │   ├── priority.ts
│   │   ├── priority_rr.ts
│   │   ├── hrrn.ts
│   │   ├── multilevel.ts
│   │   ├── mlfq.ts          # Multilevel Feedback Queue
│   │   └── index.ts         # Dispatch por algoritmo
│   ├── engine.ts            # SimulationEngine, orquestra os ticks (suporte a threads)
│   ├── thread-scheduler.ts  # Escalonador intra-processo (FCFS / RR / Priority)
│   ├── metrics.ts           # Cálculo de métricas por processo, globais e por thread
│   ├── types.ts             # Todas as interfaces TypeScript
│   └── presets.ts           # Cenários pré-definidos (processos e threads)
│
├── store/                   # Estado global com Zustand
├── components/              # Componentes React
│   ├── ProcessPanel/        # Criação e edição de processos
│   │   ├── ThreadEditor.tsx # Editor de threads (modelo, política, bursts por thread)
│   │   └── ...
│   ├── SchedulerPanel/      # Seleção de algoritmo e parâmetros
│   ├── ControlBar/          # Play, Pause, Step, Reset, velocidade
│   ├── GanttChart/          # Diagrama de Gantt interativo
│   │   ├── GanttThreadRow.tsx  # Sub-linha de thread no Gantt
│   │   └── ...
│   ├── MetricsPanel/        # Tabela, gráficos e métricas globais
│   │   ├── ThreadMetricsTable.tsx  # Tabela de métricas por thread
│   │   └── ...
│   └── shared/              # Botões, badges, tooltips, modais
│       ├── threadUtils.ts   # Derivação de cores de threads (HSL)
│       └── ...
│
└── hooks/                   # Hooks personalizados (loop de animação, export, etc.)

---

📦 Presets disponíveis

Carregue cenários clássicos com um clique para explorar fenômenos de SO:

Processos:

Preset	O que demonstra
classic_fcfs	Execução básica com FCFS, sem I/O
convoy_effect	Efeito de comboio: um processo longo bloqueando vários curtos
rr_demo	Revezamento justo com Round Robin (quantum=3)
starvation	Processos de baixa prioridade nunca recebem CPU
aging_fix	O mesmo cenário de starvation, resolvido com aging
io_heavy	Mix de processos CPU Bound vs I/O Bound
multilevel_demo	Múltiplas filas com prioridades diferentes

Threads:

Preset	O que demonstra
many_to_one	Modelo N:1 — I/O de uma thread bloqueia todo o processo
one_to_one	Modelo 1:1 — threads bloqueiam independentemente
many_to_many	Modelo N:M — slots de kernel limitam o paralelismo
thread_starvation	Starvation intra-processo com política Priority
threads_vs_processes	Comparação direta: processo com threads vs processo único

---

🧪 Testes

# Roda todos os testes unitários
npm test

# Modo watch (re-executa ao salvar)
npm run test:watch

# Com relatório de cobertura
npm run test:coverage

Os testes cobrem a engine de simulação, todos os algoritmos de escalonamento, e o cálculo de métricas.

---

🛠️ Stack Tecnológica

Camada	Tecnologia
Framework UI	React 18
Linguagem	TypeScript 5
Build tool	Vite 6
Estilos	Tailwind CSS 4
Estado global	Zustand 5
Gráficos	Recharts
Ícones	Lucide React
Testes	Vitest + Testing Library

---

📄 Documentação adicional

• 📐 Algoritmos de Escalonamento: descrição detalhada de cada algoritmo, regras de desempate e exemplos
• 📏 Métricas: fórmulas e definições de todas as métricas calculadas
• 📝 JOSS Paper: artigo científico submetido ao Journal of Open Source Software

Also available in: 🇺🇸 English

---

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, consulte nosso guia em CONTRIBUTING.md para obter detalhes sobre como configurar o ambiente de desenvolvimento, reportar bugs ou enviar um Pull Request.

---

📜 Licença

Distribuído sob a Licença MIT. Desenvolvido por Lucas Rayan Guerra.