added identity operations

Author: alelom

.vscode/settings.json

@@ -68,5 +68,6 @@
         "**/.*": {
         "when": "$(basename).isDirectory"
         }
-    }
+    },
+    "python.languageServer": "None"
 }

README.md

@@ -72,17 +72,69 @@ print(list(bag))  # [1, 2, 3, 4]
 
 ### ConcurrentDictionary
 
-A thread-safe dictionary. It has a few notable methods:
-
-- `assign_atomic()`
-- `get_locked()`
-- `update_atomic()`
+A thread-safe dictionary. It has several atomic methods for safe concurrent operations:
+
+- `assign_atomic()` - Atomically assign a value to a key
+- `update_atomic()` - Atomically update a value using a function
+- `remove_atomic()` - Atomically remove a key and return its value
+- `put_if_absent()` - Atomically put a value only if the key doesn't exist
+- `replace_if_present()` - Atomically replace a value only if the key exists
+- `replace_if_equal()` - Atomically replace a value only if it equals the expected value
+- `remove_if_exists()` - Atomically remove a key if it exists
+- `get_and_remove()` - Atomically get and remove a value
+- `get_locked()` - Context manager for safe read-modify-write operations
 
 #### ConcurrentDictionary's `assign_atomic()`
 
 Assigns a dictionary value under a key in a thread-safe way.
 While `dict["somekey"] = value` is allowed, it's best to use `assign_atomic()` for clarity of intent. Using normal assignment will work but raise a UserWarning.
 
+#### ConcurrentDictionary's `remove_atomic()`
+
+Atomically removes a key from the dictionary and returns its value, or None if the key doesn't exist.
+
+```python
+from concurrent_collections import ConcurrentDictionary
+
+d = ConcurrentDictionary({'x': 1, 'y': 2})
+value = d.remove_atomic('x')  # Returns 1, removes 'x'
+```
+
+#### ConcurrentDictionary's `put_if_absent()`
+
+Atomically puts a value for a key only if the key is not already present. Returns the existing value if the key exists, None if the key was added.
+
+```python
+from concurrent_collections import ConcurrentDictionary
+
+d = ConcurrentDictionary({'x': 1})
+existing = d.put_if_absent('x', 2)  # Returns 1, no change
+existing = d.put_if_absent('y', 3)  # Returns None, adds 'y': 3
+```
+
+#### ConcurrentDictionary's `replace_if_present()`
+
+Atomically replaces the value for a key only if the key exists. Returns True if the key was replaced, False if the key doesn't exist.
+
+```python
+from concurrent_collections import ConcurrentDictionary
+
+d = ConcurrentDictionary({'x': 1})
+replaced = d.replace_if_present('x', 2)  # Returns True
+replaced = d.replace_if_present('y', 3)  # Returns False
+```
+
+#### ConcurrentDictionary's `replace_if_equal()`
+
+Atomically replaces the value for a key only if the current value equals the expected value. Returns True if the value was replaced, False otherwise.
+
+```python
+from concurrent_collections import ConcurrentDictionary
+
+d = ConcurrentDictionary({'x': 1})
+replaced = d.replace_if_equal('x', 1, 2)  # Returns True
+replaced = d.replace_if_equal('x', 1, 3)  # Returns False (current value is 2)
+```
 
 #### ConcurrentDictionary's `get_locked()`
 
@@ -126,6 +178,70 @@ Additionally, there are [other queue classes in the `multiprocessing` module](ht
 - `SimpleQueue` (again)
 
 
+## Equality and Identity Semantics
+
+### ConcurrentBag Equality
+
+`ConcurrentBag` compares as a **multiset** - order doesn't matter, but element frequency does:
+
+```python
+from concurrent_collections import ConcurrentBag
+
+# These are equal (same elements, same frequencies)
+bag1 = ConcurrentBag([1, 2, 2, 3])
+bag2 = ConcurrentBag([2, 1, 3, 2])
+assert bag1 == bag2  # True
+
+# These are not equal (different frequencies)
+bag3 = ConcurrentBag([1, 2, 3, 3])
+assert bag1 != bag3  # True
+```
+
+### ConcurrentQueue Equality
+
+`ConcurrentQueue` compares elements in order, taking snapshots for consistency during concurrent operations:
+
+```python
+from concurrent_collections import ConcurrentQueue
+
+# These are equal (same elements, same order)
+queue1 = ConcurrentQueue([1, 2, 3])
+queue2 = ConcurrentQueue([1, 2, 3])
+assert queue1 == queue2  # True
+
+# These are not equal (different order)
+queue3 = ConcurrentQueue([3, 2, 1])
+assert queue1 != queue3  # True
+```
+
+### ConcurrentDictionary Equality
+
+`ConcurrentDictionary` compares key-value pairs, order doesn't matter:
+
+```python
+from concurrent_collections import ConcurrentDictionary
+
+# These are equal (same key-value pairs)
+dict1 = ConcurrentDictionary({'a': 1, 'b': 2})
+dict2 = ConcurrentDictionary({'b': 2, 'a': 1})
+assert dict1 == dict2  # True
+
+# These are not equal (different values)
+dict3 = ConcurrentDictionary({'a': 1, 'b': 3})
+assert dict1 != dict3  # True
+```
+
+## Thread Safety Guarantees
+
+All collections provide the following guarantees:
+
+1. **Atomic Operations**: All individual operations (append, remove, get, set) are atomic
+2. **Consistent Snapshots**: Iteration and equality comparisons take consistent snapshots
+3. **No Race Conditions**: Multiple threads can safely access and modify the collections
+4. **Identity Consistency**: Hash values and equality comparisons are consistent within a single operation
+
+**Note**: While individual operations are thread-safe, compound operations (like checking length then conditionally modifying) should use the provided atomic methods or context managers to ensure consistency.
+
 ## License
 
 MIT License

concurrent_collections/concurrent_bag.py

@@ -1,5 +1,5 @@
 import threading
-from typing import Generic, Iterable, Iterator, List, Optional, TypeVar
+from typing import Generic, Iterable, Iterator, List, Optional, TypeVar, Any
 
 T = TypeVar('T')
 
@@ -54,4 +54,38 @@ def clear(self) -> None:
 
     def __repr__(self) -> str:
         with self._lock:
-            return f"ConcurrentBag({self._items!r})"
+            return f"ConcurrentBag({self._items!r})"
+
+    def __eq__(self, other: Any) -> bool:
+        """
+        Thread-safe equality comparison.
+        
+        Two ConcurrentBag instances are equal if they have the same elements with the same frequency
+        (multiset equality). Order does not matter for bag equality.
+        
+        Example:
+            ConcurrentBag([1, 2, 2, 3]) == ConcurrentBag([2, 1, 3, 2])  # True
+            ConcurrentBag([1, 2, 2, 3]) == ConcurrentBag([1, 2, 3, 3])  # False (different frequencies)
+        """
+        if not isinstance(other, ConcurrentBag):
+            return False
+        
+        with self._lock:
+            with other._lock:
+                # Compare as multisets by counting element frequencies
+                from collections import Counter
+                return Counter(self._items) == Counter(other._items)
+
+    def __hash__(self) -> int:
+        """
+        Thread-safe hash computation.
+        
+        The hash is computed based on the multiset content (element frequencies).
+        Note: The hash will change if the bag is modified.
+        """
+        with self._lock:
+            # Convert to frozenset of (element, count) pairs for consistent hashing
+            from collections import Counter
+            counter = Counter(self._items)
+            items = frozenset(counter.items())
+            return hash(items)

concurrent_collections/concurrent_deque.py

@@ -1,6 +1,6 @@
 import threading
 from collections import deque
-from typing import Generic, Iterable, Iterator, Optional, TypeVar
+from typing import Generic, Iterable, Iterator, Optional, TypeVar, Any
 
 T = TypeVar('T')
 
@@ -48,4 +48,37 @@ def extendleft(self, iterable: Iterable[T]) -> None:
 
     def __repr__(self) -> str:
         with self._lock:
-            return f"ConcurrentQueue({list(self._deque)})"
+            return f"ConcurrentQueue({list(self._deque)})"
+
+    def __eq__(self, other: Any) -> bool:
+        """
+        Thread-safe equality comparison.
+        
+        Two ConcurrentQueue instances are equal if they have the same elements in the same order.
+        For concurrent operations, this comparison takes a snapshot of both queues at the time
+        of comparison to ensure consistency.
+        
+        Note: Due to the concurrent nature of the queue, the order may change between
+        comparisons, but this method provides a consistent snapshot-based comparison.
+        """
+        if not isinstance(other, ConcurrentQueue):
+            return False
+        
+        with self._lock:
+            with other._lock:
+                # Take snapshots for consistent comparison
+                self_snapshot = list(self._deque)
+                other_snapshot = list(other._deque)
+                return self_snapshot == other_snapshot
+
+    def __hash__(self) -> int:
+        """
+        Thread-safe hash computation.
+        
+        The hash is computed based on the current state of the queue.
+        Note: The hash will change if the queue is modified.
+        """
+        with self._lock:
+            # Convert to tuple for consistent hashing
+            items = tuple(self._deque)
+            return hash(items)

concurrent_collections/concurrent_dict.py

@@ -112,7 +112,7 @@ def update_atomic(self, key: K, func: Callable[[V], V]) -> None:
         Example:
             d = ConcurrentDictionary({'x': 0})
             # Atomically increment the value for 'x'
-            d.modify_atomic('x', lambda v: v + 1)
+            d.update_atomic('x', lambda v: v + 1)
         """
         with self._lock:
             if key in self._dict:
@@ -123,6 +123,103 @@ def update_atomic(self, key: K, func: Callable[[V], V]) -> None:
                 # If the key does not exist, we can set it directly
                 self._dict[key] = func(None) # type: ignore
 
+    def remove_atomic(self, key: K) -> Optional[V]:
+        """
+        Atomically remove a key from the dictionary and return its value.
+        
+        This method ensures that the removal is performed atomically,
+        preventing race conditions in concurrent environments.
+        
+        Returns the value associated with the key, or None if the key doesn't exist.
+        
+        Example:
+            d = ConcurrentDictionary({'x': 1, 'y': 2})
+            value = d.remove_atomic('x')  # Returns 1, removes 'x'
+        """
+        with self._lock:
+            return self._dict.pop(key, None)
+
+    def remove_if_exists(self, key: K) -> bool:
+        """
+        Atomically remove a key from the dictionary if it exists.
+        
+        Returns True if the key was removed, False if it didn't exist.
+        
+        Example:
+            d = ConcurrentDictionary({'x': 1})
+            removed = d.remove_if_exists('x')  # Returns True
+            removed = d.remove_if_exists('y')  # Returns False
+        """
+        with self._lock:
+            if key in self._dict:
+                del self._dict[key]
+                return True
+            return False
+
+    def get_and_remove(self, key: K, default: Optional[V] = None) -> Optional[V]:
+        """
+        Atomically get the value for a key and remove it from the dictionary.
+        
+        This is equivalent to pop(key, default) but with a more descriptive name
+        for atomic operations.
+        
+        Example:
+            d = ConcurrentDictionary({'x': 1})
+            value = d.get_and_remove('x')  # Returns 1, removes 'x'
+        """
+        return self.pop(key, default)
+
+    def put_if_absent(self, key: K, value: V) -> Optional[V]:
+        """
+        Atomically put a value for a key only if the key is not already present.
+        
+        Returns the existing value if the key exists, None if the key was added.
+        
+        Example:
+            d = ConcurrentDictionary({'x': 1})
+            existing = d.put_if_absent('x', 2)  # Returns 1, no change
+            existing = d.put_if_absent('y', 3)  # Returns None, adds 'y': 3
+        """
+        with self._lock:
+            if key in self._dict:
+                return self._dict[key]
+            else:
+                self._dict[key] = value
+                return None
+
+    def replace_if_present(self, key: K, value: V) -> bool:
+        """
+        Atomically replace the value for a key only if the key exists.
+        
+        Returns True if the key was replaced, False if the key doesn't exist.
+        
+        Example:
+            d = ConcurrentDictionary({'x': 1})
+            replaced = d.replace_if_present('x', 2)  # Returns True
+            replaced = d.replace_if_present('y', 3)  # Returns False
+        """
+        with self._lock:
+            if key in self._dict:
+                self._dict[key] = value
+                return True
+            return False
+
+    def replace_if_equal(self, key: K, old_value: V, new_value: V) -> bool:
+        """
+        Atomically replace the value for a key only if the current value equals old_value.
+        
+        Returns True if the value was replaced, False otherwise.
+        
+        Example:
+            d = ConcurrentDictionary({'x': 1})
+            replaced = d.replace_if_equal('x', 1, 2)  # Returns True
+            replaced = d.replace_if_equal('x', 1, 3)  # Returns False (current value is 2)
+        """
+        with self._lock:
+            if key in self._dict and self._dict[key] == old_value:
+                self._dict[key] = new_value
+                return True
+            return False
 
     def pop(self, key: K, default: Optional[V] = None) -> Optional[V]:
         with self._lock:
@@ -171,4 +268,29 @@ def __iter__(self) -> Iterator[K]:
 
     def __repr__(self) -> str:
         with self._lock:
-            return f"ConcurrentDictionary({self._dict!r})"
+            return f"ConcurrentDictionary({self._dict!r})"
+
+    def __eq__(self, other: Any) -> bool:
+        """
+        Thread-safe equality comparison.
+        
+        Two ConcurrentDictionary instances are equal if they have the same key-value pairs.
+        """
+        if not isinstance(other, ConcurrentDictionary):
+            return False
+        
+        with self._lock:
+            with other._lock:
+                return self._dict == other._dict
+
+    def __hash__(self) -> int:
+        """
+        Thread-safe hash computation.
+        
+        The hash is computed based on the current state of the dictionary.
+        Note: The hash will change if the dictionary is modified.
+        """
+        with self._lock:
+            # Convert to frozenset of items for consistent hashing
+            items = frozenset(self._dict.items())
+            return hash(items)