2.4 million cells, 37 formats
A heap snapshot of a web spreadsheet, taken while a user had a sales export open, showed 2.4 million CellFormat objects using about 480 MB. The sheet was 200,000 rows by 12 columns, and every cell carried its own format: font family and size, bold and italic, text and fill colours, borders, alignment, and a number format such as #,##0.00. With its strings, each format came to about 200 bytes.
Then someone counted the distinct ones. There were 37: a header style, a currency style, a date style, a few highlight colours and plain text, repeated down the columns. The browser tab was holding 2.4 million copies of 37 answers.
What a cell really owns
A cell's data comes in two kinds. Its value and its position belong to that one cell. Its format is something it has in common with hundreds of thousands of others. Keep one object per distinct format, let every cell hold a reference to the one it uses instead of a copy of its own, and you have the design the Gang of Four catalogue named Flyweight. Each shared object is a flyweight.
The pattern names the two kinds. Intrinsic state is what the flyweight holds and shares, here everything in the format. Extrinsic state depends on where the flyweight is used, so the flyweight does not store it, and the caller passes it in. In the rebuilt renderer a cell no longer draws itself. The renderer asks the cell's format to draw and hands it what only the cell knows, format.draw(canvas, x, y, value), with x and y worked out from the row and column.
B2 and B3 share one currency format and A1 uses the header format. The factory holds one object per distinct format and hands out the existing one.
The cells themselves did not go away. There are still 2.4 million of them, each with a value and a reference to a format, and each cell already held that reference before, so it costs nothing new. What went away is every format object but 37: nearly all of the 480 MB.
One place that hands out formats
To share a format, the code that needs one has to find the copy that already exists, so every format comes from a flyweight factory, here FormatFactory.get(spec), which looks the spec up in a table and returns the object already there, creating and storing one only on the first request for that spec. When the user pastes 50,000 rows in bold currency, the factory is asked 50,000 times and builds at most one object.
The key must cover every intrinsic field, normalised so that #FF0000 and #ff0000 land on the same format. The table also keeps every format it has ever made. For one open document like this one, that is a few dozen objects; in a long-running server that shares values across requests, a table that only grows keeps formats nobody uses any more, which is why such tables often hold weak references or are dropped with the document they belong to. And if several threads can ask for a new spec at once, the lookup and the insert must happen as one atomic step, or two equal formats can get built.
Bold one cell, bold four hundred thousand
The first bug report after the change was alarming. A user selected B2, clicked Bold, and every currency cell in the sheet turned bold. The Bold button's handler still did what it had always done, cell.format.bold = true, and cell.format was now one object shared by 400,000 cells.
This is why intrinsic state is normally kept immutable, and here it has to be. A flyweight is read by every cell that holds it, so a change made through one cell is made to all of them. Formats become read-only once the factory has built them, and changing one cell's format means asking the factory for the format the cell should have now, its current spec with bold switched on, factory.get(spec.with({ bold: true })), and pointing that one cell at the result. The other 399,999 cells keep the format they had.
Two formats, not one, in the Challenge
The Flyweight Pattern Challenge gives you eight nodes and asks for flyweights holding shared immutable state, a factory or cache that returns existing instances, clients passing extrinsic state in at call time, and many contexts referencing the same flyweight. Draw two Flyweight nodes, two formats for instance, with a Cache node as the factory that holds both, and three or four Component nodes as contexts, more than one of them pointing at the same flyweight. Add one Client node and put the extrinsic state on its edge to a flyweight, as a label such as draw(x, y, value), so the drawing shows it is passed in and not stored.
Not one, not a copy, not a loan
Three neighbours are easy to confuse with it. A Singleton is one instance per class; the factory here keeps 37, one per distinct format. A Prototype clone is a new object that can then diverge from its original; a flyweight is the same object everywhere, which is why it is normally immutable. An Object Pool lends an object to one borrower at a time and wants it back; a flyweight is used by everyone at once. A flyweight is usually also a Value Object, immutable and defined by its fields, and when the shared pieces are leaves of a tree built with Composite, a leaf can be shared only if it does not store its parent, since the parent is extrinsic state that differs wherever the leaf appears.
When the arithmetic does not work
The saving is roughly the number of objects that stop carrying their own copy, times the size of what they stop carrying, minus what sharing adds: the factory's table of shared objects, and a reference in each object that did not already hold one. For the spreadsheet that is 2.4 million times 200 bytes, against a table of 37 entries. Run the same sum on other cases and it can come out near zero:
- Few objects. A sheet of 300 cells saves about 60 KB, less than one image on the page, and every code path that sets a format now has to go through the factory.
- Small intrinsic state. If what the objects share is a single boolean, the reference that replaces it is as large as the field it replaces, or larger.
- Values that rarely repeat. Conditional formatting that gives each cell its own colour on a gradient makes nearly every format distinct. The factory then holds about as many objects as before, plus a lookup on every change.
- The runtime already shares. Many language runtimes already reuse some immutable values, such as string literals or small integers, so the duplicates you expected to remove may not be there.
So measure before and after with your runtime's heap profiler, and count the two numbers the pattern depends on: how many objects there are, and how many distinct values they hold. A gap like 2.4 million to 37 is what makes Flyweight worth its factory.