docs: refine HW-09 README
This commit is contained in:
@@ -69,56 +69,69 @@ Explain why this might happen from a thread-scheduling perspective.
|
||||
Describe two strategies a developer can use to increase the likelihood of exposing deadlocks during testing.
|
||||
|
||||
---
|
||||
|
||||
## 💻 Practical Project
|
||||
|
||||
## 🏦 Advanced Banking & Transaction Processing System
|
||||
## 🏦 Advanced Banking & Concurrent Transaction System
|
||||
|
||||
---
|
||||
|
||||
### 🧭 Overview
|
||||
|
||||
Modern banking systems process thousands of transactions concurrently. Multiple worker threads may read account data, update balances, or transfer money between accounts simultaneously.
|
||||
In modern banking systems, thousands of transactions are processed concurrently by multiple worker threads. These threads may access shared bank accounts simultaneously, leading to potential race conditions and consistency issues.
|
||||
|
||||
In this assignment, you will implement the **concurrency control layer** of a banking system. The goal is to ensure:
|
||||
In this assignment, you will implement the **core concurrency control layer** of a banking simulation system.
|
||||
|
||||
Your goal is to ensure:
|
||||
|
||||
* Correctness under concurrent execution
|
||||
* Absence of race conditions
|
||||
* Deadlock-free transfers
|
||||
* Reasonable concurrency performance
|
||||
* consistent account state under concurrent execution
|
||||
* Deadlock-free transfer operations
|
||||
* Reasonable concurrency and scalability
|
||||
|
||||
Students are expected to design their own synchronization strategy from scratch.
|
||||
|
||||
---
|
||||
|
||||
### 📦 Provided Components (IMPORTANT)
|
||||
### 📦 Provided System (DO NOT MODIFY)
|
||||
|
||||
The following parts of the system are already implemented and **must NOT be modified**:
|
||||
The following components are fully implemented and must not be changed:
|
||||
|
||||
#### ✅ Fully implemented:
|
||||
#### ✅ Infrastructure Layer
|
||||
|
||||
* Transaction stream parsing
|
||||
* Transaction generation / loading
|
||||
* ExecutorService (thread pool) setup
|
||||
* Worker thread management
|
||||
* System startup and execution flow
|
||||
* Live monitoring / balance visualization
|
||||
* Transaction generation and models
|
||||
* TransactionProcessor (dispatch layer)
|
||||
* BankingSystem (task submission layer)
|
||||
* ExecutorService configuration
|
||||
* Worker thread execution model
|
||||
* DemoApplication (system runner)
|
||||
* Live monitoring (debug tool)
|
||||
* JUnit test suite
|
||||
|
||||
---
|
||||
|
||||
### ❗ Your Responsibility
|
||||
### ❗ Your Responsibility (IMPORTANT)
|
||||
|
||||
You are ONLY responsible for implementing thread-safe logic inside:
|
||||
|
||||
#### 📄 `BankAccount.java`
|
||||
|
||||
You must implement the following methods:
|
||||
You must implement:
|
||||
|
||||
```java
|
||||
deposit(int amount);
|
||||
withdraw(int amount);
|
||||
transfer(BankAccount target, int amount);
|
||||
deposit(long amount);
|
||||
withdraw(long amount);
|
||||
transfer(BankAccount target, long amount);
|
||||
getBalance();
|
||||
```
|
||||
|
||||
Additionally, you may introduce internal synchronization design choices such as:
|
||||
|
||||
* Locks
|
||||
* ReadWriteLock
|
||||
* Atomic variables
|
||||
* Custom ordering strategies
|
||||
|
||||
---
|
||||
|
||||
### 🏗 System Architecture
|
||||
@@ -127,52 +140,57 @@ getBalance();
|
||||
Transaction Stream
|
||||
│
|
||||
▼
|
||||
ExecutorService Pool
|
||||
TransactionProcessor
|
||||
│
|
||||
┌──────────────────┼──────────────────┐
|
||||
▼
|
||||
BankingSystem (task submission via ExecutorService)
|
||||
│
|
||||
┌──────────────┼──────────────┐
|
||||
▼ ▼ ▼
|
||||
Worker A Worker B Worker C
|
||||
│ │ │
|
||||
└──────────────────┼──────────────────┘
|
||||
└──────────────┼──────────────┘
|
||||
▼
|
||||
Shared Bank Accounts
|
||||
```
|
||||
|
||||
Multiple worker threads may access the same accounts concurrently.
|
||||
Multiple worker threads may operate on the same account simultaneously.
|
||||
|
||||
Execution order is **non-deterministic**, and correctness must be guaranteed regardless of scheduling.
|
||||
Execution order is **non-deterministic**, and correctness must hold for all possible schedules.
|
||||
|
||||
---
|
||||
|
||||
### 🧠 Core Requirement
|
||||
### 🧠 Core Design Requirement
|
||||
|
||||
Your implementation must ensure:
|
||||
Your solution must guarantee:
|
||||
|
||||
* Shared state consistency
|
||||
* Thread safety
|
||||
* No race conditions
|
||||
* No lost updates
|
||||
* Correct final balances regardless of thread execution order
|
||||
* Atomic multi-step operations
|
||||
* Deadlock-free execution under all conditions
|
||||
|
||||
---
|
||||
|
||||
## 🛠 Implementation Requirements
|
||||
## 🛠 Implementation Phases
|
||||
|
||||
---
|
||||
|
||||
### 🟢 Phase 1 — Thread-Safe Account Operations
|
||||
### 🟢 Phase 1 — Thread-Safe Account State
|
||||
|
||||
Implement safe concurrent access for:
|
||||
Implement safe access and mutation for account balance:
|
||||
|
||||
* deposit
|
||||
* withdraw
|
||||
* getBalance
|
||||
#### Methods:
|
||||
|
||||
* `getBalance()`
|
||||
* `deposit()`
|
||||
* `withdraw()`
|
||||
|
||||
#### Requirements:
|
||||
|
||||
* No lost updates
|
||||
* No corrupted balances
|
||||
* Multiple threads may safely access different accounts concurrently
|
||||
* `getBalance()` must always return a valid state
|
||||
* No race conditions
|
||||
* Reads must never observe invalid intermediate state
|
||||
* Multiple accounts must remain independently concurrent
|
||||
* Negative balances are allowed unless explicitly handled by your implementation.
|
||||
|
||||
---
|
||||
|
||||
@@ -181,49 +199,40 @@ Implement safe concurrent access for:
|
||||
Implement:
|
||||
|
||||
```java
|
||||
transfer(BankAccount target, int amount);
|
||||
transfer(BankAccount target, long amount);
|
||||
```
|
||||
|
||||
#### Requirements:
|
||||
|
||||
* Transfer must be **atomic**
|
||||
* Money must never be created or lost
|
||||
* Partial updates are NOT allowed
|
||||
* Concurrent transfers must not corrupt balances
|
||||
* Transfer must be **fully atomic**
|
||||
* No partial updates allowed
|
||||
* Money must never be lost or created
|
||||
* Consistency must hold under concurrent transfers
|
||||
|
||||
Example of invalid behavior:
|
||||
#### Important:
|
||||
|
||||
```
|
||||
A → B transfer starts
|
||||
A is debited
|
||||
Crash / thread switch happens
|
||||
B is never credited ❌
|
||||
```
|
||||
A transfer involves **two shared resources (accounts)**, which introduces synchronization complexity beyond simple locking.
|
||||
|
||||
---
|
||||
|
||||
### 🔴 Phase 3 — Deadlock Prevention
|
||||
### 🔴 Phase 3 — Deadlock-Free Design
|
||||
|
||||
Transfers involve TWO accounts, which introduces risk of deadlock.
|
||||
|
||||
Example:
|
||||
Concurrent transfers may create cyclic locking scenarios:
|
||||
|
||||
```
|
||||
Thread 1: A → B
|
||||
Thread 2: B → A
|
||||
```
|
||||
|
||||
If locks are acquired incorrectly, the system may freeze.
|
||||
|
||||
#### Requirements:
|
||||
|
||||
* System must be completely deadlock-free
|
||||
* Must pass stress tests with high concurrency
|
||||
* Must work under arbitrary transaction ordering
|
||||
* Must pass high-concurrency stress tests
|
||||
* Must remain correct under arbitrary execution ordering
|
||||
|
||||
---
|
||||
|
||||
### ⚙ Allowed Java Concurrency Tools
|
||||
### ⚙ Allowed Concurrency Tools
|
||||
|
||||
You may use:
|
||||
|
||||
@@ -236,35 +245,38 @@ You may use:
|
||||
|
||||
---
|
||||
|
||||
### ❌ Not Allowed
|
||||
### ❌ Restrictions
|
||||
|
||||
* Busy waiting (e.g., `while(true)`)
|
||||
* Modifying test files
|
||||
* Modifying method signatures
|
||||
* Creating additional worker threads
|
||||
* Changing system architecture outside `BankAccount`
|
||||
You are NOT allowed to:
|
||||
|
||||
* Use busy waiting (e.g., `while(true)`)
|
||||
* Modify test files
|
||||
* Modify method signatures
|
||||
* Change system architecture outside `BankAccount`
|
||||
* Create additional worker threads
|
||||
* Modify transaction processing pipeline
|
||||
|
||||
---
|
||||
|
||||
### 📊 Live Monitoring (Debug Tool)
|
||||
### 📊 Live Monitoring (Debug Support)
|
||||
|
||||
The system includes a live balance visualization tool.
|
||||
A monitoring system is included to display real-time account balances.
|
||||
|
||||
It shows:
|
||||
It helps you:
|
||||
|
||||
* Real-time account balances
|
||||
* Effects of concurrent transactions
|
||||
* Potential race conditions
|
||||
* Observe race conditions
|
||||
* Debug concurrency issues
|
||||
* Validate correctness under load
|
||||
|
||||
⚠ This tool is NOT part of grading.
|
||||
⚠ This component is NOT part of grading and may produce non-deterministic output.
|
||||
|
||||
---
|
||||
|
||||
### 🧪 Testing
|
||||
|
||||
A full JUnit test suite is provided.
|
||||
A full JUnit test suite validates your solution.
|
||||
|
||||
Your solution will be evaluated on:
|
||||
Your implementation will be evaluated on:
|
||||
|
||||
---
|
||||
|
||||
@@ -280,39 +292,38 @@ Your solution will be evaluated on:
|
||||
|
||||
* No deadlocks under stress tests
|
||||
* Stable execution under high concurrency
|
||||
* Correct behavior under random transaction ordering
|
||||
* Correct behavior under unpredictable scheduling
|
||||
|
||||
---
|
||||
|
||||
#### ⚡ Performance
|
||||
|
||||
* Independent accounts should not block each other unnecessarily
|
||||
* Avoid global locking unless absolutely necessary
|
||||
* System should scale with number of threads
|
||||
* Independent accounts should not block each other
|
||||
* Avoid unnecessary global locking
|
||||
* Maintain scalable concurrency
|
||||
|
||||
---
|
||||
|
||||
### 🌟 Bonus Challenge (Optional)
|
||||
|
||||
Implement conditional waiting for insufficient funds:
|
||||
Implement **conditional waiting for insufficient funds**:
|
||||
|
||||
* Withdraw should wait if balance is insufficient
|
||||
* Transfer should wait until funds are available
|
||||
* `withdraw()` waits until balance is sufficient
|
||||
* `transfer()` waits until source has enough funds
|
||||
|
||||
#### Requirements:
|
||||
|
||||
* No busy waiting
|
||||
* No CPU spinning
|
||||
* No starvation
|
||||
* Must remain thread-safe
|
||||
|
||||
⚠ **Note on Bonus:** The provided JUnit test suite assumes the base behavior (allowing balances to proceed without waiting). Implementing the bonus challenge might cause some base stress tests to time out due to threads waiting indefinitely for funds. It is recommended to verify the bonus logic using your own custom test scenarios.
|
||||
|
||||
---
|
||||
|
||||
### 💡 Hint
|
||||
|
||||
Start with correctness first.
|
||||
|
||||
Then optimize concurrency.
|
||||
|
||||
A simple correct solution is always better than a fast incorrect one.
|
||||
### 💡 Final Hint
|
||||
|
||||
> A correct solution is always more valuable than an optimized incorrect one.
|
||||
|
||||
Start simple, ensure correctness, then improve concurrency and performance.
|
||||
|
||||
Reference in New Issue
Block a user