Documentation#
Distributed Systems Playground is a browser tool for writing distributed algorithms in textbook pseudocode and watching them run on a simulated network. These pages explain how to use it, what it models, and where it simplifies.
The same pages are published as a documentation site with navigation and search. In a copy of the repository, open manual/index.html.
Where to start#
| If you want to | Read |
|---|---|
| try it in twenty minutes | Getting started |
| brush up on the theory | Concepts |
| explore ready-made scenarios | Examples |
| use it in a course | Teaching with the playground |
| know what the simulator leaves out | Assumptions and simplifications |
Reference#
| Page | Content |
|---|---|
| The interface | every panel, control, visual mark and shortcut |
| The Upon language | syntax, semantics, built-ins, checks and errors |
| The module library | links and broadcast modules, their guarantees and costs |
| The timing model | assumed and actual models, distributions, presets, rounds, GST |
| Faults | crashes, recoveries, link failures, partitions |
| How the engine works | event ordering, steps, message handling, determinism |
| How the project is put together | the diagram of the pieces and how they fit |
| A guided tour | seven scenarios in order, each showing one thing the playground is for |
| Running scenarios outside the browser | the command line tool and the batch runner API |
| Questions, related tools and references | what it is and is not, how it compares, what to read |
| Troubleshooting | symptoms, causes, fixes and error messages |
| Specification | the design document, grammar and implementation status |
| Changelog | what changed in each version |
A note on trust#
Every run is one execution of a model. The model is described precisely in Assumptions and simplifications, and the examples in these pages were checked against the engine: the numbers quoted come from real runs with the stated seeds, and the Upon programs are compiled by the test suite. If you find a statement that does not match what the playground does, please open an issue.