Flyweight

Flyweight reduces memory by sharing the parts of many objects that are identical, keeping only what genuinely differs per instance. It is the one pattern in the catalogue that exists purely for a resource constraint, and that makes it the one most often applied without evidence.

Reach for it after a measurement, never before. The pattern trades clarity and mutability for memory, and a program that did not have a memory problem has simply become harder to read.

The split that defines it

Every field on an object is one of two kinds:

Intrinsic state is the same for many instances and independent of context — a character's glyph outline, a tree species' texture and name, a log level's label and severity. This can be shared.

Extrinsic state is unique per use and depends on context — where this character sits on the page, where this tree stands in the forest, when this log line was written. This cannot be shared, and must be passed in or stored elsewhere.

// Shared: one object per species, however many trees exist
class TreeSpecies {
  constructor(name, texture, mesh) {
    this.name = name; this.texture = texture; this.mesh = mesh;
    Object.freeze(this);
  }
}

const speciesCache = new Map();
function speciesFor(name, texture, mesh) {
  if (!speciesCache.has(name)) speciesCache.set(name, new TreeSpecies(name, texture, mesh));
  return speciesCache.get(name);
}

// Per instance: only what differs
class Tree {
  constructor(x, y, scale, species) { this.x = x; this.y = y; this.scale = scale; this.species = species; }
}

A million trees across twelve species holds twelve textures rather than a million. The saving is proportional to the ratio of instances to distinct intrinsic values, which is why the pattern is spectacular in the rare cases it fits and pointless everywhere else.

Immutability is not optional

The shared object is referenced by every instance using it. If it can be mutated, changing it for one changes it for all — the same aliasing failure described under Prototype, but affecting a million objects rather than two.

Freeze the shared object at construction. If the language cannot enforce that, expose no setters and copy anything mutable on the way in. A flyweight with a public mutable field is a bug that has not happened yet.

You already use it

String interning. Most runtimes share identical string literals so that a million occurrences of "active" are one object. This is Flyweight built into the language, and it is why identity comparison on strings is a trap in some languages — two equal strings may or may not be the same object.

Boxed integer caches. Small integers are commonly pre-allocated and shared, which produces the classic surprise that identity comparison works for small values and fails for large ones.

Symbols, enums and interned atoms. One object per distinct name, referenced everywhere.

Glyph rendering. The original motivating case: a document with a million characters holds one object per distinct character, not per occurrence.

Column-oriented storage. Dictionary encoding — storing distinct values once and referencing them by index — is Flyweight applied to data at rest, and it is why analytical databases compress categorical columns so well.

Why it is a last resort

It complicates the object model. Extrinsic state has to be passed to every method that needs it, so signatures grow: species.render(x, y, scale) instead of tree.render(). That noise appears everywhere the flyweight is used.

It forbids mutation. A perfectly reasonable future requirement — "let the user rename a species" — now has to consider every sharer.

The cache is a leak by default. A map from key to flyweight holds every entry forever. Unbounded key spaces need weak references or eviction, and getting this wrong replaces a memory problem with a worse one.

Cheaper options usually exist. Before restructuring, check whether the objects can simply be fewer, smaller, or absent:

• Do all million need to exist at once? Streaming or paging removes the problem rather than shrinking it.
• Is a compact representation available? A struct-of-arrays layout, or typed arrays instead of objects, often beats Flyweight and keeps the code simple.
• Is the memory actually in the objects? Profilers routinely show the real cost is elsewhere — a cache, a retained request buffer, a logging framework.

Check your understanding

Common mistakes

Applying it without measuring. The pattern costs clarity and mutability, and buys nothing if values do not repeat heavily.

A mutable shared object. One write, a million silently wrong instances, and no proximity between cause and symptom.

An unbounded cache. A leak introduced to fix a memory problem.

Splitting the state wrongly. A field that varies per instance living on the shared object means instances silently share a value they should not.

Ignoring cheaper options. Fewer objects, streaming, or a compact array layout usually beats Flyweight and keeps the code readable.

Relying on identity comparison. Whether two equal values are the same object depends on whether interning applied, which varies by runtime and by value.

Practice

Key takeaways

• Flyweight shares intrinsic state (identical across instances) and keeps extrinsic state (unique per use) outside.
• The saving is roughly instances ÷ distinct values — transformative at high repetition, worthless at low.
• Measure first. It is the one pattern that exists purely for a resource constraint, so applying it without evidence is pure cost.
• Shared objects must be immutable, enforced structurally. Mutation surfaces as unrelated objects being wrong, far from the write.
• The cache is a leak by default. Bound it unless the key space is provably finite.
• You already use it: string interning, boxed integer caches, enums and dictionary encoding in columnar stores.
• Cheaper alternatives usually exist: fewer objects, streaming, or a compact array layout.
• A canonical shared instance is sometimes right for modelling reasons rather than memory — currencies, enums, units.

Further reading

• Erich Gamma, Richard Helm, Ralph Johnson and John Vlissides, Design Patterns: Elements of Reusable Object-Oriented Software (Addison-Wesley, 1994).
• Paul Calder and Mark Linton, "Glyphs: Flyweight Objects for User Interfaces" (ACM UIST, 1990) — the origin of the pattern.
• Daniel Abadi, Samuel Madden and Miguel Ferreira, "Integrating Compression and Execution in Column-Oriented Database Systems" (ACM SIGMOD, 2006) — dictionary encoding.
• Brian Goetz and others, Java Concurrency in Practice (Addison-Wesley, 2006) — immutability and safe sharing.
• Martin Fowler, Patterns of Enterprise Application Architecture (Addison-Wesley, 2002) — value objects and money.