C++ architecture and refactoring.

[Alan Conway <ac...@redhat.com>]

As part of the 0-9 work I want to do some refactoring to clarify the
architecture and separate concerns a little better. I think it's a good
opportunity to discuss architectural principles. Comments welcome! I'll
write up a wiki page when the ideas have settled.

= Qpid C++ Architecture = 

* network layer (qpid::sys::*): IO abstractions, network handling 

*framing layer (qpid::framing::*): encode/decode, generated from spec.

* adapter layer (client/broker::*HandlerImpl): Adapts framing APIs to
calls on core objects. Sends frames to peer via the Proxy.

* broker/client core (client/broker::*): Main functionality

This architecture is already implied by the code - you can see how the
namespaces & class names line up neatly with the layers. The bit that's
murky right now is the adapter/core distiction. Broker side
SessionHandlerImpl and it's inner classes do a bit of both. I plan to
pull the core broker functionality out into 3 main classes: Connection,
Channel and Broker. That will leave a set of light Handlers that just
do: 
 * simple argument manipulation
 * delegate to the core
 * make calls on ClientProxy.

In particular the handlers for per-channel classes need access to the
right Channel object so I'll change the signatures to take a Channel&
rather than a channel number. 

Apart from helping the 0-9 work I'm doing now I think this will help
prepare us for multi-version support. Basically I see us generating
separate framing classes for each version in the framing layer and
writing adapters for each version that delegate to the same core
classes. I think there may also be scope to partly
automate/codegen/templatize the adapter layer so we can keep the
hand-coding to a minimum. 

Cheers,
Alan.

Re: C++ architecture and refactoring.

[Alan Conway <ac...@redhat.com>]

On Tue, 2007-01-16 at 17:22 +0000, Gordon Sim wrote:
> Alan Conway wrote:
> > As part of the 0-9 work I want to do some refactoring to clarify the
> > architecture and separate concerns a little better. I think it's a good
> > opportunity to discuss architectural principles. Comments welcome! I'll
> > write up a wiki page when the ideas have settled.
> > 
> > = Qpid C++ Architecture = 
> > 
> > * network layer (qpid::sys::*): IO abstractions, network handling 
> > 
> > *framing layer (qpid::framing::*): encode/decode, generated from spec.
> > 
> > * adapter layer (client/broker::*HandlerImpl): Adapts framing APIs to
> > calls on core objects. Sends frames to peer via the Proxy.
> > 
> > * broker/client core (client/broker::*): Main functionality
> > 
> > This architecture is already implied by the code - you can see how the
> > namespaces & class names line up neatly with the layers. The bit that's
> > murky right now is the adapter/core distiction. Broker side
> > SessionHandlerImpl and it's inner classes do a bit of both. 
> 
> The adapter/core distinction sort of mirrors the version 
> dependent/independent distinction and that is by definition murky since 
> we cannot anticipate what will change to a great degree of detail.

Exactly. Adding a new version means adding a new adapter. Compatible
additions to the core (e.g. for new features in new versions) don't
affect existing adapters, incompatible core changes do require updating
all the adapters. The goal should be a stable core API that: 
- allows adapters to be simple
- grows with each version but
- rarely requires changes that force updates of previous version
adapters.

We won't get this right first time, but after one or two real version
changes we will have redistributed the adapter/broker responsibilities
into something that should be fairly stable going forward.

I'm doing some experiments now with boost's template and preprocessor
meta-programming libraries which I believe will result in less code in
the framing & adapter layers, which will also help keep things under
control.

> At present for example things like setting the default queue for a 
> channel are done in the adapters as this is not in my view core 
> behaviour and might well change between versions. Similarly sending of 
> particular error codes.

We will learn what really is "version specific" only when we have
another version so we'll probably refactor between the core and the
first couple of adapters. I feel the existing adapter still has too much
logic in some places, I'll be doing my best guess on the refactor :)

I think sending responses is always an adapter responsibility because
responses are part of the protocol version.

> Having said all that I do agree entirely with your architectural outline 
> and the renaming of SessionHandlerImpl to Connection. Much clearer.

Good, keep watching - more to come :)

Re: C++ architecture and refactoring.

[Gordon Sim <gs...@redhat.com>]

Alan Conway wrote:
> As part of the 0-9 work I want to do some refactoring to clarify the
> architecture and separate concerns a little better. I think it's a good
> opportunity to discuss architectural principles. Comments welcome! I'll
> write up a wiki page when the ideas have settled.
> 
> = Qpid C++ Architecture = 
> 
> * network layer (qpid::sys::*): IO abstractions, network handling 
> 
> *framing layer (qpid::framing::*): encode/decode, generated from spec.
> 
> * adapter layer (client/broker::*HandlerImpl): Adapts framing APIs to
> calls on core objects. Sends frames to peer via the Proxy.
> 
> * broker/client core (client/broker::*): Main functionality
> 
> This architecture is already implied by the code - you can see how the
> namespaces & class names line up neatly with the layers. The bit that's
> murky right now is the adapter/core distiction. Broker side
> SessionHandlerImpl and it's inner classes do a bit of both. 

The adapter/core distinction sort of mirrors the version 
dependent/independent distinction and that is by definition murky since 
we cannot anticipate what will change to a great degree of detail.

At present for example things like setting the default queue for a 
channel are done in the adapters as this is not in my view core 
behaviour and might well change between versions. Similarly sending of 
particular error codes.

Having said all that I do agree entirely with your architectural outline 
and the renaming of SessionHandlerImpl to Connection. Much clearer.