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.
-
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.
- Java 21 (project configured to use a Java 21 toolchain).
- Gradle (optional — you can compile and run via
javac/javabut Gradle is recommended). comp512p2.jarmust be present in the repository root.
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.
Two main entry points are provided: an interactive app and an automated app.
- 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,Dto broadcast moves;Eends the process. - The app uses Paxos to achieve total order;
broadcastTOMsgblocks until consensus for the move is reached.
- Enter
- 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 viaFailCheck.
- Each process writes a process-info log file using a
FileHandlerwith a name like:<gameid>-<myProcessWithColonReplaced>-<playernum>-processinfo-.log
- Example sample logs are included under
comp512st/testsandcomp512st/tiapp.
- Per-slot Paxos instances: each broadcast occupies a sequential
instanceNumber(a total-order slot). PaxosMessageHandlerlistens 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 majorityACCEPTEDit broadcastsCONFIRM.
PaxosAcceptor:- Tracks
maxBallotPromised,acceptedValue, andacceptedUUID. - Replies appropriately with
PROMISE,PROMISE_WITH_ACCEPTED,REFUSE,DENY,ACCEPTED.
- Tracks
- Delivery:
- On
CONFIRMfor the current slot, the value is delivered to the application viaPaxos.deliverToApplication, whichacceptTOMsg()reads from.
- On
- Concurrency:
- A background listener thread in
PaxosMessageHandlerprocesses incoming messages. - The proposer waits on per-instance locks;
CountDownLatchis used by the API to block until the caller's proposal is accepted.
- A background listener thread in
- 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.
- 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_FACTORand proposer timeouts. Debugcurrently logs at SEVERE level; adjust logging levels or add more granular logging if needed.- The default blocking timeout inside
broadcastTOMsgis relatively large (180s). For faster feedback during development, reduce it.