Skip to content

Commit 80b80de

Browse files
Kaushal1011Kaushal1011
committed
added some docs 🤖
1 parent 33292bf commit 80b80de

File tree

2 files changed

+173
-1
lines changed

2 files changed

+173
-1
lines changed

‎README.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,14 @@
22

33
This project is a simulation of various distributed computing algorithms implemented in Scala using the Akka framework.
44

5+
## Simulation Architecture
6+
7+
8+
9+
10+
## Testing Architecture
11+
12+
513
## Prerequisites
614

715
Before you begin, ensure you have met the following requirements:
@@ -42,7 +50,7 @@ sbt clean compile test
4250
- ***Weight throwing for termination detection (Slight Variation)***
4351
- Moves to next simulation plan
4452

45-
### Mutex
53+
### [Mutex](./docs/MutexAlgorithms.md)
4654

4755
#### Message Passing based Algorithms
4856

‎docs/MutexAlgorithms.md

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Mutex Algorithms Documentation
2+
3+
This document provides a detailed explanation of the mutex algorithms implemented in this project.
4+
5+
## Overview
6+
7+
The mutex module in this project implements various mutual exclusion algorithms. These algorithms are used to prevent concurrent processes from accessing shared resources simultaneously, thus avoiding potential conflicts or inconsistencies.
8+
All the algorithms implemented from the mutual exclusion chapter of the textbook ["Distributed Algorithms, Second Edition An Intuitive Approach, W Fokik"](https://mitpress.mit.edu/9780262037662/distributed-algorithms/) which provides an intuitive approach to learning them by summarising and elaborating on individual paper.
9+
10+
## Algorithms Implemented
11+
12+
The following algorithms are implemented in this project:
13+
1. Ricart Agarwal
14+
2. Ricart Agarwal Carvalho Extension
15+
3. Raymonds Algorithm
16+
4. Agrawal El Abbadi
17+
5. Peterson's Algorithm (Tournament for N Processes)
18+
6. Peterson's Algorithm (Two Process)
19+
7. Bakery Algorithm
20+
8. Test and Set Lock Algorithm
21+
9. Test and Test and Set Lock Algorithm
22+
23+
## Algorithm Details
24+
25+
### [Ricart Agarwal](../src/main/scala/com/distcomp/mutex/RicartaAgarwal.scala)
26+
27+
Request all processes in the system for permission to enter the critical section. The process can enter the critical section only when it receives permission from all other processes. The process sends a request message to all other processes and waits for a reply from all of them. The process can enter the critical section only when it receives a reply from all other processes.
28+
29+
#### Implementation Details
30+
31+
32+
1. **Timestamp-based Ordering:** Each actor sends a `RequestCS` with its timestamp to all other actors and must receive a `ReplyCS` from every actor before entering the critical section, ensuring requests are ordered by timestamp and node ID.
33+
34+
2. **State Management:** Uses mutable state (`pendingReplies`) to track which actors have not yet replied to the critical section request, updating this state upon receiving each `ReplyCS`.
35+
36+
3. **Message Handling:** Actors handle different types of messages (`RequestCS`, `ReplyCS`, `EnterCriticalSection`, `ExitCriticalSection`, and `ReleaseCS`) to manage entry, operation within, and exit from the critical section, adhering to the mutual exclusion principle.
37+
38+
4. **Concurrency Control:** Prioritizes critical section access based on timestamp and node ID comparisons. This is implemented in the condition checking within the `RequestCS` message handling, deciding whether to immediately reply or defer the reply until after exiting the critical section.
39+
40+
5. **State Transitions and Timestamp Updates:** Implements state transitions upon entering and exiting the critical section and updates the logical clock upon receiving messages with higher timestamps to maintain consistency.
41+
42+
43+
### [Ricart Agarwal Carvalho Extension](../src/main/scala/com/distcomp/mutex/RicartaAgarwalCarvalhoRoucairol.scala)
44+
45+
An extension of the Ricart Agarwal algorithm that allows a process to enter the critical section without waiting for permission from all other processes. The process can enter the critical section when it receives permission from processes which have requested critical section after it last exited critical section.
46+
47+
#### Implementation Details
48+
49+
1. **Roucairol and Carvalho Optimization:** Utilizes a `lastGranted` set to remember which nodes last granted access to the critical section, allowing the node to request access only from these nodes in subsequent attempts, significantly reducing the number of messages needed.
50+
51+
2. **Selective Request Broadcasting:** When requesting critical section access, the node either broadcasts to all nodes (if not previously in the critical section) or only to nodes in `lastGranted` (if re-entering), optimizing network use.
52+
53+
3. **Dynamic Set Management:** Actively manages the `lastGranted` set by adding nodes that grant access and clearing it upon exiting the critical section, ensuring that only relevant nodes are contacted in future requests.
54+
55+
4. **Critical Section Re-entry:** Employs conditional logic to check if re-entry is possible without waiting for new permissions if no changes in `lastGranted` have occurred, speeding up the process of re-entering the critical section.
56+
57+
58+
### Raymonds Algorithm
59+
60+
Raymond's algorithm forms a logical tree structure among processes to control access to the critical section. Each process in the tree has a token, and only the holder of the token can enter the critical section. A process needing to enter the critical section must request the token from its parent in the tree, and this request may be propagated up the tree until it reaches the token holder. The token is then passed down the tree to the requesting process.
61+
62+
#### Implementation Details
63+
64+
1. **Token Management:** Uses a token-based approach for critical section entry. Nodes request and pass a token along a logical tree, where possession of the token grants access to the critical section.
65+
66+
2. **Queue System:** Implements a queue to manage requests for the token. Nodes add themselves to the queue when they need the token, and the token is passed to the first node in the queue when available.
67+
68+
3. **Critical Section Entry and Exit:** Nodes enter the critical section when they have the token and exit by passing the token to the next node in the queue, if any.
69+
70+
4. **Dynamic Parent-Child Reassignment:** On exiting the critical section, a node can reassign the 'parent' role to the next node in the queue, reflecting changes in the tree's structure necessary for efficient token passing.
71+
72+
### Agrawal El Abbadi
73+
74+
This algorithm uses a timestamping mechanism to decide the order of critical section access among competing processes. Each process maintains a local clock. When a process desires to enter the critical section, it broadcasts its timestamp to all other processes and waits for their acknowledgment. The process can enter the critical section when it has received all acknowledgments and has the smallest timestamp among all pending requests.
75+
76+
#### Implementation Details
77+
78+
1. **Heartbeat Mechanism:** Incorporates a heartbeat system to monitor node availability, using scheduled heartbeats sent to a failure detector. This ensures that the system can adapt to node failures by dynamically updating permissions and quorum configurations.
79+
80+
2. **Dynamic Quorum and Permission Management:** Manages a quorum queue to control access to the critical section, only granting permission to the head of the queue and dynamically adjusting the queue based on node failures and permissions.
81+
82+
3. **Critical Section Protocols:** Implements protocols for entering and exiting the critical section, including granting and revoking permissions based on quorum status, and signaling completion to a simulator.
83+
84+
4. **Failure Handling:** Reacts to node failures by adjusting the permission given state and recalibrating the quorum queue, ensuring the system remains operational and consistent even in the presence of failures.
85+
86+
### Peterson's Algorithm (Tournament for N Processes)
87+
88+
This version of Peterson's algorithm extends the basic two-process algorithm to N processes organized in a binary tree. Each node of the tree represents a competition between two processes, and the winner at each node moves up to compete at the next level. This continues until one process emerges as the winner at the root of the tree, gaining access to the critical section.
89+
90+
#### Implementation Details
91+
92+
1. **Tournament Tree Construction:** Builds a binary tournament tree for managing mutual exclusion among multiple processes. Each process is assigned an internal node ID and a bit position, creating a structured pathway to contest for entering the critical section.
93+
94+
2. **Flag and Turn Setting:** Processes communicate with a shared memory actor to set flags and turns that dictate the ability to proceed or wait in the contest for the critical section. These flags are set recursively up the tournament tree until the root is reached or the contest is resolved.
95+
96+
3. **Critical Section Entry:** A process enters the critical section only after successfully navigating the tournament tree, ensuring that no other process is contesting its entry at a higher priority level. Entry is managed through message passing that checks and sets conditions at each level of the tree.
97+
98+
4. **Message Queue Management:** Utilizes a message queue to store actions that need to be executed after exiting the critical section, ensuring that flags are reset correctly and the state is consistent for future requests.
99+
100+
5. **Recursive Contest Resolution:** Implements recursive checks and updates up the tournament tree. If a process cannot proceed, it waits and retries, effectively spinning on a condition. Once able to proceed, it moves up the tree until it can either enter the critical section or needs to retry at a higher level.
101+
102+
### Peterson's Algorithm (Two Process)
103+
104+
This simpler variant of Peterson's algorithm is designed for two competing processes. Each process signals its intent to enter the critical section and sets a preference variable indicating the other process's turn to enter. A process can enter the critical section when it sees either the other process is not interested or it is its turn according to the preference variable.
105+
106+
#### Implementation Details
107+
108+
1. **Initialization and Logging:** Starts by logging the initialization of the Peterson two-process algorithm, ensuring the node is set up correctly for mutual exclusion operations.
109+
110+
2. **Shared Memory Interaction:** Processes interact with a shared memory actor to set and check flags and turns, crucial for determining the right to enter the critical section based on the Peterson algorithm rules.
111+
112+
3. **Critical Section Entry Logic:** Implements a check-and-wait mechanism where the process sets its flag, sets the turn to the other process, and repeatedly checks both the flag and turn conditions to decide when it can safely enter the critical section.
113+
114+
4. **Critical Section Management:** Once conditions are met, the process enters the critical section, performs operations, and then exits. It resets its flag in shared memory to allow the other process to enter the critical section.
115+
116+
5. **Exit and Cleanup:** Signals completion of its critical section execution to a simulator actor and ensures the flag is reset in shared memory, maintaining system consistency for subsequent operations.
117+
118+
### Bakery Algorithm
119+
120+
The Bakery algorithm is based on the analogy of taking a number at a bakery. Each process takes a ticket number when it wants to enter the critical section. Processes enter the critical section in the order of their ticket numbers, ensuring fairness. A process with a lower ticket number will always enter the critical section before those with higher numbers.
121+
122+
#### Implementation Details
123+
124+
1. **Algorithm Initialization:** Logs the initiation of the Bakery algorithm, which simulates the classic bakery ticket system for managing access to a critical section among multiple processes.
125+
126+
2. **Flag and Number Setting:** Processes interact with a shared memory actor to set 'choosing' flags when attempting to enter the critical section, then calculate and set their 'number' based on the highest current number observed plus one.
127+
128+
3. **Critical Section Entry Check:** Each process repeatedly checks two conditions before entering the critical section: that no other process is in the 'choosing' state, and that no process has a smaller 'number' (or if the same, has a lower ID).
129+
130+
4. **Entry and Exit from Critical Section:** Once conditions are met, the process enters the critical section, performs its operations, and upon exiting, resets its number to zero and notifies the simulator of the completion.
131+
132+
5. **Handling Delays and Shared Memory Checks:** Implements random delays to simulate network latency and ensures operations on shared memory are synchronized and consistent across all participating processes.
133+
134+
### Test and Set Lock Algorithm
135+
136+
This algorithm uses a single shared boolean variable. A process attempting to enter the critical section uses an atomic "test and set" operation on the variable. If the variable is false (unlocked), it is set to true (locked), and the process enters the critical section. If the variable is true, the process must wait and repeatedly test until it becomes false.
137+
138+
#### Implementation Details
139+
140+
1. **Initialization and Setup:** Logs the start of the Test and Set mutex mechanism, preparing the node for operation within the mutual exclusion environment.
141+
142+
2. **Lock Acquisition Attempt:** Each process sends a `SetLockRequest` to the shared memory actor to attempt acquiring the lock. If unsuccessful (i.e., the lock is already held), it periodically retries until the lock becomes available.
143+
144+
3. **Entering and Exiting Critical Section:** Once the lock is successfully acquired, the process enters the critical section, performs its task, and upon completion, signals an `ExitCriticalSection` to proceed with lock release.
145+
146+
4. **Lock Release and Cleanup:** After exiting the critical section, the process sends an `UnlockRequest` to the shared memory actor to release the lock and notifies the simulator of the completion of its critical section execution.
147+
148+
### Test and Test and Set Lock Algorithm
149+
150+
An optimization of the Test and Set Lock Algorithm, this method reduces the bus traffic in multiprocessor systems. A process first tests the lock status without altering it. If the lock is free, the process then uses the "test and set" operation to attempt to acquire the lock. This reduces the amount of expensive atomic operations required, potentially lowering system overhead.
151+
152+
#### Implementation Details
153+
154+
1. **Initialization and Setup:** Logs the startup process for the Test and Test and Set mutex mechanism, preparing the node for operation within the mutual exclusion environment.
155+
156+
2. **Initial Lock Check:** Each process first sends a `ReadLockRequest` to shared memory to check the lock status. This step avoids unnecessary locking attempts if the lock is already held by another process.
157+
158+
3. **Lock Attempt and Optimization:** If the initial lock check returns false (lock is free), the process then sends a `SetLockRequest`. This double-checking minimizes the lock's contention and improves performance by reducing the number of lock acquisition attempts.
159+
160+
4. **Critical Section Entry:** Upon successful lock acquisition (confirmed by a `SetLockResponse` with false), the process enters the critical section, performs necessary operations, and then signals `ExitCriticalSection`.
161+
162+
5. **Lock Release and Algorithm Completion:** After completing the critical section operations, the process releases the lock by sending an `UnlockRequest` to shared memory and notifies the simulator of the operation's completion.
163+
164+
6. **Robust Error Handling:** Ensures continuous operation despite potential null references to shared memory, crucial for maintaining stability in distributed systems.

0 commit comments

Comments
 (0)