Improve Flyweight with more documentation

Author: fadeevab

structural/flyweight/README.md

@@ -1,10 +1,12 @@
 # Flyweight
 
-_**Flyweight** is a structural design pattern that allows programs to support
-ast quantities of objects by keeping their memory consumption low._
+_**Flyweight** (Cache) is a structural design pattern that allows programs to
+support vast quantities of objects by keeping their memory consumption low._
+
+It's an _internal cache_ hidden behind a settle Facade-like API.
+The cache stores shared parts that are referenced from multiple objects.
+_See more explanation below._
 
-The pattern achieves it by sharing parts of object state between multiple
-objects.
 
 ## Rendering a Forest
 
@@ -24,25 +26,47 @@ For 100,000 trees:
 
 ```
 100000 trees drawn
----------------------
+Cache length: 2 tree kinds
+-------------------------------
 Memory usage:
 Tree size (16 bytes) * 100000
 + TreeKind size (~30 bytes) * 2
----------------------
+-------------------------------
 Total: 1MB (instead of 4MB)
 ```
 
-Flyweight is implemented via a `HashMap` that holds only one copy
-of a `TreeKind` for each `Tree` inside of the `Forest` structure.
+## Overview
+
+`Forest` has a public API that can not be changed for backward compatibility reasons:
+
+```rust
+pub fn plant_tree(&mut self, x: u32, y: u32, color: TreeColor, name: String, data: String);
+```
+
+There is an internal cache that is implemented via a `HashSet` that holds
+only one copy of a common part (`TreeKind`) of thousands of trees.
 
 ```rust
 #[derive(Default)]
 pub struct Forest {
-    pub tree_kinds: HashMap<String, Rc<TreeKind>>,
-    pub trees: Vec<Tree>,
+    cache: HashSet<Rc<TreeKind>>,
+    trees: Vec<Tree>,
 }
 ```
 
+The point is having an opaque cache implementation. It can use a hash set,
+FIFO, or even a simple vector. And it's hidden behind the API because that's
+the point: we try to optimize internals without changing a public method,
+otherwise we could always pass a common part from top to bottom.
+
+Other points:
+ - `cache` is of `HashSet` type, so it can hold only a single
+    instance of a `TreeKind`,
+- `Rc` is needed to get the reference on the tree kind without
+   cloning a full structure,
+- `TreeKind` must derive `Eq`, `PartialEq`, and `Hash` traits to be
+   used in the `HashSet`.
+
 ## Reference
 
 The example reproduces a [Flyweight Example in Java (Rendering a Forest)](https://refactoring.guru/design-patterns/flyweight/java/example).

structural/flyweight/forest.rs

@@ -1,29 +1,40 @@
 mod tree;
 
 use draw::Canvas;
-use std::{collections::HashMap, rc::Rc};
+use std::{collections::HashSet, rc::Rc};
 use tree::{Tree, TreeKind};
 
 pub use self::tree::TreeColor;
 
+/// Forest implements an internal cache that is hidden behind the public API.
+///
+/// The point is having an opaque cache implementation. It can use a hash set,
+/// FIFO, or even a simple vector.
+///
+/// Here are the key points:
+/// - `cache` is of `HashSet` type, so it can hold only a single
+///    instance of a `TreeKind`,
+/// - `Rc` is needed to get the reference on the tree kind without
+///    cloning the full structure,
+/// - `TreeKind` must derive `Eq`, `PartialEq`, and `Hash` traits to be
+///    used in the `HashSet`.
 #[derive(Default)]
 pub struct Forest {
-    pub tree_kinds: HashMap<String, Rc<TreeKind>>,
-    pub trees: Vec<Tree>,
+    cache: HashSet<Rc<TreeKind>>,
+    trees: Vec<Tree>,
 }
 
 impl Forest {
     pub fn plant_tree(&mut self, x: u32, y: u32, color: TreeColor, name: String, data: String) {
-        // Here is the substance of the Flywheight Pattern:
+        let tree_kind = TreeKind::new(color, name.clone(), data);
+
+        // Here is an essence of Flyweight: it's an internal cache,
         // there is always a single instance of a "tree kind" structure.
-        let tree_kind = self
-            .tree_kinds
-            .entry(name.clone())
-            .or_insert(Rc::new(TreeKind::new(color, name.clone(), data)));
+        self.cache.insert(Rc::new(tree_kind.clone()));
 
         // A tree kind is referenced from each tree instance using `Rc` pointer.
         // `tree_kind.clone()` increases a reference counter instead of real cloning.
-        let tree = Tree::new(x, y, tree_kind.clone());
+        let tree = Tree::new(x, y, self.cache.get(&tree_kind).unwrap().clone());
         self.trees.push(tree);
     }
 
@@ -32,4 +43,8 @@ impl Forest {
             tree.draw(canvas);
         }
     }
+
+    pub fn cache_len(&self) -> usize {
+        self.cache.len()
+    }
 }

structural/flyweight/forest/tree.rs

@@ -2,6 +2,7 @@ use std::rc::Rc;
 
 use draw::{Canvas, Drawing, Shape, Style, RGB};
 
+#[derive(Clone, PartialEq, Eq, Hash)]
 pub enum TreeColor {
     Color1,
     Color2,
@@ -18,6 +19,9 @@ impl TreeColor {
     }
 }
 
+/// A cacheable item. It derives `PartialEq`, `Eq`, and `Hash` in order to be
+/// used in the `HashSet`.
+#[derive(Clone, PartialEq, Eq, Hash)]
 pub struct TreeKind {
     color: TreeColor,
     _name: String,

structural/flyweight/main.rs

@@ -38,11 +38,12 @@ fn main() {
     render::save(&canvas, "res/forest.svg", SvgRenderer::new()).expect("Rendering");
 
     println!("{} trees drawn", TREES_TO_DRAW);
-    println!("---------------------");
+    println!("Cache length: {} tree kinds", forest.cache_len());
+    println!("-------------------------------");
     println!("Memory usage:");
     println!("Tree size (16 bytes) * {}", TREES_TO_DRAW);
     println!("+ TreeKind size (~30 bytes) * {}", TREE_TYPES);
-    println!("---------------------");
+    println!("-------------------------------");
     println!(
         "Total: {}MB (instead of {}MB)",
         ((TREES_TO_DRAW * 16 + TREE_TYPES * 30) / 1024 / 1024),