WIP

Author: ashtanko

README.md

@@ -22,23 +22,23 @@
 
 ### Metrics
 ```text
-15001 number of properties
-10391 number of functions
-8857 number of classes
-230 number of packages
-3488 number of kt files
+15007 number of properties
+10398 number of functions
+8859 number of classes
+231 number of packages
+3489 number of kt files
 ```
 
 
 ### Complexity Report
 ```text
-259554 lines of code (loc)
-158990 source lines of code (sloc)
-116006 logical lines of code (lloc)
-72493 comment lines of code (cloc)
-24708 cyclomatic complexity (mcc)
-20232 cognitive complexity
+259717 lines of code (loc)
+159153 source lines of code (sloc)
+116114 logical lines of code (lloc)
+72470 comment lines of code (cloc)
+24752 cyclomatic complexity (mcc)
+20233 cognitive complexity
 0 number of total code smells
 45 comment source ratio
-212 mcc per 1,000 lloc
+213 mcc per 1,000 lloc
 ```

gradle/libs.versions.toml

@@ -12,7 +12,7 @@ kapt = "2.1.0"              # https://kotlinlang.org/docs/kapt.html
 slf4j = "2.0.17"            # https://www.slf4j.org TODO remove
 rxjava = "3.1.10"           # https://github.com/ReactiveX/RxJava
 rxkotlin = "3.0.1"          # https://github.com/ReactiveX/RxKotlin
-lincheck = "2.36"           # https://github.com/JetBrains/lincheck
+lincheck = "2.29"           # https://github.com/JetBrains/lincheck
 serialization = "1.8.1"     # https://github.com/Kotlin/kotlinx.serialization
 retrofit = "2.11.0"         # https://github.com/square/retrofit
 okhttp = "5.0.0-alpha.14"   # https://square.github.io/okhttp/changelogs/changelog

src/main/kotlin/dev/shtanko/algorithms/leetcode/TOP_150.md

@@ -0,0 +1 @@
+- Merge Sorted Array

src/main/kotlin/dev/shtanko/concurrency/AtomicReferenceArrayExample.kt

@@ -24,23 +24,19 @@ import java.util.concurrent.atomic.AtomicReferenceArray
 object AtomicReferenceArrayExample {
     @JvmStatic
     fun main(args: Array<String>) {
-        // Initialize an AtomicReferenceArray with 5 elements
         val atomicArray = AtomicReferenceArray<String>(5)
 
-        // Set values in the array
         atomicArray.set(0, "A")
         atomicArray.set(1, "B")
         atomicArray.set(2, "C")
         atomicArray.set(3, "D")
         atomicArray.set(4, "E")
 
-        // Get and print values from the array
         println("Initial values:")
         for (i in 0 until atomicArray.length()) {
             println("Index $i: ${atomicArray.get(i)}")
         }
 
-        // Update a value using compareAndSet
         val indexToUpdate = 2
         val oldValue = "C"
         val newValue = "Z"

src/main/kotlin/dev/shtanko/concurrency/collections/ARRAY_BLOCKING_QUEUE.md

@@ -0,0 +1,86 @@
+## 🧠 `ArrayBlockingQueue`
+
+`ArrayBlockingQueue` is a bounded, **blocking queue** implementation in Java that uses an array to store the elements. 
+It is a **thread-safe** queue designed for situations where a fixed-size queue is needed, and elements are added or removed in a **first-in-first-out (FIFO)** order.
+
+---
+
+### 🔍 Key Features
+
+- **Thread-safe**: Provides safe concurrent access for multiple threads.
+- **Blocking behavior**: It **blocks** threads when the queue is full or empty (for `put()` and `take()` operations).
+- **Bounded capacity**: The queue has a fixed capacity, preventing unbounded growth.
+- **FIFO order**: Elements are dequeued in a first-in-first-out order.
+
+---
+
+### ✅ When to Use
+
+- ✅ You need a **bounded queue** with a **fixed capacity**.
+- ✅ Threads should block when the queue is full or empty (e.g., producer-consumer pattern).
+- ✅ You want to ensure that the queue doesn’t grow indefinitely, thereby controlling memory usage.
+
+---
+
+### ❌ When Not to Use
+
+- ❌ If you need a **non-blocking** queue or one that grows dynamically (consider `ConcurrentLinkedQueue` or `LinkedBlockingQueue`).
+- ❌ When you need **unbounded queue capacity** or if memory control isn’t a priority.
+
+---
+
+### 📌 Kotlin Example
+
+```kotlin
+import java.util.concurrent.ArrayBlockingQueue
+
+fun main() {
+    // Creating a bounded queue with a capacity of 3
+    val queue = ArrayBlockingQueue<String>(3)
+
+    // Producer thread: Adds elements to the queue
+    val producer = Thread {
+        try {
+            queue.put("Task 1")  // Will block if the queue is full
+            queue.put("Task 2")
+            queue.put("Task 3")
+            println("Producer finished adding tasks.")
+        } catch (e: InterruptedException) {
+            e.printStackTrace()
+        }
+    }
+
+    // Consumer thread: Removes elements from the queue
+    val consumer = Thread {
+        try {
+            println("Consumer started")
+            println("Taken: ${queue.take()}")  // Will block if the queue is empty
+            println("Taken: ${queue.take()}")
+            println("Taken: ${queue.take()}")
+            println("Consumer finished processing tasks.")
+        } catch (e: InterruptedException) {
+            e.printStackTrace()
+        }
+    }
+
+    // Start producer and consumer threads
+    producer.start()
+    consumer.start()
+
+    // Wait for threads to finish
+    producer.join()
+    consumer.join()
+}
+```
+
+---
+
+### 💡 Summary Table
+
+| Feature               | `ArrayBlockingQueue`        |
+|-----------------------|-----------------------------|
+| Thread-safe           | ✅ Yes                      |
+| Blocking operations   | ✅ Yes (blocks on full/empty) |
+| Capacity              | ✅ Bounded (fixed size)     |
+| FIFO order            | ✅ Yes                      |
+| Best use case         | ✅ Producer-consumer pattern, controlling memory usage  |

src/main/kotlin/dev/shtanko/concurrency/collections/CONCURRENT_HASH_MAP.md

@@ -0,0 +1,75 @@
+## 🧠 `ConcurrentHashMap` in Java and Kotlin
+
+`ConcurrentHashMap` is a thread-safe and highly performant implementation of `Map` designed for concurrent access without needing to synchronize the entire map.
+
+---
+
+### 🔍 Key Features
+
+- Allows **concurrent reads and writes** by segmenting the map internally.
+- **Does not allow `null` keys or values**.
+- **No need to synchronize** explicitly for most operations.
+- Iterators are **weakly consistent** — they reflect some (not necessarily all) changes made during iteration and do **not** throw `ConcurrentModificationException`.
+
+---
+
+### ✅ When to Use
+
+- ✅ You need a **high-performance thread-safe map**.
+- ✅ Multiple threads **frequently read and write** concurrently.
+- ✅ You're building multi-threaded services, caches, or registries.
+
+---
+
+### ❌ When Not to Use
+
+- ❌ You need to store `null` values (not allowed).
+- ❌ In single-threaded scenarios — prefer regular `HashMap`.
+
+---
+
+### 📌 Kotlin Example
+
+```kotlin
+import java.util.concurrent.ConcurrentHashMap
+
+fun main() {
+    val map = ConcurrentHashMap<String, String>()
+
+    map["name"] = "Alice"
+    map["city"] = "Wonderland"
+
+    // Accessing elements
+    println("Name: ${map["name"]}")
+    println("City: ${map["city"]}")
+
+    // Iterating over keys
+    for (key in map.keys) {
+        println("$key => ${map[key]}")
+    }
+
+    // Safe concurrent access (example using multiple threads)
+    val threads = List(10) { i ->
+        Thread {
+            map["thread-$i"] = "value-$i"
+        }
+    }
+
+    threads.forEach { it.start() }
+    threads.forEach { it.join() }
+
+    println("Map size after concurrency: ${map.size}")
+}
+```
+
+---
+
+### 💡 Summary Table
+
+| Feature              | `ConcurrentHashMap`        |
+|----------------------|-----------------------------|
+| Thread-safe          | ✅ Yes                      |
+| Null keys/values     | ❌ Not allowed              |
+| Performance          | ✅ High under concurrency   |
+| Iterators            | ✅ Weakly consistent        |
+| Best use case        | ✅ Multi-threaded apps      |

src/main/kotlin/dev/shtanko/concurrency/collections/CONCURRENT_LINKED_DEQUE.md

@@ -0,0 +1,85 @@
+## 🧠 `ConcurrentLinkedDeque`
+
+`ConcurrentLinkedDeque` is a thread-safe, non-blocking **double-ended queue** (deque) that allows elements to be added or removed from both ends of the queue concurrently. 
+It provides a **lock-free** implementation for high-performance operations in concurrent environments.
+
+---
+
+### 🔍 Key Features
+
+- **Thread-safe**: Allows multiple threads to access and modify the deque concurrently without requiring synchronization.
+- **Non-blocking**: Provides lock-free, non-blocking operations for adding and removing elements from both ends of the deque.
+- **FIFO Order**: Elements are dequeued in a **first-in-first-out** order, but since it’s a deque, elements can also be added and removed from both ends.
+- **Unbounded**: It grows as needed (limited only by available memory).
+
+---
+
+### ✅ When to Use
+
+- ✅ You need a **high-performance thread-safe deque** that allows **adding/removing elements** from both ends.
+- ✅ You require **non-blocking behavior** for both ends of the deque in a **multi-threaded environment**.
+- ✅ You have scenarios like **task scheduling**, **buffering**, or **job queues** that require fast access from both ends.
+
+---
+
+### ❌ When Not to Use
+
+- ❌ If you need to block threads while waiting for elements (consider using `BlockingDeque` in that case).
+- ❌ If you only need a simple queue or stack, consider using `ConcurrentLinkedQueue` or `Stack` instead.
+
+---
+
+### 📌 Kotlin Example
+
+```kotlin
+import java.util.concurrent.ConcurrentLinkedDeque
+
+fun main() {
+    val deque = ConcurrentLinkedDeque<String>()
+
+    // Adding elements to both ends of the deque
+    deque.offerFirst("Task 1")  // Adds at the front
+    deque.offerLast("Task 2")   // Adds at the back
+    deque.offerFirst("Task 3")  // Adds at the front
+    deque.offerLast("Task 4")   // Adds at the back
+
+    // Polling elements from both ends
+    println("Polled from front: ${deque.pollFirst()}")  // Output: Task 3
+    println("Polled from back: ${deque.pollLast()}")   // Output: Task 4
+
+    // Peek at the front and back without removing
+    println("Peek front: ${deque.peekFirst()}")  // Output: Task 1
+    println("Peek back: ${deque.peekLast()}")    // Output: Task 2
+
+    // Checking if the deque is empty
+    println("Is deque empty? ${deque.isEmpty()}")  // Output: false
+
+    // Safe concurrent access example
+    val threads = List(5) { i ->
+        Thread {
+            deque.offerLast("Task from thread $i")
+        }
+    }
+
+    threads.forEach { it.start() }
+    threads.forEach { it.join() }
+
+    // Polling all tasks after concurrent additions
+    while (deque.isNotEmpty()) {
+        println("Polled: ${deque.pollFirst()}")
+    }
+}
+```
+
+---
+
+### 💡 Summary Table
+
+| Feature               | `ConcurrentLinkedDeque`     |
+|-----------------------|-----------------------------|
+| Thread-safe           | ✅ Yes                      |
+| Non-blocking          | ✅ Yes (lock-free)          |
+| FIFO order            | ✅ Yes                      |
+| Allows adding/removing from both ends | ✅ Yes          |
+| Capacity              | ❌ Unbounded (limited by memory) |
+| Best use case         | ✅ Task scheduling, job queues, buffers  |