Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

17 Commits

Folders and files

Repository files navigation

COMP512A2 — Paxos Total-Order Broadcast + TreasureIsland Application

This repository contains a Paxos-based total-order broadcast module used by a simple distributed game (TreasureIsland). The implementation lives under comp512st and depends on a provided course JAR: comp512p2.jar.


Repository layout

  • comp512st/paxos/ — Paxos implementation:

    • Paxos.java — public API used by applications:
      • broadcastTOMsg(Object val) — propose a value and block until it is accepted.
      • acceptTOMsg() — receive the next total-ordered message (blocks).
      • shutdownPaxos() — cleanly shutdown Paxos subsystem.
    • PaxosMessage.java — Paxos message types and factories.
    • PaxosMessageHandler.java — receives messages from GCL and coordinates proposer/acceptor/instances.
    • PaxosProposer.java — proposer behavior (ballot, promises, accepts).
    • PaxosAcceptor.java — acceptor behavior (promises, accepts, confirm/deliver).
    • PaxosInstance.java — per-instance (slot) state.
    • Debug.java — logging helper for Paxos internals.
  • comp512st/tiapp/ — interactive TreasureIsland application:

    • comp512st.tiapp.TreasureIslandApp — interactive CLI app that reads moves and broadcasts them via Paxos.
  • comp512st/tests/ — automated test harness:

    • comp512st.tests.TreasureIslandAppAuto — automated move generator (supports injected failure modes).
    • Shell scripts to run, compare, and manage test runs (run_tiapp_auto.sh, compare_run_tiapp.sh, kill_all.sh, rapid_tester.sh, test_and_compare.sh).
    • Sample logs and test outputs.
  • Root:

    • build.gradle — Gradle build configuration (Java 21 toolchain).
    • comp512p2.jar — course-provided dependency (required).
    • Course PDFs and supporting documentation.

Requirements

  • Java 21 (project configured to use a Java 21 toolchain).
  • Gradle (optional — you can compile and run via javac / java but Gradle is recommended).
  • comp512p2.jar must be present in the repository root.

Build

From the repository root:

  • With Gradle:
    • gradle build
    • Or (if you have the wrapper) ./gradlew build (if provided).

Compiled classes are placed under:

  • build/classes/java/main

The build.gradle file configures comp512st as the source directory and declares a local file dependency on comp512p2.jar.


Run

Two main entry points are provided: an interactive app and an automated app.

  1. Interactive TreasureIsland App
  • Main class: comp512st.tiapp.TreasureIslandApp
  • Usage:
    • java -cp build/classes/java/main:comp512p2.jar comp512st.tiapp.TreasureIslandApp <myProcess> <allProcessesCommaSeparated> <gameid> <numplayers> <playernum>
  • Example (three processes; open three terminals):
    • java -cp build/classes/java/main:comp512p2.jar comp512st.tiapp.TreasureIslandApp localhost:40139 localhost:40139,localhost:40239,localhost:40339 game-39-99 3 1
    • (repeat for other player ports and player ids)
  • Notes:
    • Enter L, R, U, D to broadcast moves; E ends the process.
    • The app uses Paxos to achieve total order; broadcastTOMsg blocks until consensus for the move is reached.
  1. Automated App (move generator)
  • Main class: comp512st.tests.TreasureIslandAppAuto
  • Usage:
    • java -cp build/classes/java/main:comp512p2.jar comp512st.tests.TreasureIslandAppAuto <myProcess> <allProcessesCommaSeparated> <gameid> <numplayers> <playernum> <maxmoves> <interval_ms> <randseed> [FAILMODE]
  • Example:
    • java -cp build/classes/java/main:comp512p2.jar comp512st.tests.TreasureIslandAppAuto localhost:40139 localhost:40139,localhost:40239,localhost:40339 game-39-99 3 1 200 200 42
  • FAILMODE (optional): IMMEDIATE, RECEIVEPROPOSE, AFTERSENDVOTE, AFTERSENDPROPOSE, AFTERBECOMINGLEADER, AFTERVALUEACCEPT. Those map to short codes used by the automated generator and cause the process to simulate failures at specific failure points via FailCheck.

Logging

  • Each process writes a process-info log file using a FileHandler with a name like:
    • <gameid>-<myProcessWithColonReplaced>-<playernum>-processinfo-.log
  • Example sample logs are included under comp512st/tests and comp512st/tiapp.

How Paxos is organized (design notes)

  • Per-slot Paxos instances: each broadcast occupies a sequential instanceNumber (a total-order slot).
  • PaxosMessageHandler listens to the GCL and dispatches messages to proposer and acceptor logic.
  • PaxosProposer:
    • Uses ballot numbers that incorporate the process number and an aging factor to break ties and encourage progress.
    • Runs rounds with timeouts and jitter; uses exponential backoff on no responses.
    • On majority promise (or promise-with-accepted) it sends ACCEPT. On majority ACCEPTED it broadcasts CONFIRM.
  • PaxosAcceptor:
    • Tracks maxBallotPromised, acceptedValue, and acceptedUUID.
    • Replies appropriately with PROMISE, PROMISE_WITH_ACCEPTED, REFUSE, DENY, ACCEPTED.
  • Delivery:
    • On CONFIRM for the current slot, the value is delivered to the application via Paxos.deliverToApplication, which acceptTOMsg() reads from.
  • Concurrency:
    • A background listener thread in PaxosMessageHandler processes incoming messages.
    • The proposer waits on per-instance locks; CountDownLatch is used by the API to block until the caller's proposal is accepted.

Testing and helper scripts

  • Use scripts under comp512st/tests/ to automate starting multiple processes and comparing results:
    • run_tiapp_auto.sh — helper script to launch automated instances.
    • compare_run_tiapp.sh, test_and_compare.sh — utilities to compare logs.
    • rapid_tester.sh — run many short tests rapidly.
    • kill_all.sh — terminate processes started by tests.

Caveats & possible improvements

  • The code assumes semantics provided by comp512p2.jar (comp512.gcl.GCL) — make sure that JAR is on the classpath at runtime.
  • Ballot numbering and timeouts are tuned for the assignment; under different conditions you may want to adjust AGING_FACTOR and proposer timeouts.
  • Debug currently logs at SEVERE level; adjust logging levels or add more granular logging if needed.
  • The default blocking timeout inside broadcastTOMsg is relatively large (180s). For faster feedback during development, reduce it.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages