When to Choose Your Own Implementation in the Bridge Pattern

At this rate, every pattern in Design Patterns in Dart is going to include a websocket. That is a little crazy considering that I do not use websockets all that often in actual client code, but they have the dual benefits of having an accessible API and being conceptually easy to understand. So who knows, maybe I will find a way to include them in every single pattern.

The pattern of current investigation is the bridge pattern. As I found last night, websockets can serve as a realistic alternative to vanilla HTTP for communication. The alternative implementations for communication make the situation well suited for the bridge pattern, which seeks to "bridge" between an abstraction and multiple implementations.

What I would like to examine tonight is creating the right implementor object. Last night, I made two quick decisions on when to create the Communication implementor. Perhaps I could have done that better.

The abstraction in this bridge pattern example remains a Messenger class. It could be a mobile app for posting status updates or sending direct messages. It could be a web form that does the same thing. Either way, a messenger needs a reference to a concrete implementation of Communication and it needs to know how to post updates. So the interface that refined Messenger classes will need to extend looks like:

// Abstraction
abstract class Messenger {
  Communication comm;
  Messenger(this.comm);
  void updateStatus();
}

The refined messenger class that I am using is a WebMessenger. Its constructor stores a text input element from which it can obtain messages to send:

class WebMessenger extends Messenger {
  InputElement _messageElement;
  WebMessenger(this._messageElement) :
    super(new HttpCommunication());
  // ...
}

The bit after the constructor is a redirection to the superclass constructor, which supplies a Communication implementation to the Messenger superclass. Here is where I make my first decision about when to construct a Communication implementation. By default, I opt to create an HttpCommunication implementation of the Communication interface. Since the superclass requires a Communication object in its constructor, I either had to create one right in the constructor as I have done here or I could have required client code to do so.

The choice of whether the client should provide the implementation or if it should be done in the refined abstraction comes down to the details of the code. To be perfectly honest, I did it this way because it was quickest. It probably was not the correct choice, however. Yesterday's implementation has the client choose when to switch between the websocket and HTTP concrete implementations. If the client code chose when to switch, it probably should determine initial state as well.

But let's move the choice of implementation from the client and instead put in into the WebMessenger. It makes sense to start with a low-overhead HttpCommunication object. Given that, the redirecting constructor can stay as-is. But, should the client find itself at the mercy of a power user who is updating status more often than 3 times a minute, then the WebMessenger should switch to a websocket.

So, after each message, I log the message along with a timestamp:

class WebMessenger extends Messenger {
  // ...
  List _history = [];
  // ...
  void updateStatus() {
    comm.send(message);
    _log(message);
  }

  void _log(message) {
    _history.add([new DateTime.now(), message]);
  }
  // ...
}

Then, after logging I do a simple calculation of the frequency with which this user is updating. If it is too often or too slow, I switch Communication implementations:

class WebMessenger extends Messenger {
  // ...
  void updateStatus() {
    comm.send(message);
    _log(message);
    _maybeChangeCommunication();
  }
  // ...
  _maybeChangeCommunication() {
    if (_history.length < 3) return;

    var last = _history.length - 1,
      dateOld = _history[last-2][0],
      dateNew = _history[last][0],
      diff = dateNew.difference(dateOld);

    if (diff.inSeconds < 60) {
      if (comm is! WebSocketCommunication)
        comm = new WebSocketCommunication();
    }
    else {
      if (comm is! HttpCommunication)
        comm = new HttpCommunication();
    }
  }
}

That does the trick. If I send the first 3 message updates out in quick succession, then WebMessenger upgrades the connection to the WebSocketCommunication implementation. The server sees the first three messages come in over HTTP, then the next few over websockets:

$ ./bin/server.dart
[HTTP] message=asdf+1
[HTTP] message=asdf+2
[HTTP] message=asdf+3
[WebSocket] message=asdf 4
[WebSocket] message=asdf 5
[WebSocket] message=asdf 6
[HTTP] message=asdf+7

I then wait a minute between messages 5 and 6, after which I have crossed the lower threshold and am again in the HttpCommunication implementation.

That seems a nice example of when it make sense for the refined abstraction to have responsibility for choosing the implementation—websockets come through again! I do think that some or all of the choice behavior could move into the abstraction itself. Whether that is a good idea depends on the variance in refined abstractions. If a mobile messenger wanted different thresholds or added a new implementation, then the choose-your-implementation behavior would need to continue to reside in the refined abstractions. But if the web and mobile (and other) refined abstractions could share the same choices, then the subclasses could be wonderfully brief.

Code for the bridge client and the backend server are on the Design Patterns in Dart public repository.

Day #81

‹prev | My Chain | next›

The Bridge Pattern with Websockets and HTTP

Design patterns don't tell us how to develop systems. Patterns are names applied to how we already develop. Knowing patterns well won't help us to implement them better in the future—we are already doing that very fine, thank you very much. Knowing a pattern is understanding its consequences and puts us in a better position to minimize or take advantage of those consequences.

That's all fine—if you recognize the pattern. When I first started playing with it, I could not think of an example in which I had used the bridge pattern. It took me some brain digging, but I think I finally excavated a real-world example of it.

Consider, if you will, a browser application that normally communicates with a server over websockets, but has to switch to plain-old HTTP under certain circumstances. The reason for switching might be an older client, a low-memory browser, or simply that this part of the application needs to talk to an HTTP-only server.

Whatever the reason, the web application should not change when the communication implementation changes. If the application is a simple form, then the web form and backing code should never change when switching between HTTP and websockets:



I need to suss out better names for the actors in this play, but I start by calling the web form a "messenger" and mechanism for talking "communication." They are kind of the same thing, so I need to work on that, but it will do for a start. The Messenger abstraction will require a Communication implementation of some kind and will need to know how to send messages with that communication channel. Expressed in Dart, that looks like:

abstract class Messenger {
  Communicator comm;
  Messenger(this.comm);
  void send();
}

The refined abstraction is a web form messenger that gets the message to send from a text element:

class FormMessenger extends Messenger {
  Element _messageElement;
  FormMessenger(this._messageElement) : super(new HttpCommunicator());

  void send() {
    comm.save(message);
  }

  String get message => _messageElement.value;
}

As can be seen from the send() method, the Communication class needs to support a save() method in order to save the message on the backend:

abstract class Communicator {
  void save(String message);
}

The HttpCommunicator is simple enough, thanks to the HttpRequest.postFormData() method:

class HttpCommunicator implements Communicator {
  void save(message) {
    HttpRequest.postFormData('/save', {'message': message});
  }
}

The second implementor, the WebsocketCommunicator class, takes a little more setup for websockets, but is still pretty straight forward:

class WebSocketCommunicator implements Communicator {
  WebSocket _socket;
  WebSocketCommunicator() { _startSocket(); }

  _startSocket() async {
    _socket = new WebSocket('ws://localhost:4040/ws');

    var _c = new Completer();
    _socket.onOpen.listen((_){ _c.complete(); });
    await _c.future;
  }

  void save(message) {
    _socket.send(message);
  }
}

And that pretty much does it. Aside from some better naming, this feels like a fairly accessible example.

One of the implications of the bridge pattern is that a code decision needs to be made as to where to assign the implementor. For a fist pass, I listen to the two radio buttons in the form and, based on which is selected, I assign a different Communicator:

  queryAll('[name=implementor]').
    onChange.
    listen((e) {
      var input = e.target;
      if (!input.checked) return;

      if (input.value == 'http')
        message.comm = new HttpCommunicator();
      else
        message.comm = new WebSocketCommunicator();
    });

With that, I can switch between implementors and send messages to the server however I like:

$ ./bin/server.dart
[HTTP] message=A+web+form+message%21
[WebSocket] A web form message!
[HTTP] message=A+web+form+message%21
[HTTP] message=A+web+form+message%21
[HTTP] message=A+web+form+message%21

Nice! Now all that is left is to come up with some better names.

Full code for the frontend and backend is located at: https://github.com/eee-c/design-patterns-in-dart/tree/master/bridge.


Day #80

‹prev | My Chain | next›

Handle Body Reference Counting in Garbage Collected Dart

Oh, what the hell. I finished yesterday hand-waving over a particular implementation. Let's see if I can actually implement a reference counting handle body in Dart. There may be no practical application for this in a garbage collected language like Dart, but we'll see...

I continue to use Shape as the abstraction in my bridge pattern exploration. It will now serve double duty as the handle class, holding references to the body implementation. Well, it already did that (which is rather the point of the pattern), but now it needs to reference, dereference, and delete implementors as well.

The implementor is DrawingApi, which knows that subclasses will, among other things, know how to draw a circle:

abstract class DrawingApi {
  void drawCircle(double x, double y, double radius);
}

To maintain reference counts, DrawingApi needs a _refCount instance variable along with ref() and deref() methods to increase and decrease that counter:

abstract class DrawingApi {
  int _refCount = 0;
  void ref() {
    _refCount++;
    print('  $this Increased refcount to $_refCount');
  }
  void deref() {
    _refCount--;
    print('  $this Decreased refcount to $_refCount');
  }
  void drawCircle(double x, double y, double radius);
}

In client code, I can create an instance of two subclasses of DrawingApi:

main() {
  var api1 = new DrawingApi1(),
      api2 = new DrawingApi2();
  // ...
}

Then I initially set those as the "drawer" (the thing that draws, not a thing that holds stuff in desks) property for Circle instances:

main() {
  // ...
  var circle1 = new Circle(1.0, 2.0, 3.0)..drawer = api1,
      circle2 = new Circle(0.0, 6.0, 1.0)..drawer = api1,
      circle3 = new Circle(2.0, 2.0, 1.5)..drawer = api2;
  // ...
}

The Circle class is a concrete implementor of the Shape abstraction / handle class. So assigning api1 to two difference Circle instances needs to update the number of references to api1 accordingly.

I more or less copy the code from the handle / body example from the bridge pattern chapter in the Gang of Four book. The drawer() setter is responsible for noting the new reference, and noting the derefence for the existing object. If the reference count goes to zero, the handle class needs to delete the reference, which I do by assigning the _drawingApi instance variable to null:

abstract class Shape {
  DrawingApi _drawingApi;

  set drawer(DrawingApi other) {
    other.ref();
    if (_drawingApi != null) {
      _drawingApi.deref();
      if (_drawingApi._refCount == 0) {
        print('  ** Deleting no longer used $_drawingApi **');
        _drawingApi = null;
      }
    }
    _drawingApi = other;
  }
}

It is here that I finally realize that there is no point to doing any of this—at least not in this example. Even without explicitly setting _drawingApi to null, it gets assigned to a different value on the following line. Once that happens, Dart itself notes that there is one fewer references to the object and, if zero, schedules the object for garbage collection.

I don't know why I thought this might be necessary in some cases. I do get easily confused in the presence of C++.

Anyhow, back in my client code, I draw those circles with the mixture of api1 and api2, then update the drawers so that everyone is using api2:

main() {
  // ...
  circle1.draw();
  circle2.draw();
  circle3.draw();

  circle1.drawer = api2;
  circle2.drawer = api2;

  api1 = api2 = null;

  circle1.draw();
  circle2.draw();
  circle3.draw();
}

When I run this code, I get what I expect. The first time through a mixture of api1 and api2 drawers are used, when I switch to all-api2, the deletion of the api2 reference is noted, then api2 drawing commences:

./bin/draw.dart
  Instance of 'DrawingApi1' Increased refcount to 1
  Instance of 'DrawingApi1' Increased refcount to 2
  Instance of 'DrawingApi2' Increased refcount to 1
[DrawingApi1] circle at (1.0, 2.0) with radius 3.000
[DrawingApi1] circle at (0.0, 6.0) with radius 1.000
[DrawingApi2] circle at (2.0, 2.0) with radius 1.500
  Instance of 'DrawingApi2' Increased refcount to 2
  Instance of 'DrawingApi1' Decreased refcount to 1
  Instance of 'DrawingApi2' Increased refcount to 3
  Instance of 'DrawingApi1' Decreased refcount to 0
  ** Deleting no longer used Instance of 'DrawingApi1' **
[DrawingApi2] circle at (1.0, 2.0) with radius 3.000
[DrawingApi2] circle at (0.0, 6.0) with radius 1.000
[DrawingApi2] circle at (2.0, 2.0) with radius 1.500

So it works, but Dart already had me covered with garbage collection. The effort is not a complete waste. I did clear up whatever C++ confusion I was suffering. Potentially more important, I have client code that can demonstrate sharing implementors such that garbage collection will reclaim them when they go unused.

Play with the code on DartPad: https://dartpad.dartlang.org/43585b1f6e0f1403fc5a.


Day #79

‹prev | My Chain | next›

Sharing Implementors is Easy in the Bridge Pattern

Reference counting is something of a lost art. I, for one, hope it stays that way. If there was a way to mess up counting, I was more than up to the task of finding it. That's only a slight exaggeration.

So I very much appreciate garbage collected languages like Dart. Of course, garbage collection can only do so much—I promise you that it is still possible to build web applications that consume insane amounts of memory. In that vein, tonight I investigate sharing implementors in the bridge pattern.

The Gang of Four book describes Handle Body idiom for tackling this in C++. But that's for my old nemesis reference counting. In Dart, I have to think factory constructor singletons would be an easy way to tackle this. For example, consider the wildly memory intensive DrawingApi1 class:

class DrawingApi1 implements DrawingApi {
  void drawCircle(double x, double y, double radius) {
    print(
      "[DrawingApi1] "
      "circle at ($x, $y) with "
      "radius ${radius.toStringAsFixed(3)}"
    );
  }
}

Clearly, I do not want that class to instantiate new objects each time a Circle refined abstraction is created:

  List<Shape> shapes = [
    new Circle(1.0, 2.0, 3.0, new DrawingApi1()),
    new Circle(0.0, 6.0, 1.0, new DrawingApi1()),
    new Circle(2.0, 2.0, 1.5, new DrawingApi1()),
    new Circle(5.0, 7.0, 11.0, new DrawingApi2()),
    new Circle(1.0, 2.0, 3.0, new DrawingApi1()),
    new Circle(5.0, -7.0, 1.0, new DrawingApi2()),
    new Circle(-1.0, -2.0, 5.0, new DrawingApi1())
  ];

Even if DrawingApi2 is significantly more lightweight than DrawingApi1, enough of the latter will drag the browser / system to a halt. But a simple singleton factory constructor solves that neatly:

class DrawingApi1 implements DrawingApi {
  static final DrawingApi1 _drawingApi = new DrawingApi1._internal();
  factory DrawingApi1()=> _drawingApi;
  DrawingApi1._internal();

  void drawCircle(double x, double y, double radius) { /* ... */ }
}

The class variable _drawingApi is constructed once from a private constructor. The regular DrawingApi1() is a factory constructor that only returns that one _drawingApi reference. And the internal constructor is a simple, no-argument private constructor.

The only case that does not cover is when the number of references to a DrawingApi1 instance goes to zero. The start-at-zero case is handled automatically for me by Dart. The private _drawingApi class variable is not assigned until the constructor is invoked for the first time—that is just thanks to Dart's lazy instantiation. So no memory will be used unless and until the first DrawingApi1 shape is drawn.

If I really needed to reclaim memory, I might try a handle-body kind of thing. But I'd probably get it wrong. So instead I use mirrors (because mirrors are always easier than reference counting). If I switch to constructing shapes with the class name instead of an instance, the individual shapes might look like:

  List<Shape> shapes = [
    new Circle(1.0, 2.0, 3.0, DrawingApi1),
    new Circle(0.0, 6.0, 1.0, DrawingApi1),
    new Circle(2.0, 2.0, 1.5, DrawingApi1),
    new Circle(5.0, 7.0, 11.0, DrawingApi2),
    new Circle(1.0, 2.0, 3.0, DrawingApi1),
    new Circle(5.0, -7.0, 1.0, DrawingApi2),
    new Circle(-1.0, -2.0, 5.0, DrawingApi1)
  ];

The Circle constructor still redirects the last parameter, which is now a Type, to the abstraction superclass:

class Circle extends Shape {
  double _x, _y, _radius;
  Circle(this._x, this._y, this._radius, Type drawingApi) :
    super(drawingApi);
  // ...
}

Finally, the constructor in the Shape abstraction can putIfAbsent() on the cache:

import 'dart:mirrors' show reflectClass;
abstract class Shape {
  DrawingApi _drawingApi;
  static Map _drawingApiCache = {};

  Shape(Type drawingApi) {
    _drawingApi = _drawingApiCache.putIfAbsent(
      drawingApi,
      ()=> reflectClass(drawingApi).newInstance(new Symbol(''), []).reflectee
    );
  }
  // ...
}

If I want to clear that cache after all Shape instances have been removed, I can use a simple clear():

abstract class Shape {
  // ...
  void reset() { _drawingApiCache.clear(); }
  // ...
}

The rest remains unchanged from previous nights. The bridge between abstraction (shape) and implementor (a drawing API) is used in the draw() method in the refined abstraction:

class Circle extends Shape {
  // ...
  void draw() {
    _drawingApi.drawCircle(_x, _y, _radius);
  }
  // ...
}

I draw two conclusions from this. First, I enjoy mirrors far more than is healthy. A handle-body class would have involved counting, but might have solved the last reference removal just as well (and possibly clearer). Second, singletons seem to solve the reference count for nearly all use-cases.


Play with the code on DartPad: https://dartpad.dartlang.org/befac6b199a2cebf1d76.

Day #78

‹prev | My Chain | next›

Bridge Mixins

Today I take a look at the bridge pattern with Dart mixins. The Gang of Four book includes a brief discussion on multiple inheritance and the bridge pattern. This has me curious about mixins, which can serve a similar purpose to multiple inheritance.

I continue to work with the shape drawing example from Wikipedia. In it, a Shape is the the abstraction in need of bridging to an implementation—drawing in this case. The abstract Shape class requires a drawing API object be supplied when constructing a concrete implementation, along with two methods that must be defined by that same subclass:

abstract class Shape {
  DrawingApi _drawingApi;

  Shape(this._drawingApi);

  void draw();                         // low-level
  void resizeByPercentage(double pct); // high-level
}

In a "refined abstraction," the low-level draw() is the method that needs the bridge to the implementor. For a Circle, the draw() method might invoke a drawCircle() method on a concrete drawing API object:

// Refined Abstraction
class Circle extends Shape {
  double _x, _y, _radius;
  Circle(this._x, this._y, this._radius, DrawingApi api) :
    super(api);

  // low-level i.e. Implementation specific
  void draw() {
    _drawingApi.drawCircle(_x, _y, _radius);
  }
  // ...
}

The client then create a concrete DrawingApi object (like DrawingApi1) to supply to Circle's constructor:

    new Circle(1.0, 2.0, 3.0, new DrawingApi1())
      ..draw();

That works great and is a nice example of a bridge pattern. But it is a hassle to have to construct a concrete DrawingApi class every time I construct a Circle. What's to prevent me from using DrawingApi1 (or DrawingApi2) as a mixin? The answer is nothing!

Since the abstraction no longer needs to track the implementor, it can be simplified to an interface requiring two methods:

abstract class Shape {
  void draw();                         
  void resizeByPercentage(double pct);
}

Then I mixin DrawingApi1 to Circle by extending Shape with DrawingApi1:

class Circle extends Shape with DrawingApi1 {
  double _x, _y, _radius;
  Circle(this._x, this._y, this._radius);
  void draw() { /* ... */  }
  void resizeByPercentage(double pct) { /* ... */ }
}

With access to the methods of DrawingApi1, I can now call drawCircle() directly from draw():

class Circle extends Shape with DrawingApi1 {
  // ...
  void draw() {
    drawCircle(_x, _y, _radius);
  }
  // ...
}

That in turn simplifies my client code since it longer needs to worry about creating the drawing API object:

    new Circle(1.0, 2.0, 3.0)
      ..draw();

When this code is, just as in the prior implementation, it produces the following output:

$ ./bin/draw.dart           
[DrawingApi1] circle at (1.0, 2.0) with radius 3.000

So it is possible to use mixins to implement the bridge pattern in Dart… except not quite.

This will work for the degenerate case explored last night in which there is only one concrete drawing implementor. Both the implementor and abstraction can vary independently, which is ultimately the goal of the pattern.

What does not work is the same thing that the Gang of Four mentions as a shortcoming of the multiple inheritance approach in C++. The binding between the abstraction and implementor are now permanent. If I needed to vary the implementation at runtime, I am out of luck. Even mirrors will not help—at least not until the mixin property of ClassMirror is read-write.

In the end, mixins in the bridge pattern are a fun experiment. They may even be a useful approach to use in degenerate, single implementor implementations. For a full featured bridge pattern, mixins will not serve as a legitimate solution.

Play with the code on DartPad: https://dartpad.dartlang.org/b0050955ee95746956da.


Day #77

‹prev | My Chain | next›

Degenerate Bridges

I enjoyed last night's example implementation of the bridge pattern, though it feels unfamiliar. The Gang of Four book mentions a degenerative case—that sounds right up my alley!

In last night's example, the "refined abstraction" in the pattern was a Circle (Shape being the abstraction). In addition to supporting position and size arguments, the constructor also accepted an instance of an implementation. The example uses drawing circles on the screen as the implementation being supported:

class Circle extends Shape {
  double _x, _y, _radius;
  Circle(this._x, this._y, this._radius, DrawingApi api) :
    super(api);
  // ...
}

The draw() method of Circle then delegates responsibility to the drawing API (it bridge the abstraction and implementation):

class Circle extends Shape {
  // ...
  void draw() {
    _drawingApi.drawCircle(_x, _y, _radius);
  }
  // ...
}

The degenerate case does not support multiple implementations. Last night's approach accepted a DrawingApi instance so that multiple types of DrawingApi objects could be used (e.g. one for the console, one for the browser, etc.). But if there is only one concrete implementor, then the abstraction itself can create that implementor:

abstract class Shape {
  DrawingApi1 _drawingApi = new DrawingApi1();

  void draw();                         
}

In this case, the Circle refined abstraction does not have to worry about creating or handling the DrawingApi, it can just do circle things:

class Circle extends Shape {
  double _x, _y, _radius;
  Circle(this._x, this._y, this._radius);

  void draw() {
    _drawingApi.drawCircle(_x, _y, _radius);
  }
}

The draw() method still works through the DrawingApi1 implementor, the only difference here is that the _drawingApi instance is created in the Shape abstraction class.

Since there is only one implementor, there is no need for an interface. The abstraction depends directly on the concrete DrawingApi1 implementor, which remains unchanged from yesterday's print-to-stdout barebones example:

class DrawingApi1 {
  void drawCircle(double x, double y, double radius) {
    print(
      "[DrawingApi] "
      "circle at ($x, $y) with "
      "radius ${radius.toStringAsFixed(3)}"
    );
  }
}

Client code can then create and draw a circle with something like:

    new Circle(1.0, 2.0, 3.0)
      ..draw();

That results in the desired, bridged output:

$ ./bin/draw.dart           
[DrawingApi] circle at (1.0, 2.0) with radius 3.075

The question is why would I want to do something like this instead of putting drawing code directly inside Circle's draw() method?

The Gang of Four suggest that a change in the drawing implementation should not force client code to recompile. Dart compilation does not work that way—any change anywhere necessitates that everything get recompiled. I would think the intent behind the Gang of Four's assertion was the single responsibility principle and that the point is still valid in Dart. Per the SRP, a class should only have one reason to change. If the drawing code existed directly inside the draw() method, then Circle would change whenever new features are added to describe a circle and whenever the manner in which drawing occurs changes.

I still do not recall ever having used even this simple case. That will mean a challenge coming up with a more real-world example for either this or the regular case. Still, it does seem worth noodling through.

Play with the code on DartPad: https://dartpad.dartlang.org/0ca4f1ac6ee8caad731e.

Day #76

‹prev | My Chain | next›

The Bridge Pattern in Dart

The bridge pattern definition sounds like little more than a jargon generator seeded with object-oriented terms. From the Gang of Four book, the intent is to:

Decouple an abstraction from its implementation so that the two can vary independently.

Some day I hope to be able to reduce computer science-y terms with such whimsy. Until then, I'll settle for attempting to implement the pattern in Dart.

For my first pass, I borrow the Java implementation from the Wikipedia article. It is a nice example in which the abstraction is a shape and the implementation is a drawing API. Part of the abstraction's job is to maintain a reference to the implementation, so I start with the latter.

The implementor is DrawingApi:

abstract class DrawingApi {
  void drawCircle(double x, double y, double radius);
}

Obviously, what will vary between concrete implementors is that drawCircle() method. In this very simple string-based example, the only thing that changes is the first part of the string printed by drawCircle():

class DrawingApi1 implements DrawingApi {
  void drawCircle(double x, double y, double radius) {
    print(
      "[DrawingApi1] "
      "circle at ($x, $y) with "
      "radius ${radius.toStringAsFixed(3)}"
    );
  }
}

class DrawingApi2 implements DrawingApi {
  void drawCircle(double x, double y, double radius) {
    print(
      "[DrawingApi2] "
      "circle at ($x, $y) with "
      "radius ${radius.toStringAsFixed(3)}"
    );
  }
}

With that out of the way, it is time to check out the abstraction. Again, the abstraction maintains a reference to an implementor. It also defines the public-facing interface:

abstract class Shape {
  DrawingApi _drawingApi;

  Shape(this._drawingApi);

  void draw();                         // low-level
  void resizeByPercentage(double pct); // high-level
}

What I appreciate about this example is that it identifies where changes will occur. Implementator changes are low-level changes such as variations in the DrawingApi. Abstraction variations are considered "high-level" such as resizing the shape.

The refined abstraction for Shape is a Circle. It needs to store properties for a circle and supply the implementor to the Shape superclass:

class Circle extends Shape {
  double _x, _y, _radius;
  Circle(this._x, this._y, this._radius, DrawingApi api) :
    super(api);
  // ...
}

The private instance variables are assigned with Dart's wonderful this constructor shorthand. I curse at any language that does not support this. The DrawingApi is assigned via a redirection to the superclass' constructor. That is nice & clean and could be a one-liner if I did not abhor long lines.

The low-level draw() method delegates to the supplied implementor:

class Circle extends Shape {
  // ...
  void draw() {
    _drawingApi.drawCircle(_x, _y, _radius);
  }
  // ...
}

As long as the implementor continues to support that DrawingApi interface, it can change as much as it likes. As for the high-level, abstraction specific resize method, it simply multiplies the radius by a percentage:

class Circle extends Shape {
  // ...
  void resizeByPercentage(double pct) {
    _radius *= (1.0 + pct/100.0);
  }
}

And that is the pattern. If I had to change the implementation details of the resize function, I could do so with no fear of breaking the low-level implementor. The same goes for the implementor—if I need to change how drawing works or add another type of implementor, I can do so without affecting the abstraction.

Client code can create a 2 shape list, each with a different drawing implementor. I can then loop over each to resize and draw:

main() {
  List shapes = [
    new Circle(1.0, 2.0, 3.0, new DrawingApi1()),
    new Circle(5.0, 7.0, 11.0, new DrawingApi2())
  ];

  shapes.forEach((shape){
    shape.resizeByPercentage(2.5);
    shape.draw();
  });
}

This results in:

$ ./bin/draw.dart           
[DrawingApi1] circle at (1.0, 2.0) with radius 3.075
[DrawingApi2] circle at (5.0, 7.0) with radius 11.275

Nice! There is still much to explore in this pattern, but that is a nice start.

Play with the code on DartPad: https://dartpad.dartlang.org/2b092185cb17ebebecef.


Day #75

‹prev | My Chain | next›

Is It a Real Proxy Pattern Without Types?

It turns out that I may be too rigid at times with my types in Dart. That's just insane. Me. An old Perler, an ancient Rubyist, and old-timey JavaScripter, someone who fled Java because of the type craziness — using types too darn often. What a world.

When I first explored protection proxy patterns I almost headed down the path of generic proxies, but decided against it because... types. The particular example that I was using to explore protection proxies probably influence me to a fair extent. I was using a Driver to determine if a particular driver instance was old enough to legally start a Car. I opted against a generic proxy class (probably rightly) since a proxy class protecting against drivers was certain to be an automobile of some kind. Following from there, if the proxy class always worked with automobiles, it might as well implement the Automobile interface.

That suited me just fine because it kept me on the happy Gang of Four path. All of my proxy pattern explorations followed the same patterns as in the original book: a subject (the interface), a real subject (e.g. a Car) and a proxy (e.g. RemoteCar). But in Gilad Bracha's The Dart Programming Language, it struck me reading that, not only was it OK to use a generic proxy, but that "being able to define transparent proxies for any sort of object is an important property."

So, I go back to my protection proxy example to see how it will work with a proxy that will work with any kind of object. In addition the object serving as the real subject of my protection proxy, I also need a driver instance through which access will be allowed or denied:

class ProxyProtect {
  final Driver _driver;
  final _realSubject;

  ProxyProtect(this._driver, this._realSubject);
  // ...
}

As a quick aside, I must point out that I really enjoy Gilad's book. It is wonderful getting insights into the language from one of the primary designers. The little notes about things like variables almost almost always being used in a final way are wonderful. I will make a concerted effort to use final in most of my real code. I likely won't use it teaching for the same reason that it is not the default in the language—it is not expected by most developers. Anyhow...

I have my ProxyProtext constructor, now I need the calls to the real subject. I continue to use noSuchMethod() for this:

import 'dart:mirrors' show reflect;

@proxy class ProxyProtect {
  // ...
  dynamic noSuchMethod(i) {
    if (_driver.age <= 16)
      throw new IllegalDriverException(_driver, "too young");

    return reflect(_realSubject).delegate(i);
  }
}

If no other methods are defined, then Dart will invoke noSuchMethod() with information about the method being invoked. With that, no matter what method is invoked, I first check the driver. If the driver is too young, an exception is thrown and nothing else occurs. The real subject is protected against illegal actions. If the driver is of age, then it is time for mirrors—the kind that allow dynamic calls and inspection. In this case, I get a mirror of the real subject with reflect(), then delegate whatever was invoked to the real subject with delegate().

Easy peasy. Now I have a ProxyProtect for any object that might have a driver: a car, an R/C toy, a train, as spaceship, etc. If I create a car and an of-age driver in client code, I can drive the car:

  var _car = new Car(),
      _driver = new Driver(25);
  print("* $_driver here:");

  var car = new ProxyProtect(_driver, _car);
  car.drive();

When run, this results in:

$ ./bin/drive.dart
* 25 year-old driver here:
Car has been driven!

If an underage drive attempts to pilot the vehicle:

  var _car = new Car(),
      _driver = new Driver(16);
  print("* $_driver here:");

  var car = new ProxyProtect(_driver, _car);
  car.drive();

Then this results in:

$ ./bin/drive.dart
* 16 year-old driver here:
Unhandled exception:
IllegalDriverException: 16 year-old driver is too young!

As I found out last night, I am not quite done here. When I run the code through the Dart static type analyzer, I find that my protection proxy does not seem to fit the correct types. Specifically, a drive() method is being invoked when one is not declared and the class does not explicitly specify an interface that it is implementing:

[hint] The method 'drive' is not defined for the class 'ProxyProtect' (/home/chris/repos/design-patterns-in-dart/proxy/bin/drive.dart, line 19, col 7)

To address this, I use the built-in @proxy annotation, which tells the analyzer to give my proxy class a pass:

@proxy class ProxyProtect {
  // ...
}

With that, I have a working protection proxy for any sort of object... and it passes static type analysis. Nothing too surprising here, though I do have figure out how and if to work this into the discussion of the pattern in Design Patterns in Dart. For now, I think I may be done with my exploration of the proxy pattern—it was a fun one! Play with the code on DartPad: https://dartpad.dartlang.org/6d8f76cab3f9d1bb97ff. Day #74

‹prev | My Chain | next›

A Closer Look at the Proxy Annotation in Dart

I don't think I used it once. I enjoyed exploring the proxy pattern in Dart. Trying to use isolates for simple remote proxies was probably ill-advised, but aside from that, my exploration went swimmingly. Except one thing that I was sure would happen never did.

Not once did I use the @proxy annotation for any of my proxy implementations. I am pretty sure that I understand what the @proxy annotation does, but "pretty sure" pretty much always translates into some mistake on my part. And since I never once had to use it when implementing a variety of proxy classes, there is a good chance that I have a knowledge gap.

I had always assumed that @proxy annotated a class indicating that the class supported methods even if not specifically declared. Since Dart is optionally typed, this would be a static type analysis warning, not a compile or runtime issue. But I specifically run all my code through dartanalyzer before using it, so how did I avoid it?

There would have been no need for the annotation with my websocket remote car implementation. All of the methods that were declared in the interface:

abstract class AsyncAuto {
  String get state;
  Future drive();
  Future stop();
}

Were explicitly declared in the remote proxy class:

class ProxyCar implements AsyncAuto {
  // ...
  String get state => _state;
  Future drive() => _send('drive');
  Future stop()  => _send('stop');
  // ...
}

But how did I manage to avoid @proxy with my noSuchMethod() / protection proxy class? In that example, I was still working with cars, but the subject of the pattern, the Automobile interface, only declared a single method:

abstract class Automobile {
  void drive();
}

The proxy class in this example does not explicitly declare the drive method even though it implements the Automobile interface:

class ProxyCar implements Automobile {
  Driver _driver;
  Car _car;

  ProxyCar(this._driver);

  Car get car => _car ??= new Car();

  dynamic noSuchMethod(i) {
    if (_driver.age <= 16)
      throw new IllegalDriverException(_driver, "too young");

    return reflect(car).delegate(i);
  }
}

Without explicitly declaring drive(), I need @proxy, right? Well.. no. When I run dartanalyzer against this library and some client code, I get no issues in either:

$ dartanalyzer bin/drive.dart lib/car.dart
Analyzing [bin/drive.dart, lib/car.dart]...
No issues found
No issues found

I also get no errors when using this DartPad, so this seems to be expected and / or desired behavior. So what is the point of @proxy then? As far as I can tell, it comes in handy when I lack a subject in the proxy pattern. That is, when you do not have an interface to implement, then warning will be issued. For example, if I remove the implements clause from the ProxyCar implementation, but leave the same noSuchMethod() implementation in place:

class ProxyCar {
  // ...
  dynamic noSuchMethod(i) {
    if (_driver.age <= 16)
      throw new IllegalDriverException(_driver, "too young");

    return reflect(car).delegate(i);
  }
}

Then my client code:

  // ...
  car = new ProxyCar(new Driver(25));
  car.drive();
  // ...

Generates warnings:

$ dartanalyzer bin/drive.dart lib/car.dart
Analyzing [bin/drive.dart, lib/car.dart]...
[hint] The method 'drive' is not defined for the class 'ProxyCar' (/home/chris/repos/design-patterns-in-dart/proxy/bin/drive.dart, line 11, col 7)
1 hint found.

In this situation, I can eliminate the warning with a @proxy annotation before the class:

@proxy
class ProxyCar {
  // ...
}

But, as long as I have an interface to implement and a noSuchMethod() method declared, @proxy is not necessary. In The Dart Programming Language, Gilad Bracha has a nice explanation of why one might want a proxy without a classic subject. I may take a closer look at that tomorrow. For now, I have a better understanding of @proxy and why it usually is not necessary.

Play with the non-annotated code on DartPad: https://dartpad.dartlang.org/3577ddd84876ebf310c4.

Day #73

‹prev | My Chain | next›

Program to Distant Interfaces

For the most part I am content to create Dart examples that run in the SDK. Command-line scripts feel lighter than their browser-based counterparts (and are certainly lighter than their JavaScript compiled counterparts). Plus, I can usually convert my scripts to run on DartPad. But I feel compelled to try my remote proxy pattern websocket implementation in the browser—not because I fear something going wrong. Rather, I am curious to explore coding to an interface in two different locations.

I create a simple web/index.html page to hold a remote proxy car instance. As UIs go, this barely qualifies as bare minimum:



Still, it should be sufficient to test things out.

Surprisingly (at least to me) things go amiss here. I had forgotten that the WebSocket class in the dart:html library differs from the one that I had been using in dart:io. The former conforms to the standard browser websocket interface where the latter is a standard Stream implementation.

Aside from the annoyance of two different interfaces for the same object, there are some practical differences for which I have to account. In the drive.dart script pulled into the web page via <script> tag, I have to add a Completer to await the websocket being ready for use:

import 'dart:async' show Completer;
import 'dart:html' show WebSocket, document, query;

import 'package:proxy_code/web_car.dart';

main() async {
  var socket = new WebSocket('ws://localhost:4040/ws');

  var _c = new Completer();
  socket.onOpen.listen((_){ _c.complete(); });
  await _c.future;

  // Create proxy car with send/receive streams
  ProxyCar car = new ProxyCar(socket);
  // ...
}

The web_car.dart file with the web remote proxy implementation also needs to change slightly, listening to the onMessage property instead of directly to the socket:

class ProxyCar implements AsyncAuto {
  // ...
  ProxyCar(this._socket) {
    _socket.onMessage.listen((e) {
      _state = e.data;
    });
  }
  // ...
}

But once those minor differences are sorted out, everything just works. Darn it.

I hook up the buttons in the page to event listeners in the Dart script:

  document.query('#drive').onClick.listen((_) async {
    print('Drive');
    await car.drive();
    updateState(car.state);
  });

Clicking the button tells the proxy car to drive, which then results in an update to the state from the websocket. The result of this is included in the <pre> tag below the buttons:



And, indeed, the web socket server from the other night is seeing these messages and passing them along to the real car:

$ ./bin/server.dart
[AsyncCar] received: stop
[AsyncCar] received: drive

In the sum total of things, that is a good thing. I was able to take my command-line remote proxy package and use it in the browser with only minor changes. I hadn't counted on those minor changes between websocket implementations. And I had expected that I would need to move the common interface out into a separate file that could be imported into both dart:io and dart:html libraries. That turned out not be necessary--thanks to Dart's beautiful libraries and creating the websockets in the client instead of the libraries.

Since libraries work so well in this case, I have no doubt that they will work when the common subject interface is pulled out into its own file. I do it anyway, creating interface.dart with:

library car;

import 'dart:async' show Future;

// Subject
abstract class AsyncAuto implements Automobile {
  String get state;
  Future drive();
  Future stop();
}

I then import that into both real_car.dart and web_car.dart:

library car;

import 'dart:async' show Future, Stream;
import 'dart:html' show WebSocket;

import 'interface.dart';

// Proxy Subject
class ProxyCar implements AsyncAuto {
  // ...
}

That makes the type analyzer happy and positions me well should I ever decide to create the specific websockets implementations in the dart:html and dart:io libraries. In other words, no matter how I decide I want to code those implementations, I have easy access to the interface to program against.


Day #72

‹prev | My Chain | next›

Full-Duplex Streams

I ask you, what kind of world do we live in where websockets are the easy answer?

Sure, my problems are my own and completely contrived, but still, websockets have proven to be the ideal medium to describe the remote proxy pattern. What makes them so nice is that I only have to supply a single socket to the proxy instance in order to enable it to control a real subject:

main() async {
  var socket = await WebSocket.connect('ws://localhost:4040/ws');
  ProxyCar car = new ProxyCar(socket);
  // ...
}

The reason that this works is that websockets are, under the covers, a full-duplex communication channel. That is, a single websocket supports messages going from the client to the server and from the server to the client.

Just as importantly, websockets send bi-directional messages rather than broadcast messages. Streams in Dart are either one-way or broadcast. I had previously attempted the remote proxy pattern with streams, but that required two streams, one for inbound and one for outbound:

main() async {
  var mainOut = new StreamController(),
      mainIn = new StreamController();
  ProxyCar car = new ProxyCar(mainOut, mainIn);
  // ...
}

It works and, if you think about the need for sending messages from the client to the server and vice versa, that approach makes sense. But if I am trying to describe this in a book like Design Patterns in Dart, I don't want readers to have to think about this—just the core concept being discussed.

And don't even get me started on communication via isolate workers. They are twice as conceptually complex due to the need to create communication channels over existing one-way channels.

And so, yes, I have created a world for myself in which websockets are the neat and clean answer. Armageddon must soon surely follow.

But seriously, I am not diametrically opposed to websockets for this case. They do make a certain amount of sense as a vehicle for remotely controlling cars or other objects. I had hoped to find another kind of stream in the standard Dart library that was full-duplex, but that would appear not possible.

Websockets in Dart are streams and they implement the Stream interface (for listening to messages) and the StreamSink interface (for sending messages). I had hoped that StreamSink might be implemented by another class that happened to be full-duplex. But it is only implemented by the StreamController that previously forced me into the undesirable two-stream-instances implementation.

But what if I try it with just a single stream instead?

main() async {
  var socket = new StreamController.broadcast();
  ProxyCar car = new ProxyCar(socket);
  // ...
}

The socket needs to be a broadcast stream so that both the proxy and real subject can listen to the same stream. Of course that is going to cause problems since ProxyCar will see messages from the real car and itself. So I need a way for ProxyCar to ignore its own messages.

I could use an enum here or some other lookup, but it turns out that I already have a convention in place. The ProxyCar class only sends commands to the real car. I am sending those as symbols instead of strings (because mirrors!):

class ProxyCar implements AsyncAuto {
  // ...
  Future drive() => _send(#drive);
  Future stop()  => _send(#stop);

  Future _send(message) {
    _socket.add(message);
    // ...
  }
}

So when ProxyCar listens for messages on the broadcast "socket," I can filter out any symbol messages with where():

class ProxyCar implements AsyncAuto {
  StreamController _socket;
  String _state = "???";

  ProxyCar(this._socket) {
    _socket.stream.where((m)=> m is! Symbol).listen((message) {
      print("[ProxyCar] $message");
      _state = message;
    });
  }
  // ...
}

Conversely, the real car, AsyncCar, only sends strings, so it can filter those out:

class AsyncCar implements AsyncAuto {
  StreamController _socket;
  Car _car;

  AsyncCar(this._socket) {
    _car = new Car();

    _socket.stream.where((m)=> m is! String).listen((message) {
      print("[AsyncCar] $message");
      if (message == #drive) _car.drive();
      if (message == #stop)  _car.stop();
      _socket.add(state);
    });
  }
  // ...
}

That works, and is nicer than creating two explicit instances. There is no need for mention of full-duplex communication should I include this in the book—I can merely mention that these classes need to ignore their own messages. The best part of this solution is that it works on DartPad:

https://dartpad.dartlang.org/aef966876bda192076c0

Still, crazy as it seems, this is not as nice as websockets which require no explanation other than "they send messages back and forth between client and server." So, unless I really need DartPad or another requirement presents itself, it looks like I love me some websockets.


Day #71

‹prev | My Chain | next›

Driving Cars with Websockets

Isolates look unlikely to serve as a teachable implementation for the remote proxy pattern in Dart. They are relatively simple, but still remain a tad too cumbersome. Last night's exploration of simple streams shows promise, begging the question of how another stream might work—websockets.

I borrow (OK, steal verbatim) the example websocket server from the Dart on the server example:

#!/usr/bin/env dart

import 'dart:async';
import 'dart:io';

handleMsg(msg) {
  print('Message received: $msg');
}

main() {
  runZoned(() async {
    var server = await HttpServer.bind('localhost', 4040);
    await for (var req in server) {
      if (req.uri.path == '/ws') {
        // Upgrade a HttpRequest to a WebSocket connection.
        var socket = await WebSocketTransformer.upgrade(req);
        socket.listen(handleMsg);
      };
    }
  },
  onError: (e) => print("An error occurred: $e"));
}

I will add my proxy pattern code shortly. For now, I just want to ensure that it works. I save this as bin/server.dart, chmod 755 and start it up with ./bin/server.dart. Nothing crashes, so I assume that I am good to go.

In my existing proxy pattern script, I add the appropriate websocket client code:

#!/usr/bin/env dart

import 'dart:async';
import 'dart:io';

main() async {
  var socket = await WebSocket.connect('ws://localhost:4040/ws');
  socket.add('Hello, World!');
  // ...
}

That should connect to my running websocket server and add a message to the websocket stream to which the server is currently listening. When I run this client script, I see the following message from the server:

$ ./bin/server.dart
Message received: Hello, World!

Nice! Web sockets were never all that hard in Dart, but they are getting close to trivial.

So what is it going to take to convert my ProxyCar from streams (which were converted last night from isolates) to websockets? Blood sacrifice? The answer is surprisingly little.

In my client code, I continue to open the websocket, pass that to a ProxyCar, then perform some remote car operations:

main() async {
  var socket = await WebSocket.connect('ws://localhost:4040/ws');

  ProxyCar car = new ProxyCar(socket);

  print("Attempting to drive remote car...");
  await car.drive();
  print("Car is ${car.state}");

  print("--");

  print("Attempting to stop remote car...");
  await car.stop();
  print("Car is ${await car.state}");
}

The ProxyCar is responsible for listening to this websocket for state responses from the real car. I establish that listener in the constructor:

class ProxyCar implements AsyncAuto {
  Stream _socket, _broadcast;
  String _state;

  ProxyCar(this._socket) {
    _broadcast = _socket.asBroadcastStream();
    _broadcast.listen((message) {
      _state = message;
    });
  }
  // ...
}

I get a broadcast version of the websocket so that I can listen to it in multiple locations. Here, I listen for state updates. When I send action messages to the real car, I also listen to the stream for confirmation that the message was received:

class ProxyCar implements AsyncAuto {
  Stream _socket, _broadcast;
  String _state;
  // ...
  String get state => _state;
  Future drive() => _send('drive');
  Future stop()  => _send('stop');

  Future _send(message) {
    _socket.add(message);
    return _broadcast.first;
  }
}

I may reconsider that at some point, just for ease of discussion. For now, I leave it as-is.

The server is using the same library. Instead of the ProxyCar instance, it works with the real subject in this pattern: an AsynCar instance:

      // ...
      if (req.uri.path == '/ws') {
        // Upgrade a HttpRequest to a WebSocket connection.
        var socket = await WebSocketTransformer.upgrade(req);
        new AsyncCar(socket);
      };
      // ...

Like the ProxyCar, the AsyncCar implements the AsyncAuto interface:

// Subject
abstract class AsyncAuto implements Automobile {
  String get state;
  Future drive();
  Future stop();
}

If anything, the AsyncCar real subject is even simpler than the proxy:

class AsyncCar implements AsyncAuto {
  Stream _socket;
  Car _car;

  AsyncCar(this._socket) {
    _car = new Car();

    _socket.listen((message) {
      print("[AsyncCar] received: $message");
      if (message == 'drive') _car.drive();
      if (message == 'stop')  _car.stop();
      _socket.add(state);
    });
  }

  String get state => _car.state;
  Future drive() => new Future((){ _car.drive(); });
  Future stop()  => new Future((){ _car.stop(); });
}

It adapts a synchronous Car, which it manipulates in response to messages that it receives from the socket. If the websocket message is 'drive', then the car instance is sent the drive message. If the websocket see 'stop', stop() is invoked on car.

And that actually works. Running the client code results in:

$ ./bin/drive.dart
Attempting to drive remote car...
Car is driving
--
Attempting to stop remote car...
Car is idle

Checking the server output, I see:

$ ./bin/server.dart
[AsyncCar] received: drive
[AsyncCar] received: stop

So there you have it. I can drive a car over websockets with Dart. And it was pretty darn easy!


Day #70

‹prev | My Chain | next›

Faking Dart Isolates for Proxy Pattern Profits

Perhaps the best answer is "not."

I have been struggling with how best to present isolates (isolated workers) as a remote proxy pattern vehicle. As of last night, I think I have the bare minimum of what I can do in my Dart code. It's good—functional, well named, proper—but still complex enough that it would distract from the main discussion.

So what if I get rid of isolates altogether? Well, for one thing, I likely would not really need a remote proxy pattern implementation. The main function could speak directly to the worker function without required go-betweens like send and receive ports. For the sake of argument and illustration, let's stipulate that there is a requirement for main and worker functions to speak only over streams.

I start by replacing the isolate / send-port / receive-post dance with two stream controllers in main()—one for sending messages to the worker function, the other for receiving messages from the worker:

main() async {
  var mainOut = new StreamController.broadcast(),
      mainIn = new StreamController.broadcast();
  // ...
}

Next, I create a remote ProxyCar instance, supplying these two stream controllers for communication with the real subject (which will reside in the worker() function):

main() async {
  var mainOut = new StreamController.broadcast(),
      mainIn = new StreamController.broadcast();

  // Create proxy car with send/receive streams
  ProxyCar car = new ProxyCar(mainOut, mainIn);
  // ...
}

This requires two minor changes to the ProxyCar declaration, neither of which should really affect ease of understanding. First, the _in and _out instance variables become StreamControllers instead of ReceivePort and SendPort. Second, I need to listen on the StreamController's stream instead of directly on the StreamController object:

class AsyncCar implements AsyncAuto {
  StreamController _out, _in;

  AsyncCar(this._out, this._in) {
    _in.stream.listen((message) {
      print("[AsyncCar] $message");
      if (message == #drive) _car.drive();
      if (message == #stop)  _car.stop();
      _out.add(state);
    });
  }
  // Proxied methods remain unchanged...
}

Back in main(), I also sent the mainOut and mainIn stream controllers to the worker:

  // Start "worker"
  worker(mainIn, mainOut);

Inside the worker() function, these two arguments are mirrors of the arguments in main()—mainIn in main() is workerOut inside worker():

worker(StreamController workerOut, StreamController workerIn) {
  new AsyncCar(workerOut, workerIn);
}

The AsyncCar class requires the same minor StreamController changes that I made to ProxyCar, but the actual functionality remains unchanged from the isolate version of the code.

And that does the trick. Back in main(), I can invoke the usual vehicle methods on the ProxyCar and those requests are forwarded onto the real AsyncCar in worker():

main() async {
  var mainOut = new StreamController.broadcast(),
      mainIn = new StreamController.broadcast();

  ProxyCar car = new ProxyCar(mainOut, mainIn);
  worker(mainIn, mainOut);

  await car.drive();
  print("Car is ${car.state}");

  print("--");

  await car.stop();
  print("Car is ${await car.state}");
}

Along with some debugging code inside the car classes, this code produces the following output:

$ ./bin/drive.dart                          
[AsyncCar] Symbol("drive")
[ProxyCar] driving
Car is driving
--
[AsyncCar] Symbol("stop")
[ProxyCar] idle
Car is idle

I like that. The example is certainly contrived, but experienced Dartisans will recognize where this can go while folks new to the language should not be completely lost. Once the main discussion is done, I would then be free to show a quick code transformation into an isolate—or even a web socket—solution.

And best of all is that this approach can be seen on DartPad: https://dartpad.dartlang.org/7cc9f080e49939ac4cad.


Day #69

‹prev | My Chain | next›

A Naming Convention for Dart Isolate Ports

I still can't isolate. Well, I can create isolate workers in Dart, but they feel incredibly awkward to use to support programming discussions. I may give up on them, but I'd like at least one more shot at them.

On the face of it, communication between the main entry point and a worker is fairly simple:



Main sends messages from its send-port to the receive-port in the worker. The worker uses its own send-port to send messages to the receive-port back in main. Simple, right? Yes and no.

From the above diagram, you might think that main's receive-port is created last:

1. first you need a send-port to send to the worker
2. second, the worker needs a receive port to listen for those messages
3. third, the worker needs a send-port to send back to main
4. last, main needs the receive port to listen for messages from worker

In reality, Dart receive-ports are created first. A send-port is just a property of the receive-port. As a property of a receive-port, the send-port is already linked for communication, the challenge is then to get main's receive-port send-port to the worker and vice-versa.

Side-note: sentences like the last one are probably why I will not be able to use isolates in discussions like remote proxy patterns. It makes sense if you noodle it through, but readers should expend cognitive load on the main discussion, not the apparatus for the discussion. Anyway, onward...

To create an isolate worker, the main entry point first creates its receive-port (with associated send-port). It then spawns the worker sending along the associated send-port at the same time:



At this point, the worker can send all the messages it likes back to the main worker, but main has no way to communicate back to worker. In many cases this is just fine. In many of the examples that I want to use, however, this is insufficient. To allow main to communicate with worker, worker has to create its own receive-port and supply the associated send-port back to main. There is only one way to do so—back through main's send-port:



All of this makes perfect sense. I understand the tradeoffs involved. I understand how to set it up. I cannot think of better names than "ports" for these beasties. But the end result is that I have to send a send-port over a send-port in order to establish worker's receive-port. And all I really want is to discuss the proxy pattern, darn it.

I am unsure how to proceed at this point. It seems like a higher level library is in order, but then I have a library just for teaching purposes. Maybe that is what I will wind up doing in the end. First though, I am going to experiment with a worker-centric naming convention to see if it helps the actual code.

So, in worker, I will refer to the send-port (which comes from main) as "worker-out." Back in main, that same send-port will be associated with "main-in":



To make that happen, I start in main() by creating my mainIn receive-port, then sending its sendPort to worker() when it is spawned:

main() async {
  var mainIn = new ReceivePort();
  await Isolate.spawn(worker, mainIn.sendPort);
  // ...
}

(I am using the async / await syntactic sugar for Dart futures here)

So far, so good. I have a good handle on what mainIn is. Previously, I had called that receivePort or just r—by the time I was looking inside worker, I was easily confused. Hopefully this naming convention will serve me better.

Then, down in the worker() that is being spawned, I accept main's mainIn.sendPort, assigning it locally as workerOut:

worker(SendPort workerOut) {
  // ...
}

At the risk of being redundant, from main's perspective, this is mainIn.sendPort. From worker's perspective, that same thing is workerOut. I think that works.

Now I need a workerIn, which is a receive-port and I need to send it back to main:

worker(SendPort workerOut) {
  var workerIn = new ReceivePort();
  workerOut.send(workerIn.sendPort);
  // ...
}

Lastly, back in main, I need to accept that first message and assign it as mainOut. I cannot just ask mainIn for the first message because that has the side-effect of closing the stream and all of this bi-directional communication setup would be for naught. Instead, I convert mainIn from a receive-port to a broadcast stream using the asBroadcastStream() method:

main() async {
  var mainIn = new ReceivePort();
  await Isolate.spawn(worker, mainIn.sendPort);

  var inStream = mainIn.asBroadcastStream();
  SendPort mainOut = await inStream.first;
  // ...
}

With that, I can still listen to inStream for additional communication—even after I have mainOut. Conceptually, this winds up looking something like:



I think I am OK with that. Renaming the ports after the context seems to help clear up most of my confusion. I will likely adopt this approach in future isolate code. That said, I remain unconvinced that this is clear enough for something like Design Patterns in Dart. I may try my hand at a high-level, simple library. I believe that I have already searched for one, but I may also check to see if any existing libraries might suit my needs.

Grist for tomorrow...


Day #68

‹prev | My Chain | next›

Proxies Don't Always Need to Know Subject Type

Up today, I explore types when implementing the proxy pattern in Dart. The Gang of Four book states that proxies do not necessarily need to know the type of the real subject. This seems reasonable to me, but I prefer to at least run the theory through somewhat practical application to see if I am overlooking something.

For the proxy class to not know the type of its real subject, the real subject must be created outside of the proxy and then supplied to the constructor. For the car example that I had been using previously, the client code for this might look something like:

  Automobile realCar =  new Car();
  Automobile proxy = new ProxyAutomobile(realCar);
  proxy.drive();

The proxy class does not need to know the specific class, but it needs to have an interface that is being implemented—the proxy class needs to know that the interface supports a common set of actions.

The subject in this pattern remains the Automobile interface, which declares that all implementations must support the drive() method:

// Subject
abstract class Automobile {
  void drive();
}

Next, I declare three different real subjects that will be used by the proxy class:

// Real Subjects
class Car implements Automobile {
  void drive() {
    print("Car has been driven!");
  }
}

class Truck implements Automobile {
  void drive() {
    print("Truck has been driven!");
  }
}

class Motorcycle implements Automobile {
  void drive() {
    print("Motorcycle has been driven!");
  }
}

The proxy class is still a protection proxy from the other night, so it requires both a type of Automobile and a Driver when constructed:

// Proxy Subject
class ProxyAutomobile implements Automobile {
  Driver _driver;
  Automobile _auto;

  ProxyAutomobile(this._auto, this._driver);
  // ...
}

As for the drive() method itself, it needs to first verify that the driver is legal, then will invoke the drive() method on the real subject:

class ProxyAutomobile implements Automobile {
  // ...
  void drive() {
    if (_driver.age <= 16)
      throw new IllegalDriverException(_driver, "too young");

    _auto.drive();
  }
}

And that works exactly as expected. A driver that is of age can drive any of these automobiles through the proxy class:

  // Proxy will allow access to real subject
  driver = new Driver(25);
  print("== $driver here:");
  new ProxyAutomobile(new Car(),        driver)..drive();
  new ProxyAutomobile(new Truck(),      driver)..drive();
  new ProxyAutomobile(new Motorcycle(), driver)..drive();

The output of that code confirms that the 25 year-old driver can driver each of these:

$ ./bin/drive.dart
== 25 year-old driver here:
Car has been driven!
Truck has been driven!
Motorcycle has been driven!

And a 16 year-old driver results in an illegal driver exception:

  driver = new Driver(16);
  print("== $driver here:");
  new ProxyAutomobile(new Car(), new Driver(16))..drive();
  // => == 16 year-old driver here:
  //    Unhandled exception:
  //    IllegalDriverException: 16 year-old driver is too young!

I mentioned earlier that when the proxy does not know the real subject's type ahead of time, then client code needs to supply the real subject. That is not strictly necessary because... mirrors! Instead of supplying the real subject, the client code can supply the type, or even a symbol representation of the type:

  new ProxyAutomobile(#Car,        driver)..drive();
  new ProxyAutomobile(#Truck,      driver)..drive();
  new ProxyAutomobile(#Motorcycle, driver)..drive();

The proxy class can then use this to create a real subject:

class ProxyAutomobile implements Automobile {
  Driver _driver;
  Symbol _autoType;

  ProxyAutomobile(this._autoType, this._driver);

  Automobile get auto => _autoMirror.reflectee;

  InstanceMirror get _autoMirror =>
    _classMirror.newInstance(new Symbol(''), []);

  ClassMirror get _classMirror =>
    currentMirrorSystem().
      findLibrary(#car).
      declarations[_autoType];

  void drive() {
    if (_driver.age <= 16)
      throw new IllegalDriverException(_driver, "too young");

    auto.drive();
  }
}

Sure that's some gnarly ClassMirror → InstanceMirrror → reflectee code, but it is possible. And some of us really enjoy mirrors for some reason.

I am more or less done with the proxy pattern in Dart now. I may have another go at remote proxies because I was never quite satisfied with my previous efforts. The Gang of Four book also mentions smart references as a possible application of the pattern. I am hard pressed to come up with an illustrative example in a garbage collected language. Regardless, the proxy pattern with unknown types works well.

Play with the (pre-mirror) code on DartPad: https://dartpad.dartlang.org/6a163b3c6708564bb13b.

Day #67

‹prev | My Chain | next›

A Real Virtual Proxy Pattern

Up today, I would like to make my virtual proxy pattern in Dart a little more tangible. Concrete if you will.

Yesterday's example copied shamelessly from the image loading example on the Wikipedia page. Today, I modify it so that, instead of placeholder print() statements, I load actual images on to a page. The context of the image loading proxy pattern is an image gallery. Now, image galleries are the simplest things in the world. Until they aren't.

Consider a personal image collection of 10,000 photos. When the page first loads, it makes sense to load the most recent 100 or so images for display. This is a nice balance between immediate feedback and swamping bandwidth and browser resources. Problems occur if the user immediately scrolls back a few years. The gallery should stop loading those initial images and get to work on the first 100 from a few years back. But if the user missed the date by a month or two, then those images should stop loading and the next batch should start. It turns out to be an interesting challenge, and one that the proxy pattern can help address.

For this exercise, I look at individual images in the gallery. When the image first comes into view, it should display a blank image. After a brief pause (to allow other resources to stop and to ensure the user didn't start scrolling again), the image should load a low resolution version of itself. Lastly, it should load a high resolution version of the photo.

Since there are going to be delays and waiting for loading, I changes the Image interface to return a future when displaying the image:

abstract class Image {
  Future displayImage();
}

The RealImage, which will be the real subject in the pattern, remains relatively unchanged from last night. It is constructed with a filename and then loads that image. Instead of last night's placeholder print() statement, tonight I construct an HTML image element:

class RealImage implements Image {
  String _filename;
 ImageElement img;
  
  RealImage(this._filename) {
    _loadImage();
  }

  void _loadImage() {
    print("Loading    $_filename");
    img = new ImageElement(src: _filename, width: 800, height: 446);
    img.style.border = '1px dashed grey';
    document.body.append(img);
  }
  // ...
}

As for diplayImage(), I still leave this a little rough for ease of illustration. It allows for the _filename to have been changed, updating the ImageElement's src attribute as a means of displaying the image:

lass RealImage implements Image {
  // ...
  Future displayImage() {
    print("Displaying $_filename");
    img.src = _filename;
    return new Future.value();   
  }
}

Were I doing this for real, I would get the Future from a Completer that completes when the image loads. But this will do for now.

Now for the ProxyImage class. I would like to construct this with three filenames / URLs: the tiny version of the image, the low resolution version of the image, and the high resolution of the image. To load the UML diagrams of the proxy pattern from the Wikipedia page, for instance, the ProxyImage creation might look like:

  Image image = new ProxyImage(
    'https://upload.wikimedia.org/wikipedia/commons/5/52/Spacer.gif',
    'https://upload.wikimedia.org/wikipedia/commons/thumb/7/75/Proxy_pattern_diagram.svg/320px-Proxy_pattern_diagram.svg.png',
    'https://upload.wikimedia.org/wikipedia/commons/thumb/7/75/Proxy_pattern_diagram.svg/1280px-Proxy_pattern_diagram.svg.png'
  );

To support that, I define three instance variables and require them in the constructor:

class ProxyImage implements Image {
  RealImage _image;
  String _tiny, _lo, _hi;

  ProxyImage(this._tiny, this._lo, this._hi);
  // ...
}

To put a little delay in between loading the different resolutions, I define a simple _pause() helper method:

class ProxyImage implements Image {
  // ...
  Future _pause(int s) {
    var c = new Completer();
    new Timer(new Duration(seconds: s), c.complete);
    return c.future;
  }
}

Given a number, this method returns a future that completes in that number of seconds. With that, I can declare the displayImage() method:

class ProxyImage implements Image {
  // ...
  Future displayImage() async {
    if (_image != null) return _image.displayImage();

    // Start with 1-byte blank image
    _image = new RealImage(_tiny)..displayImage();
    await _pause(1);
    
    // Load the low-res version
    _image
      .._filename = _lo
      ..displayImage();
    await _pause(5);
    
    // Then the hi-res version
    _image
      .._filename = _hi
      ..displayImage();
    return new Future.value();
  }
  // ...
}

Since this is the proxy pattern, this proxy class forwards the proxy method displayImage() to the real subject. In this example, it does so three times for the tiny, low resolution, and high-resolution versions of the image.

I again use the async / await syntax to clean up my Future code here. And clean up it does. After loading the first, tiny image, I await a pause of one second. Then, after loading the second, low resolution image, I await a pause of five seconds. Once that pause is done, the high resolution version of the real image is loaded. Again, I might return a future that completes when the image is loaded, but keep it simple by returning a Future that completes immediately.

And that does the trick. The full, working version of the code is available on DartPad: https://dartpad.dartlang.org/851fe3543e94ec4bb5c0.

When the code is first run, a blank image is displayed. A second later, the low resolution version of the proxy pattern UML diagram displays. Then, 5 seconds after that, the full version displays. If this were part of an image gallery, the ProxyImage instances could be staggered to load at slightly different times from each other. The timers that pause the next higher resolution version of the image could be canceled if the user scrolls the image out of the viewport. All in all, the proxy pattern seems a neat solution for many of the concerns introduced by image galleries.


Day #66

‹prev | My Chain | next›