Skip to main content

​
Thread Class

The Thread class represents an execution unit in the simulator. Each thread has its own instruction sequence and execution state.

​
Constructor

Creates a new thread with a name and instruction list. 
const thread = new Thread(name, instructions);
​
name
string
required
Human-readable identifier displayed in the UI (e.g., “Client-1”, “Job-3”)
​
instructions
Array<object>
required
Ordered list of instruction objects to execute

​
Properties

​
name
string
Thread identifier used in logs and UI rendering
​
instructions
Array<object>
Complete instruction sequence for this thread
​
pc
number
Program counter - index of the current instruction (starts at 0)
​
state
string
Current execution state: "ready", "running", "blocked", or "finished"
​
blockedBy
object | null
Reference to the synchronization primitive blocking this thread (Mutex, Semaphore, etc.)

​
Methods

​
currentInstruction()

Returns the instruction at the current program counter position.
​
instruction
object | undefined
The instruction object at index pc, or undefined if no more instructions
thread.js
currentInstruction() {
  return this.instructions[this.pc];
}

​
nextInstruction()

Advances the program counter to the next instruction.
thread.js
nextInstruction() {
  this.pc++;
}

​
Thread States

Threads transition through four states during execution:

ready

Initial state. Thread is eligible to run in the next step.

running

Currently executing an instruction (set by Engine during step).

blocked

Waiting for a resource (mutex, semaphore, condition variable, etc.).

finished

No more instructions to execute. Thread is done.

​
State Transitions

​
Usage Examples

​
Basic Thread Creation

import { Thread } from "./core/thread.js";
import { Instructions } from "./core/instructions.js";

const client = new Thread("Client-1", [
  { type: Instructions.ACQUIRE },
  { type: Instructions.WITHDRAW, amount: 100 },
  { type: Instructions.RELEASE }
]);

console.log(client.name);  // "Client-1"
console.log(client.state); // "ready"
console.log(client.pc);    // 0

​
Instruction Iteration

const thread = new Thread("Worker", [
  { type: Instructions.ACQUIRE },
  { type: Instructions.DEPOSIT, amount: 50 },
  { type: Instructions.RELEASE }
]);

while (thread.currentInstruction()) {
  const inst = thread.currentInstruction();
  console.log(`Executing: ${inst.type}`);
  thread.nextInstruction();
}

console.log(thread.pc); // 3 (past end of instructions)
console.log(thread.currentInstruction()); // undefined

​
Checking Thread State

if (thread.state === "blocked") {
  console.log(`${thread.name} is blocked by:`, thread.blockedBy.constructor.name);
  // Example output: "Client-2 is blocked by: Mutex"
}

if (thread.state === "finished") {
  console.log(`${thread.name} has completed execution`);
}

​
Blocking Operations

When a thread encounters a blocking instruction (like ACQUIRE when the mutex is locked), the Engine sets: 
thread.state = "blocked";
thread.blockedBy = mutex; // Reference to the blocking resource
The thread remains in this state until the resource releases it: 
thread.state = "ready";
thread.blockedBy = null;
The program counter (pc) does NOT advance when a thread blocks. The thread will retry the same instruction in the next step.

​
Thread Lifecycle Example

import { Engine } from "./core/engine.js";
import { Thread } from "./core/thread.js";
import { Mutex } from "./core/mutex.js";
import { Instructions } from "./core/instructions.js";

const engine = new Engine();
const mutex = new Mutex();
const context = { mutex, account: { balance: 1000 } };

const thread = new Thread("Client-1", [
  { type: Instructions.ACQUIRE },
  { type: Instructions.WITHDRAW, amount: 100 },
  { type: Instructions.RELEASE }
]);

engine.addThread(thread);

// Step 1: Acquire mutex
console.log(thread.state); // "ready"
engine.step(context);
console.log(thread.state); // "ready"
console.log(thread.pc);    // 1 (advanced)

// Step 2: Withdraw money
engine.step(context);
console.log(thread.pc);    // 2

// Step 3: Release mutex
engine.step(context);
console.log(thread.pc);    // 3

// Step 4: No more instructions
engine.step(context);
console.log(thread.state); // "finished"

​
Scenario-Specific Properties

Some scenarios add temporary properties to threads: 
// Restaurant scenario
thread.hasReservedDish = true;

// Printer scenario
thread.jobPages = 10;

// Join scenario
thread.stageName = "Foundation";
thread.duration = 3;
These properties are used by the Engine’s execute() method for scenario-specific logic.
  • Engine - Execution engine that processes threads
  • Instructions - Instruction type definitions