[c++] C++ API and boost.

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

We use boost heavily in the C++ implementation, the question arises
whether we use it in the public API. We do link with boost libraries so
we will require boost runtimes to be installed regardless.

There are 3 levels:
0 - No boost includes in public header files. We do not require boost
developer package (header files) to be installed.

1 - Private/implicit use of boost. We do require boost-devel headers
installed for Qpid developers but we don't require the user to know
anything about boost or even be aware we're using it.

2 - Public use of boost: we include boost types in the public API.

I've been convinced that 2 is bad as it ties us to boost for future
source-compatibility. We have some work to do to eliminate
boost::shared_ptr from the current API but I think it's reasonable and
all the client API needs can be met without it.

I can see the attraction of 0, but I don't think it's practical. The
Session API uses keyword arguments to great effect. This is at level 1 -
the user can type session.subscribe(queue="foo") without knowing that we
use boost to make it work. There is no way we can rewrite boost's
keyword argument stuff and without it Session is unusable as an API.
Given that, it makes no sense to re-invent the wheel for other
implementation details where boost provides a ready-made solution.

I'd vote for a public API that requires no explicit knowledge or
documentation of any boost classes or concepts, but that qpid headers
may #include boost headers for private or implicit implementation
details. 

Cheers,
Alan.

Re: Resent: [c++] C++ API and boost.

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

On Sun, 2007-10-28 at 22:41 -0400, Andrew Stitcher wrote:
> [Resent due to lossage]
> 
> I agree with most of Alan's thoughts, but see below.
> 
> Alan Conway wrote:
> > We use boost heavily in the C++ implementation, the question arises
> > whether we use it in the public API. We do link with boost libraries so
> > we will require boost runtimes to be installed regardless.
> >
> > There are 3 levels:
> > 0 - No boost includes in public header files. We do not require boost
> > developer package (header files) to be installed.
> >
> > 1 - Private/implicit use of boost. We do require boost-devel headers
> > installed for Qpid developers but we don't require the user to know
> > anything about boost or even be aware we're using it.
> >
> > 2 - Public use of boost: we include boost types in the public API.
> >
> > I've been convinced that 2 is bad as it ties us to boost for future
> > source-compatibility. We have some work to do to eliminate
> > boost::shared_ptr from the current API but I think it's reasonable and
> > all the client API needs can be met without it.
> >   
> Completely agree here, but I'm not convinced that there is so much
> difference. As the difference here is that you could in theory replace
> the boost implemented features with some other implementation, but you
> will still structurally depend on the boost headers.

The difference to me is whether or not we can change the impl in a
source-compatible way. In case 1) user would never have to #include
<boost/...> headers or refer to boost::... symbols in order to use Qpid,
so we could replace boost without breaking existing code. Another
difference is that in case 1 we never have to document the use of boost
types.

> > I can see the attraction of 0, but I don't think it's practical. The
> > Session API uses keyword arguments to great effect. 
[snip]
> >   
> I agree that keyword arguments are convenient, but I'd like there to be
> a version of the API that doesn't require them, ie I'd much prefer them
> to be a convenience layer over a simpler API that doesn't require boost.
> 
That's certainly possible. I have already been thinking of them as a
layer over the binary API that we maintain for binary compatibility, but
this could also serve as a "boost-free" user API.

> I hope that this makes sense - I've just got of a plane across the
> Atlantic so I may not be at my best!

It does indeed, we'll talk more when the jet lag wears off :)

Resent: [c++] C++ API and boost.

[Andrew Stitcher <as...@redhat.com>]

[Resent due to lossage]

I agree with most of Alan's thoughts, but see below.

Alan Conway wrote:
> We use boost heavily in the C++ implementation, the question arises
> whether we use it in the public API. We do link with boost libraries so
> we will require boost runtimes to be installed regardless.
>
> There are 3 levels:
> 0 - No boost includes in public header files. We do not require boost
> developer package (header files) to be installed.
>
> 1 - Private/implicit use of boost. We do require boost-devel headers
> installed for Qpid developers but we don't require the user to know
> anything about boost or even be aware we're using it.
>
> 2 - Public use of boost: we include boost types in the public API.
>
> I've been convinced that 2 is bad as it ties us to boost for future
> source-compatibility. We have some work to do to eliminate
> boost::shared_ptr from the current API but I think it's reasonable and
> all the client API needs can be met without it.
>   
Completely agree here, but I'm not convinced that there is so much
difference. As the difference here is that you could in theory replace
the boost implemented features with some other implementation, but you
will still structurally depend on the boost headers.
> I can see the attraction of 0, but I don't think it's practical. The
> Session API uses keyword arguments to great effect. This is at level 1 -
> the user can type session.subscribe(queue="foo") without knowing that we
> use boost to make it work. There is no way we can rewrite boost's
> keyword argument stuff and without it Session is unusable as an API.
> Given that, it makes no sense to re-invent the wheel for other
> implementation details where boost provides a ready-made solution.
>
> I'd vote for a public API that requires no explicit knowledge or
> documentation of any boost classes or concepts, but that qpid headers
> may #include boost headers for private or implicit implementation
> details. 
>
>   
I agree that keyword arguments are convenient, but I'd like there to be
a version of the API that doesn't require them, ie I'd much prefer them
to be a convenience layer over a simpler API that doesn't require boost.

I hope that this makes sense - I've just got of a plane across the
Atlantic so I may not be at my best!

Andrew

Re: [c++] C++ API and boost.

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

On Thu, 2007-10-25 at 21:21 -0400, Andrew Stitcher wrote:
> I agree with most of Alan's thoughts, but see below.
> 
> Alan Conway wrote:
> > We use boost heavily in the C++ implementation, the question arises
> > whether we use it in the public API. We do link with boost libraries so
> > we will require boost runtimes to be installed regardless.
> >
> > There are 3 levels:
> > 0 - No boost includes in public header files. We do not require boost
> > developer package (header files) to be installed.
> >
> > 1 - Private/implicit use of boost. We do require boost-devel headers
> > installed for Qpid developers but we don't require the user to know
> > anything about boost or even be aware we're using it.
> >
> > 2 - Public use of boost: we include boost types in the public API.
> >
> > I've been convinced that 2 is bad as it ties us to boost for future
> > source-compatibility. We have some work to do to eliminate
> > boost::shared_ptr from the current API but I think it's reasonable and
> > all the client API needs can be met without it.
> >   
> Completely agree here, but I'm not convinced that there is so much
> difference. As the difference here is that you could in theory

I guess that was interrupted - what were you going to say? 

As long as you'll let me use boost keywords for the client API I'm happy
to kick out shared_ptr - actually I don't like it anymore since I've
realized what a heap hog it is, I'd like to generally replace it with a
traditional RefCounted base class for internal purposes (although I
still like boost::intrusive_ptr as the smart pointer :) 

I will also buy the argument that we shouldn't use boost::variant as the
API for field table values, although I would argue we could profitably
use it as the *implementation* to reduce heap allocation. boost::any is
another candidate for that. I'd like to lose the clunky getFoo() API
field table API. 

What do you think of this as an API:

  class FieldValue {
    template <class T> bool is() const; // True if is of type T.
    template <class T> T& get() const; // throw BadTypeException if not T
    template <class T> void put(const T&);
    template <class T> operator=(const T& t) { put(t); }
    // I'll stop short of a template <class T> operator T() !!
  }; 

  typedef std::map<FieldValue> FieldTable;
  // Probably not an actual typedef but equivalent API.

We can use various techniques to make this type safe in the sense that
trying to instantiate FieldValue template methods with T that is not a
valid field table type will be a compile-time error. FieldValue could be
implemented with boost::variant, boost::any, qpid::framing::Blob or some
other discriminated-union approach.

Re: [c++] C++ API and boost.

[Andrew Stitcher <as...@redhat.com>]

I agree with most of Alan's thoughts, but see below.

Alan Conway wrote:
> We use boost heavily in the C++ implementation, the question arises
> whether we use it in the public API. We do link with boost libraries so
> we will require boost runtimes to be installed regardless.
>
> There are 3 levels:
> 0 - No boost includes in public header files. We do not require boost
> developer package (header files) to be installed.
>
> 1 - Private/implicit use of boost. We do require boost-devel headers
> installed for Qpid developers but we don't require the user to know
> anything about boost or even be aware we're using it.
>
> 2 - Public use of boost: we include boost types in the public API.
>
> I've been convinced that 2 is bad as it ties us to boost for future
> source-compatibility. We have some work to do to eliminate
> boost::shared_ptr from the current API but I think it's reasonable and
> all the client API needs can be met without it.
>   
Completely agree here, but I'm not convinced that there is so much
difference. As the difference here is that you could in theory
> I can see the attraction of 0, but I don't think it's practical. The
> Session API uses keyword arguments to great effect. This is at level 1 -
> the user can type session.subscribe(queue="foo") without knowing that we
> use boost to make it work. There is no way we can rewrite boost's
> keyword argument stuff and without it Session is unusable as an API.
> Given that, it makes no sense to re-invent the wheel for other
> implementation details where boost provides a ready-made solution.
>
> I'd vote for a public API that requires no explicit knowledge or
> documentation of any boost classes or concepts, but that qpid headers
> may #include boost headers for private or implicit implementation
> details. 
>
> Cheers,
> Alan.
>
>