Explain Ref problems

diff --git a/src/mono_hash_map.rs b/src/mono_hash_map.rs
index 56d6e1400f3eae5cb40d8ba97a7681096e126ca5..ec1a5fdb4288f6166722f65031cd79b7e6eb699f 100644 (file)
--- a/src/mono_hash_map.rs
+++ b/src/mono_hash_map.rs
@@ -20,7 +20,12 @@
 impl<K: Hash + Eq, V> MonoHashMap<K, V> {
     /// This function exists for priroda to be able to iterate over all evaluator memory
     ///
-    /// The memory of constants does not show up in this list.
+    /// The function is somewhat roundabout with the closure argument because internally the
+    /// `MonoHashMap` uses a `RefCell`. When iterating over the `HashMap` inside the `RefCell`,
+    /// we need to keep a borrow to the `HashMap` inside the iterator. The borrow is only alive
+    /// as long as the `Ref` returned by `RefCell::borrow()` is alive. So we can't return the
+    /// iterator, as that would drop the `Ref`. We can't return both, as it's not possible in Rust
+    /// to have a struct/tuple with a field that refers to another field.
     pub fn iter<T>(&self, f: impl FnOnce(&mut dyn Iterator<Item=(&K, &V)>) -> T) -> T {
         f(&mut self.0.borrow().iter().map(|(k, v)| (k, &**v)))
     }