|
1 | | -Live demo: https://leiding01.github.io/fsm-educational-tool/ |
2 | | -Focus: Minimal, reproducible educational tool. Planned: NFA + ε-closure and subset construction; keyboard shortcuts; tutorial mode. |
| 1 | +# Distributed Mutual Exclusion Explorer (Variant 3) |
3 | 2 |
|
4 | | -# FSM Educational Tool — DFA (v0.2) |
| 3 | +A dependency-free, browser-based interactive tool for learning **Distributed Mutual Exclusion** concepts. |
| 4 | +It visualises how *token-based* and *message-based* algorithms enforce exclusive access to a critical section, and how **faults** affect safety and liveness. |
5 | 5 |
|
6 | | -[](https://leiding01.github.io/fsm-educational-tool/) |
| 6 | +This repository is structured as a single artefact (the `index.html` app) plus evaluation and report materials. |
7 | 7 |
|
8 | | -A minimal, teaching-oriented web tool to build and run deterministic finite automata (DFA). |
9 | | -This version adds a **trace panel**, **delete state**, a simple **Undo**, and a **preview canvas with PNG export**. |
10 | | -The codebase is dependency-free (HTML/JS/CSS) and runs locally or on GitHub Pages. |
| 8 | +--- |
| 9 | + |
| 10 | +## What this artefact is |
| 11 | + |
| 12 | +**Technology artefact:** an interactive web simulator/visualiser for distributed mutual exclusion (educational tool). |
| 13 | +**Stack:** plain HTML/CSS/JavaScript (no framework, no external dependencies), runs locally or on GitHub Pages. |
| 14 | + |
| 15 | +--- |
| 16 | + |
| 17 | +## Implemented / supported |
11 | 18 |
|
12 | | -## Highlights (engineering-focused) |
13 | | -- Deterministic finite automata (DFA) **visualiser**: trace panel, delete state, Undo, preview canvas with **Export PNG**, **JSON import/export**. |
14 | | -- Defensive UI: prevents duplicate `(state, symbol)` transitions; clear error messages (e.g. missing δ-transition). |
15 | | -- Reproducible set-up: one-click local server scripts, example models, black-box tests, a timing CSV, and a Nielsen heuristic checklist. |
16 | | -- Clean, dependency-free front-end that works offline and on GitHub Pages. |
| 19 | +### Algorithms |
| 20 | +- **Token Ring** (implemented) |
| 21 | +- **Ricart–Agrawala** (prototype) |
17 | 22 |
|
18 | | -## Roadmap (v0.3 — planned, small and safe) |
19 | | -- **NFA** support with **ε-closure**, plus **subset construction** view (NFA→DFA) and dual-view toggle. |
20 | | -- **Redo** and keyboard shortcuts (Ctrl+Z, Del, Enter), with lightweight toast notifications. |
21 | | -- One-click **Export ZIP** (current JSON + PNG preview). |
22 | | -- Small test pack (≈10 JSON models) + batch timing; **Tutorial mode** (short guided steps) if time allows. |
| 23 | +### Interactions |
| 24 | +- Configure number of processes (small n recommended for teaching clarity) |
| 25 | +- Issue **Request CS** / **Release CS** |
| 26 | +- Step / Run execution |
| 27 | +- Scripted demo replays via JSON scenarios |
23 | 28 |
|
24 | | -> The roadmap will be tracked as GitHub Issues for transparency and scope control. |
| 29 | +### Fault injection + recovery (teaching-oriented) |
| 30 | +- Token Ring: token loss + token regeneration |
| 31 | +- Token Ring / RA: process crash + recover |
| 32 | +- Ricart–Agrawala: message faults |
| 33 | + - **Drop next in-flight message** (drops the queue head) |
| 34 | + - **Drop-next-send** (arm/disarm; drops the next outgoing message) |
25 | 35 |
|
26 | | -## Evaluation & reproducibility |
27 | | -- Black-box examples in `examples/`, expected behaviours in `tests/spec_fsm_core.md`. |
28 | | -- Timing sheet: `eval/fsm_timing.csv`; usability checklist: `eval/nielsen_checklist.md`. |
29 | | -- Figures/screenshots in `report/figures/` (used as evidence in the checklist). |
30 | | -- Exportable artefacts: JSON models and PNG previews enable exact reproduction. |
| 36 | +Notes: |
| 37 | +- In Ricart–Agrawala, message loss can break **liveness** (progress) while preserving **safety**. This is intentional and used as a teaching point (e.g., “waiting for REPLY from …”). |
31 | 38 |
|
32 | 39 | --- |
33 | 40 |
|
34 | | -## Quick start |
35 | | -- Open this folder in VS Code and use *Live Server* **or** run: |
36 | | - ```bash |
37 | | - python -m http.server 5500 |
38 | | - ``` |
39 | | - then visit <http://localhost:5500/index.html>. |
40 | | - |
41 | | -- Windows: `start_server.bat` |
42 | | -- macOS/Linux: `start_server.sh` |
43 | | - |
44 | | -## Features |
45 | | -- Create/delete states; set start and accept states. |
46 | | -- Add/delete transitions (**DFA rule**: at most one per `(state, symbol)`). |
47 | | -- Run/Step an input string; see **ACCEPT/REJECT** and the **trace**. |
48 | | -- Import/Export JSON. |
49 | | -- Preview canvas (circular layout) and **Export PNG**. |
50 | | -- **Undo** common actions (add/delete state, add/delete transition, set start/accepts, clear all). |
51 | | - |
52 | | -## JSON schema (simplified) |
53 | | -```json |
54 | | -{ |
55 | | - "states": ["q0", "q1"], |
56 | | - "alphabet": ["a", "b"], |
57 | | - "start": "q0", |
58 | | - "accepts": ["q1"], |
59 | | - "transitions": [ |
60 | | - {"from": "q0", "symbol": "a", "to": "q1"} |
61 | | - ], |
62 | | - "type": "DFA" |
63 | | -} |
| 41 | +## Quick start (local) |
| 42 | + |
| 43 | +From the repository root: |
| 44 | + |
| 45 | +```bash |
| 46 | +python -m http.server 5500 |
64 | 47 | ``` |
65 | 48 |
|
66 | | -## Notes |
67 | | -- The preview uses a simple circular layout; it is sufficient for small to medium graphs. |
68 | | -- Self-loops are drawn above the state; multiple symbols between two states are merged with comma-separated labels. |
69 | | -- No personal data are collected; examples are synthetic. |
| 49 | +Open: |
| 50 | + |
| 51 | +- http://localhost:5500/ |
| 52 | + |
| 53 | +Windows users can also run a `.bat` server script if included in the repo. |
| 54 | + |
| 55 | +--- |
| 56 | + |
| 57 | +## How to use (typical) |
| 58 | + |
| 59 | +1. Choose an algorithm (Token Ring or Ricart–Agrawala) |
| 60 | +2. Set **Processes** (try 3–8 for readability), click **Apply (reset)** |
| 61 | +3. Use **Request CS** for one or more processes |
| 62 | +4. Click **Step** (or **Run**) to observe token passing or message delivery |
| 63 | +5. Use faults to demonstrate: |
| 64 | + - Token loss → no progress → regenerate |
| 65 | + - Crash/recover behaviour |
| 66 | + - RA message drop → stalled waiting for missing REPLY (liveness failure) |
| 67 | + |
| 68 | +--- |
| 69 | + |
| 70 | +## Evidence exports (keeping the repo clean) |
| 71 | + |
| 72 | +The tool supports exporting: |
| 73 | +- **State JSON** |
| 74 | +- **Trace TXT** |
| 75 | +- **Preview PNG** |
| 76 | +- **Evidence bundle** (JSON + trace + PNG) |
| 77 | + |
| 78 | +Generated exports should go into: |
| 79 | + |
| 80 | +- `report/figures/export/` |
| 81 | + |
| 82 | +This folder is **ignored by git** so the repository stays clean. |
| 83 | +If a figure is referenced in the final report, copy it into: |
| 84 | + |
| 85 | +- `report/figures/` |
| 86 | + |
| 87 | +and reference that curated file instead. |
| 88 | + |
| 89 | +--- |
| 90 | + |
| 91 | +## Repository layout |
| 92 | + |
| 93 | +- `index.html` — UI shell |
| 94 | +- `mutex_main.js` — UI wiring, rendering, exports |
| 95 | +- `mutex_core.js` — algorithm models + step logic (Token Ring + RA prototype) |
| 96 | +- `examples/` — scripted demo scenarios (JSON) |
| 97 | +- `eval/` — evaluation materials (e.g., heuristics checklist, test plan) |
| 98 | +- `report/` — report drafts, figures, and curated evidence |
| 99 | + |
| 100 | +--- |
| 101 | + |
| 102 | +## Testing (recommended) |
| 103 | + |
| 104 | +### Manual test plan |
| 105 | +See: |
| 106 | + |
| 107 | +- `eval/test_plan.md` |
| 108 | + |
| 109 | +This contains repeatable test cases with expected behaviours (Token Ring safety, token loss/recovery, crash/recover, RA conflict/tiebreak, RA message-loss stall). |
| 110 | + |
| 111 | +### Optional automated smoke tests |
| 112 | +If you add the lightweight Node-based smoke tests: |
| 113 | + |
| 114 | +```bash |
| 115 | +cd ds-mutex |
| 116 | +npm test |
| 117 | +``` |
| 118 | + |
| 119 | +(Only include this section if your repo actually contains the `package.json` + test runner.) |
| 120 | + |
| 121 | +--- |
| 122 | + |
| 123 | +## Versioning and freeze policy (recommended for dissertation evidence) |
| 124 | + |
| 125 | +- Use tags (e.g., `v0.3.1`) to freeze behaviour and exported evidence. |
| 126 | +- Only do bug fixes after a freeze; avoid feature churn that invalidates report screenshots/traces. |
70 | 127 |
|
71 | 128 | --- |
72 | 129 |
|
73 | | -not part of final artefact |
| 130 | +## Licence |
74 | 131 |
|
75 | | -## Student |
76 | | -- Name: **Lei Ding** |
77 | | -- K number: **K21029011** |
| 132 | +Add a licence if required by your course / publication method (e.g., MIT). If not, state “All rights reserved” by default. |
0 commit comments