Frank Hileman (no blog, Frank?) has been pounding us (the Avalon team) with some great
questions. Most of these have been conversations in comments, but I figured
that I should bring this to the front page, so to speak.
Of of Frank's concerns, at least as expressed in my comments section, is
that we are essentially over engineering with the Changeable pattern. Specifically,
he says this:
The non-intrusive part of Changeable has a const flag on stock brushes, etc. This
means the user must clone these and write to a copy. This is simple and easy to understand.
The intrusive part of Changeable is the part which introduces the idea of "used" and
changes the simple concept of "object reference" into something complicated. From
what you have explained, the intrusive part of Changeable exists only to allow simultaneous
multi-threaded writers to the scene graph.
I think that the point around threading is a red-herring here.
Changeable Requirements
The main problem that changeables are trying to solve is that we want to have, under
most circumstances, these changeable API objects (Brush, Pen, etc.) act like value
types and other times we want them to act like refernce types. We essentially
want to walk a fine line and get advantages from each. Frank, forgive me if
you've heard a bunch of this before, but I think that this is useful to put together
in one place.
With respect to value types, we want the simple user semantic to be: Modify my local
copy and have it be disconnected or "severed" when I pass it in to another object.
When rendering this means that I can do this:
SolidColorBrush scb = new SolidColorBrush();
scb.Color = Colors.Blue;
myDrawingContext.DrawGeometry(scb, null /*pen*/, myGeometry1);
scb.Color = Colors.Red;
myDrawingContext.DrawGeometry(scb, null /*pen*/, myGeometry2);
and have my two geometries be drawn with different colors. Since many times
the drawing context is writing in to a metafile like data structure, if we used pure
reference semantics both geometries would be drawn as Red.
Another example is setting properties in to a set of elements:
SolidColor Brush scb = new SolidColorBrush();
scb.Color = Colors.Blue;
myElement1.Background = scb;
myElement2.Background = scb;
// in some other code...
((SolidColorBrush)myElement1.Background).Color = Colors.Red;
I think, in most cases, if some user walks up to an element, such as myElement1 above,
and sets the background brush, he doesn't expect that this will have the side effect
of changing the background brush of another element. Side effects like this
would make for an unstable system.
Value types don't solve all of our problems though! We also want the efficiencies
and advanatages of making these be reference types. Specifically, we want to
have to have hierarchies, not have to copy the entire thing around and be able to
save space by having multiple places reference the same thing. We imagine a
world with lots of elements getting their values via styling. Because of this,
we want the normal case be that a user puts a value in to a style block somewhere
and then that object (via reference) gets widely shared, perhaps between hundreds
of elements. We obviously want to make the per-reference cost as small as possible
here. Going with a pure value type system won't work.
The Builder Pattern
The first cut at solving this problem was called the Builder Pattern. This pattern
was a generalization of the StringBuilder pattern. Specifically, for each type,
there was a companion, or Builder type. The main type was immutable. In
other words, any write operations would raise an exception. So, for SolidColorBrush,
we wrote a SolidColorBrushBuilder. SolidColorBrush was immutable while SolidColorBrushBuilder
was a fully writeable object. All of the APIs in the system (property types
on element, parameters in to DrawingContext methods, etc.) took the non-builder types.
To create one of those non-builder types, the user had to do one of the following:
-
Create the target type directly by using a constructor.
-
Create a builder, configure it, and call the ToXXX method on it to construct the main
type.
-
Create a builder by initializing it off of its companion type. Make a delta
and call the ToXXX method to construct the main type.
From one point of view, this is a great system. It is very explicit (at compile
time) what is editable and what isn't. However, some early users of our system
(ad-hoc usability) ended up really disliking this system. The need to constantly
deal with both types was onourous. It also meant that the user could never just
index directly in to a type and change it. To affect any change, it was
always necessary to create the builder, make the change, and set the old value in.
The Changeable Pattern
In response to a hail of internal criticism on the Builder Pattern we went back and
came up with the Changeable pattern. The idea is that we would have one type
object with an immutable bit. Once the immutable bit gets set, all further changes
to that object will throw. This opens the way up to runtime errors (instead
of compile time errors) but makes certain "delta" scenarios much easier to deal with.
However, we still wanted to solve the problems listed in the first part of this post.
Specifically, we didn't want to leave it up to the user to manually flip the immutable
bit. In this way we defined certain types of operations that would automatically
create a copy and flip the immutable bit for you if necessary. We then went
further and added advanced modes so that those APIs either make a copy but don't flip
the immutable bit or the APIs just take a reference. These last modes (whereby
something like an element holds on to a mutable brush) were never possible
with the Builder pattern.
We also added a notification mechanism so that someone who does hold on to an object
that isn't immutable can learn when that object changes.
So, do you guys (Frank?) like the more explicit builder pattern better? More
questions?