diff options
Diffstat (limited to 'docs/ARCHITECTURE.md')
| -rw-r--r-- | docs/ARCHITECTURE.md | 397 |
1 files changed, 397 insertions, 0 deletions
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..f222850 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,397 @@ +# DS-Sim Architecture Documentation + +## Table of Contents +1. [Overview](#overview) +2. [Core Architecture](#core-architecture) +3. [Event-Driven Design](#event-driven-design) +4. [Protocol Framework](#protocol-framework) +5. [Time Management](#time-management) +6. [Message System](#message-system) +7. [Component Diagrams](#component-diagrams) +8. [Sequence Diagrams](#sequence-diagrams) + +## Overview + +DS-Sim is an event-driven distributed systems simulator built with Java. It provides a visual environment for simulating and understanding distributed algorithms, protocols, and time synchronization mechanisms. + +### Key Design Principles +- **Event-Driven Architecture**: All actions are modeled as events +- **Pluggable Protocols**: Easy to add new distributed algorithms +- **Visual Feedback**: Real-time visualization of process states and messages +- **Time Simulation**: Support for logical clocks and clock drift + +## Core Architecture + +### Layer Diagram +``` +┌─────────────────────────────────────────────────────────────┐ +│ User Interface Layer │ +│ VSSimulatorFrame, VSSimulator, VSSimulatorVisualization │ +├─────────────────────────────────────────────────────────────┤ +│ Protocol Layer │ +│ VSAbstractProtocol, Protocol Implementations │ +├─────────────────────────────────────────────────────────────┤ +│ Event System Layer │ +│ VSAbstractEvent, VSTask, VSTaskManager │ +├─────────────────────────────────────────────────────────────┤ +│ Core Process Layer │ +│ VSAbstractProcess, VSInternalProcess, VSMessage │ +├─────────────────────────────────────────────────────────────┤ +│ Infrastructure Layer │ +│ Time Management, Serialization, Utilities │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Component Overview + +```mermaid +graph TB + subgraph UI[User Interface] + Frame[VSSimulatorFrame] + Sim[VSSimulator] + Viz[VSSimulatorVisualization] + end + + subgraph Core[Core Components] + TM[VSTaskManager] + IP[VSInternalProcess] + Msg[VSMessage] + end + + subgraph Events[Event System] + AE[VSAbstractEvent] + Task[VSTask] + RE[VSRegisteredEvents] + end + + subgraph Protocols[Protocols] + AP[VSAbstractProtocol] + PP[PingPongProtocol] + BC[BroadcastProtocol] + TC[TwoPhaseCommit] + end + + Frame --> Sim + Sim --> Viz + Viz --> TM + TM --> Task + Task --> AE + IP --> Msg + AP --> AE + PP --> AP + BC --> AP + TC --> AP +``` + +## Event-Driven Design + +The simulator operates on an event-driven model where all actions are encapsulated as events that are scheduled and executed by the task manager. + +### Event Hierarchy + +```mermaid +classDiagram + class VSAbstractEvent { + <<abstract>> + +onInit() + +onStart() + +getClassname() + +isInternalEvent() + +shouldIncreaseTimestamps() + } + + class VSAbstractProtocol { + <<abstract>> + +onServerInit() + +onClientInit() + +onServerRecv() + +onClientRecv() + +sendMessage() + } + + class VSProcessCrashEvent { + +onStart() + } + + class VSMessageReceiveEvent { + +onStart() + } + + class VSTimestampTriggeredEvent { + <<abstract>> + +checkCondition() + +onTimestampReached() + } + + VSAbstractEvent <|-- VSAbstractProtocol + VSAbstractEvent <|-- VSProcessCrashEvent + VSAbstractEvent <|-- VSMessageReceiveEvent + VSAbstractEvent <|-- VSTimestampTriggeredEvent +``` + +### Event Lifecycle + +1. **Creation**: Events are created with specific parameters +2. **Initialization**: `onInit()` is called once when first added +3. **Scheduling**: Events are wrapped in `VSTask` with execution time +4. **Execution**: `onStart()` is called when scheduled time arrives +5. **Completion**: Event completes or schedules new events + +## Protocol Framework + +Protocols implement distributed algorithms and define client-server communication patterns. + +### Protocol Structure + +```mermaid +stateDiagram-v2 + [*] --> Uninitialized + Uninitialized --> ServerInit: isServer + Uninitialized --> ClientInit: isClient + + ServerInit --> ServerReady + ClientInit --> ClientReady + + ServerReady --> ServerStart: hasOnServerStart + ClientReady --> ClientStart: !hasOnServerStart + + ServerReady --> ServerRecv: receive message + ClientReady --> ClientRecv: receive message + + ServerReady --> ServerSchedule: scheduled event + ClientReady --> ClientSchedule: scheduled event +``` + +### Protocol Implementation Pattern + +```java +public class MyProtocol extends VSAbstractProtocol { + public MyProtocol() { + super(HAS_ON_SERVER_START); // or HAS_ON_CLIENT_START + } + + // Server-side methods + public void onServerInit() { /* Initialize server state */ } + public void onServerStart() { /* Server begins protocol */ } + public void onServerRecv(VSMessage msg) { /* Handle client message */ } + public void onServerSchedule() { /* Periodic server action */ } + + // Client-side methods + public void onClientInit() { /* Initialize client state */ } + public void onClientStart() { /* Client begins protocol */ } + public void onClientRecv(VSMessage msg) { /* Handle server message */ } + public void onClientSchedule() { /* Periodic client action */ } +} +``` + +## Time Management + +The simulator supports multiple time representations for distributed systems research. + +### Time Types + +```mermaid +graph LR + subgraph Time System + GT[Global Time<br/>Simulation Clock] + LT[Local Time<br/>Process Clock] + LAM[Lamport Time<br/>Logical Clock] + VT[Vector Time<br/>Vector Clock] + end + + GT --> LT + LT --> LAM + LT --> VT +``` + +### Clock Synchronization + +- **Global Time**: Absolute simulation time (milliseconds) +- **Local Time**: Process time with configurable drift +- **Lamport Time**: Increments on events and messages +- **Vector Time**: Array of logical times for each process + +### Clock Drift Simulation + +``` +Local Time = Global Time + Accumulated Drift +Drift Rate = Clock Variance (e.g., -0.1 to +0.1) +``` + +## Message System + +Messages in DS-Sim carry protocol data between processes with automatic timestamp management. + +### Message Flow + +```mermaid +sequenceDiagram + participant P1 as Process 1 + participant TM as TaskManager + participant Net as Network Sim + participant P2 as Process 2 + + P1->>P1: Increase timestamps + P1->>TM: Create send task + TM->>Net: Schedule with delay + Net->>TM: Create receive task + TM->>P2: Deliver message + P2->>P2: Update timestamps + P2->>P2: Process message +``` + +### Message Properties + +- **Sender/Receiver**: Process IDs +- **Protocol**: Associated protocol class +- **Timestamps**: Lamport and vector times +- **Payload**: Serializable data +- **Type**: Server or client message + +## Component Diagrams + +### Task Management System + +```mermaid +graph TB + subgraph TaskManager + PQ[Priority Queue<br/>Time-ordered tasks] + GL[Global Tasks<br/>Simulation time] + LL[Local Tasks<br/>Process time] + end + + subgraph Task Execution + Run[runTasks<br/>Main loop] + Exec[Execute task] + Update[Update times] + end + + PQ --> Run + Run --> Exec + Exec --> Update + Update --> PQ +``` + +### Process Architecture + +```mermaid +classDiagram + class VSAbstractProcess { + <<abstract>> + #localTime: long + #globalTime: long + #lamportTime: long + #vectorTime: VSVectorTime + +increaseTime() + +sendMessage() + } + + class VSInternalProcess { + -clockVariance: float + -clockOffset: double + -vectorClockMonitor: VSVectorClockMonitor + +syncTime(globalTime) + +highlightOn() + +crash() + +recover() + } + + VSAbstractProcess <|-- VSInternalProcess +``` + +## Sequence Diagrams + +### Protocol Initialization + +```mermaid +sequenceDiagram + participant UI as User Interface + participant Reg as VSRegisteredEvents + participant Proto as Protocol + participant Proc as Process + + UI->>Reg: Select protocol + Reg->>Proto: Create instance + Proto->>Proc: Set process + Proc->>Proto: isServer(true/false) + Proto->>Proto: onServerInit/onClientInit + Proto->>UI: Ready +``` + +### Event Processing Loop + +```mermaid +sequenceDiagram + participant Viz as Visualization + participant TM as TaskManager + participant Task as VSTask + participant Event as Event + participant Proc as Process + + loop Simulation Loop + Viz->>TM: runTasks(currentTime) + TM->>TM: Get ready tasks + TM->>Task: run() + Task->>Event: onStart() + Event->>Proc: Update state + Event->>TM: Schedule new tasks + end +``` + +### Two-Phase Commit Example + +```mermaid +sequenceDiagram + participant Coord as Coordinator + participant P1 as Process 1 + participant P2 as Process 2 + + Coord->>P1: VOTE_REQUEST + Coord->>P2: VOTE_REQUEST + P1->>Coord: VOTE_YES + P2->>Coord: VOTE_YES + Coord->>Coord: All votes YES + Coord->>P1: GLOBAL_COMMIT + Coord->>P2: GLOBAL_COMMIT + P1->>Coord: ACK + P2->>Coord: ACK +``` + +## Adding New Components + +### Creating a New Event + +1. Extend `VSAbstractEvent` +2. Implement `onInit()` and `onStart()` +3. Register in `VSRegisteredEvents.init()` + +### Creating a New Protocol + +1. Extend `VSAbstractProtocol` +2. Implement required abstract methods +3. Choose `HAS_ON_SERVER_START` or `HAS_ON_CLIENT_START` +4. Register in `VSRegisteredEvents.init()` + +### Creating Timestamp-Triggered Events + +1. Extend `VSTimestampTriggeredEvent` +2. Implement `onTimestampReached()` +3. Configure trigger conditions +4. Register with process monitor + +## Design Patterns Used + +- **Template Method**: Protocol base class defines structure +- **Observer**: Event system for loose coupling +- **Strategy**: Pluggable protocols and events +- **Factory**: Event creation through registry +- **Singleton**: Global registries and managers +- **Command**: Events encapsulate actions + +## Future Architecture Improvements + +1. **GUI Separation**: Extract UI from business logic +2. **Dependency Injection**: Remove static registries +3. **Event Bus**: Decouple component communication +4. **Plugin System**: Dynamic protocol loading +5. **Reactive Streams**: Modern async event handling
\ No newline at end of file |