Advent of Changelog: Day 7

Author: zverok

_src/3.3.md

@@ -64,18 +64,40 @@ Allows to assign a string to be rendered as class/module's `#name`, without assi
 
 ### `ObjectSpace::WeakKeyMap`
 
-* **Reason:**
+A new "weak map" concept implementation. Unlike `ObjectSpace::WeakMap`, it compares keys by equality (`WeakMap` compares by identity), and only references to keys are weak (garbage-collectible).
+
+* **Reason:** The idea of a new class grew out of increased usage of `ObjectSpace::WeakMap` (which was once considered internal). In many other languages, concept of "weak map" implies only key references are weak: this allows to use it as a generic "holder of some additional information related to a set of objects while they are alive," or just a weak set of objects (using them as keys and `true` as values): caches, deduplication sets, etc.
 * **Discussion:** [Feature #18498]
 * **Documentation:** [ObjectSpace::WeakKeyMap](https://docs.ruby-lang.org/en/master/ObjectSpace/WeakKeyMap.html)
 * **Code:**
-* **Notes:**
+* **Notes:** The class interface is significantly leaner than `WeakMap`'s, and doesn't provide any kind of iteration methods (which is very hard to implement and use correctly with weakly-referenced objects), so the new class is more like a black box with associations than a collection.
 
 ### `ObjectSpace::WeakMap#delete`
 
-* **Reason:**
+* **Reason:** `WeakMap` is frequently used to have a loose list of objects that will need some processing at some point of program execution if they are still alive/used (that's why `WeekMap` and not `Array`/`Hash` is chosen in those cases). But it is possible that the code author wants to process objects conditionally, and to remove those which don't need processing anymore—even if they are still alive. `WeekMap` quacks like kind-of simple `Hash`, yet previously provided no way to delete keys.
 * **Discussion:** [Feature #19561]
 * **Documentation:** [ObjectSpace::WeakMap#delete](https://docs.ruby-lang.org/en/master/ObjectSpace/WeakMap.html#method-i-delete)
 * **Code:**
+  ```ruby
+  files_to_close = ObjectSpace::WeakMap.new
+  file1 = File.new('README.md')
+  file2 = File.new('NEWS.md')
+
+  files_to_close[file1] = true
+  files_to_close[file2] = true
+
+  files_to_close.delete(file1) #=> true
+
+  # Attempt to delete non-existing key:
+  files_to_close.delete(file1) #=> nil
+  # An optional block can be provided in case the key doesn't exist:
+  files_to_close.delete(file1) { puts "Already removed"; 0 }
+  # Prints "Already removed", returns `0`
+
+  # The block wouldn't be called if the deletion was effectful:
+  files_to_close.delete(file2) { puts "Already removed"; 0 }
+  # Prints nothing, returns true
+  ```
 * **Notes:**
 
 ### `Proc#dup` and `#clone` call `#initialize_dup` and `#initialize_clone`