Skip to main content

​
Quickstart Guide

This guide will help you run your first synchronization simulation and understand the basic controls.

​
Opening the Simulator

The simulator is a static HTML application that runs entirely in your browser.
1

Open the simulator

Open index.html in your web browser. You’ll see the algorithm selection screen.
2

Choose an algorithm

Select one of the seven available synchronization algorithms. For this quickstart, we’ll use Mutex (Bank Account scenario).Click the Mutex button to enter the bank account simulator.

​
Running Your First Simulation

Let’s walk through a complete simulation using the Mutex algorithm with the bank account scenario.
1

Configure the scenario

You’ll see two input fields:
  • Thread count: Number of clients accessing the account (default: 3)
  • Initial balance: Starting account balance (default: $1000)
Leave the defaults and click Generate Scenario.
2

Configure operations

After generating, you’ll see operation rows for each client. Each client can either:
  • Withdraw money (removes from balance)
  • Deposit money (adds to balance)
Example configuration:
Client-1: Withdraw $100
Client-2: Deposit $50
Client-3: Withdraw $75
Configure your operations, then proceed to execution.
3

Execute step-by-step

Click the Step button to execute one instruction at a time.Watch what happens:
  • One thread enters the critical section (acquires mutex)
  • Other threads block and wait in the queue
  • The active thread modifies the balance
  • The mutex transfers to the next waiting thread
Continue clicking Step to see the complete execution.
4

Try automatic execution

Click Auto to run continuously (1 step per second).Click Auto again to pause execution.

​
Understanding the Display

​
State Panel

The state panel shows the current system state:

Current Balance

Real-time account balance as threads withdraw and deposit

Mutex Owner

Shows which thread currently holds the lock, or “Libre” (Free) if unlocked

​
Mutex Queue

Visual representation of threads waiting to acquire the mutex, displayed in FIFO order. 
[Client-2] [Client-3]

​
Thread Cards

Each client has a card showing:
  • Thread name and current state indicator
  • Balance bar (visual representation of transaction amount)
  • Operation type (Withdraw/Deposit) and amount
  • State badge: Running (blue), Blocked (yellow), Finished (gray), Ready (green)

​
Timeline

The timeline shows a chronological log of all events: 
🔓 Client-1 released and freed the Mutex
💸 Client-1 modified balance: -$100
🔑 Client-1 entered Critical Section
🔒 Client-2 is waiting for the Mutex
Events appear in reverse chronological order (newest at top).

​
What Just Happened?

Let’s break down the execution you just witnessed:
The mutex ensures that only one thread can access the shared account.balance at a time. This prevents race conditions where simultaneous withdrawals could corrupt the balance.
When multiple threads try to acquire a locked mutex, they wait in a First-In-First-Out queue. This guarantees fairness - no thread waits forever.
When a thread releases the mutex, ownership transfers directly to the next waiting thread. The mutex never becomes “free” if threads are waiting, improving efficiency.
Each WITHDRAW or DEPOSIT operation completes atomically inside the critical section. No other thread can observe a partial state change.

​
The Instruction Sequence

Behind the scenes, each client thread executes these instructions: 
const client = new Thread("Client-1", [
  { type: Instructions.ACQUIRE },      // Try to lock mutex
  { type: Instructions.WITHDRAW, amount: 100 },  // Modify balance
  { type: Instructions.RELEASE },      // Unlock mutex
  { type: Instructions.END }           // Terminate
]);
The Engine executes these instructions one tick at a time:
  1. ACQUIRE: Thread attempts to lock the mutex
    • If free: Lock acquired, thread enters critical section
    • If locked: Thread blocks and joins the queue
  2. WITHDRAW/DEPOSIT: Thread modifies shared balance
    • This only happens after acquiring the mutex
    • Operation is atomic and isolated from other threads
  3. RELEASE: Thread unlocks the mutex
    • If queue is empty: Mutex becomes free
    • If threads are waiting: Direct transfer to next in queue

​
Try Other Algorithms

Now that you understand the basics, explore the other synchronization primitives:

Semaphores

Control access to a limited pool of resources (printers)

Condition Variables

Wait efficiently for events (restaurant food service)

Monitors

High-level readers-writer coordination (library catalog)

Barriers

Synchronize at checkpoints (race coordination)

Join/Await

Wait for task dependencies (house construction)

Peterson's Algorithm

Two-thread mutual exclusion without hardware (robots sharing station)

​
Next Steps

Architecture

Learn how the simulator works internally

Core Concepts

Understand threads, instructions, and execution

API Reference

Explore the technical API documentation