Flyweight Design Pattern

/** The flyweight: intrinsic state only, deeply immutable, shared by everyone. */
public record TreeType(String species, Mesh mesh, Texture bark, Texture leaf) {

    private static final Map<String, TreeType> POOL = new ConcurrentHashMap<>();

    /** The factory. Callers never see `new`. */
    public static TreeType of(String species) {
        // computeIfAbsent is atomic — two threads planting the first oak at the
        // same moment still end up with exactly one TreeType.
        return POOL.computeIfAbsent(species, TreeType::load);
    }

    private static TreeType load(String species) {
        return new TreeType(species, Meshes.load(species), Textures.bark(species), Textures.leaf(species));
    }

    /** Extrinsic state arrives as arguments — it is never stored here. */
    public void draw(Canvas canvas, int x, int y, float scale) {
        canvas.render(mesh, bark, leaf, x, y, scale);
    }
}

/** The client keeps only what actually differs: 24 bytes, not 2 MB. */
public record Tree(int x, int y, float scale, TreeType type) {
    public void draw(Canvas canvas) { type.draw(canvas, x, y, scale); }
}

// The JDK ships flyweights you use without noticing:
//   Integer.valueOf(127) == Integer.valueOf(127)   // true  — cached -128..127
//   Integer.valueOf(128) == Integer.valueOf(128)   // false — outside the cache
// String literals are interned into a shared pool for exactly the same reason.
// That first pair of lines is also the classic Java interview question.

from dataclasses import dataclass
from functools import lru_cache


@dataclass(frozen=True, slots=True)
class TreeType:
    """frozen: sharing is only safe if nobody can mutate it.
    slots:  no per-instance __dict__ — which is itself a memory win worth
            knowing about, roughly 100+ bytes saved per object.
    """
    species: str
    mesh: Mesh
    bark: Texture
    leaf: Texture

    def draw(self, canvas: Canvas, x: int, y: int, scale: float) -> None:
        canvas.render(self.mesh, self.bark, self.leaf, x, y, scale)


@lru_cache(maxsize=None)          # the factory, in one decorator
def tree_type(species: str) -> TreeType:
    return TreeType(species, load_mesh(species), bark(species), leaf(species))


@dataclass(frozen=True, slots=True)
class Tree:
    x: int
    y: int
    scale: float
    type: TreeType            # a reference, not a copy


# CPython does this internally too, and the results surprise people:
#   a = 256; b = 256; a is b     # True  — small ints are pre-allocated
#   a = 257; b = 257; a is b     # False — outside the cache
#   sys.intern(s)                # force a string into the shared pool
#
# lru_cache with maxsize=None never evicts, which is what you want for a fixed
# set of species and what you must NOT use for unbounded keys — that's a leak.

#include <memory>
#include <string>
#include <unordered_map>

class TreeType {                       // flyweight: immutable after construction
public:
    TreeType(std::string species, Mesh mesh, Texture bark, Texture leaf)
        : species_(std::move(species)), mesh_(std::move(mesh)),
          bark_(std::move(bark)), leaf_(std::move(leaf)) {}

    void draw(Canvas& c, int x, int y, float scale) const {
        c.render(mesh_, bark_, leaf_, x, y, scale);
    }

private:
    const std::string species_;
    const Mesh mesh_;
    const Texture bark_, leaf_;
};

class TreeTypeFactory {
public:
    std::shared_ptr<const TreeType> of(const std::string& species) {
        std::lock_guard lock(m_);
        auto& slot = pool_[species];
        if (!slot) slot = std::make_shared<const TreeType>(species, loadMesh(species),
                                                          bark(species), leaf(species));
        return slot;
    }
private:
    std::mutex m_;
    std::unordered_map<std::string, std::shared_ptr<const TreeType>> pool_;
};

// `shared_ptr<const T>` states the two guarantees in the type: shared ownership,
// and nobody can mutate it. Note the cost the pattern doesn't advertise —
// following a pointer to shared data can be a cache miss per object, so a
// million tiny flyweights can be SLOWER than a packed array of plain structs.
// If the data is small, data-oriented layout beats sharing; measure both.

public sealed record TreeType(string Species, Mesh Mesh, Texture Bark, Texture Leaf)
{
    private static readonly ConcurrentDictionary<string, TreeType> Pool = new();

    public static TreeType Of(string species) =>
        Pool.GetOrAdd(species, static s => new TreeType(s, Meshes.Load(s), Textures.Bark(s), Textures.Leaf(s)));

    public void Draw(Canvas canvas, int x, int y, float scale) =>
        canvas.Render(Mesh, Bark, Leaf, x, y, scale);
}

// Extrinsic state in a readonly struct: no heap allocation, no GC pressure,
// and a million of them sit contiguously in one array.
public readonly record struct Tree(int X, int Y, float Scale, TreeType Type);

// GetOrAdd's factory may run more than once under contention (only one result
// wins) — fine here because loading a mesh is idempotent, a real problem if the
// factory has side effects. Use Lazy<T> as the value when it must run once.
//
// .NET's own flyweights: string interning (string.Intern), and the cached
// boxed values behind Enum and small integers.

// The factory is a Map plus a miss check. Object.freeze buys you the
// immutability the pattern depends on — without it, one caller mutating the
// shared type mutates it for every tree on the map.

const pool = new Map()

export const treeType = species => {
  let type = pool.get(species)
  if (!type) {
    type = Object.freeze({
      species,
      mesh: loadMesh(species),
      bark: bark(species),
      leaf: leaf(species),
      draw(canvas, x, y, scale) {
        canvas.render(this.mesh, this.bark, this.leaf, x, y, scale)
      },
    })
    pool.set(species, type)
  }
  return type
}

const forest = positions.map(([x, y, s]) => ({ x, y, s, type: treeType(pickSpecies()) }))

// `Symbol.for('x')` is a flyweight built into the language: a global registry
// where the same key always returns the identical symbol, across every module
// in the realm. And be careful with Map as a pool — it holds strong references,
// so an unbounded key space never gets collected. Use WeakRef or an LRU when
// keys are user-supplied.

package forest

// The pool. sync.Map is tuned for exactly this access pattern: written a few
// times at startup, then read from many goroutines forever.
var pool sync.Map // species -> *TreeType

type TreeType struct {
	Species string
	Mesh    Mesh
	Bark    Texture
	Leaf    Texture
}

func TypeOf(species string) *TreeType {
	if t, ok := pool.Load(species); ok {
		return t.(*TreeType)
	}
	t := &TreeType{species, loadMesh(species), bark(species), leaf(species)}
	actual, _ := pool.LoadOrStore(species, t)   // last word on the race
	return actual.(*TreeType)
}

// Extrinsic state, 24 bytes, stored by value in one contiguous slice.
type Tree struct {
	X, Y  int32
	Scale float32
	Type  *TreeType
}

// Do not confuse this with sync.Pool. sync.Pool RECYCLES temporary mutable
// objects to reduce GC pressure, and anything it hands you may vanish at the
// next GC. A flyweight is the opposite: permanently shared, never mutated,
// never reclaimed. Same word "pool", opposite lifecycle.
//
// time.LoadLocation is the standard library's flyweight — every call for
// "Europe/London" returns the same *time.Location.

interface TreeType {
  readonly species: string
  readonly mesh: Mesh
  readonly bark: Texture
  readonly leaf: Texture
}

const pool = new Map<string, TreeType>()

export function treeType(species: string): TreeType {
  const existing = pool.get(species)
  if (existing) return existing

  const created: TreeType = Object.freeze({
    species,
    mesh: loadMesh(species),
    bark: bark(species),
    leaf: leaf(species),
  })
  pool.set(species, created)
  return created
}

// `readonly` is a compile-time promise only — it disappears at runtime, so a
// value that crosses an `any` boundary or arrives from JSON.parse can still be
// mutated. For a genuinely shared object, keep BOTH: readonly for the developer
// and Object.freeze for the runtime.

interface Tree {
  readonly x: number
  readonly y: number
  readonly scale: number
  readonly type: TreeType     // one pointer, not a copy
}

// A branded key type stops the classic pool bug — two different id spaces
// silently sharing one cache:
type SpeciesKey = string & { readonly __brand: 'SpeciesKey' }