On Tue, 2015-05-26 at 10:54 -0400, Chuck Rolke wrote:
> 
> ----- Original Message -----
> > From: "Alan Conway" <acon...@redhat.com>
> > To: proton@qpid.apache.org
> > Cc: "Darryl L. Pierce" <dpie...@redhat.com>, "Gordon Sim" <g...@redhat.com>
> > Sent: Monday, May 25, 2015 12:46:32 PM
> > Subject: New language bindings - when are they ready? [was Re: Ruby Engine 
> > APIs up for review]
> > 
> > On Thu, 2015-05-14 at 16:28 -0400, Darryl L. Pierce wrote:
> > > I've pushed these APIs up for public review on their own branch [1] in
> > > the Apache git repo. They're on a branch named ruby-engine-apis.
> > > 
> > > Please take a look, tinker and please provide feedback. :D
> > > 
> > > [1]
> > > http://git-wip-us.apache.org/repos/asf?p=qpid-proton.git;a=shortlog;h=refs/heads/ruby-engine-apis
> > 
> > We have a bunch of new bindings on branches (Go, Ruby, C++) When is a
> > binding ready for trunk?
> > 
> > I would propose the following as a basic critiera:
> > 
> > - Complete and tested for basic use.
> > - API documentation in language-normal form (godoc, rdoc, doxgygen)
> > - Core set of examples.
> > - Automated testing of all examples.
> > - Getting started README that explains how to run the examples.
> > 
> > I would suggest the following core examples for all bindings:
> > 
> > - send: connect to endpoint, send N messages.
> > - receive: connect to endpoint, receive N messages.
> > - broker: accept connections, in-memory queues created on demand.
> > - request_response: synchronous request-response client.
> > - echo_server: accept connections, echo message to reply-to address on
> > same connection.
> > 
> > This gives us a *small* set of examples that still has good coverage of
> > key scenarios (brokered and client-server) and can be used *without* any
> > external broker. This can be the common introduction to all our
> > bindings.
> > 
> > The python binding has all these, with different names. Rationale for
> > proposing the above names:
> > 
> > - The simplest send/receive examples should be called simply
> > "send"/"receive". Python has "simple_send"/"simple_receive" which seems
> > redundant.
> > - "request_response" is more descriptive than
> > "sync_client" ("sync_client" is a daft name, my bad)
> > - "echo_server" describes what the server does, just "server" is to
> > generic. The broker is also a server, and there may be other example
> > servers.
> > 
> > I can live with the python names if there's a consensus for that but now
> > might be a good time to rationalize. I do think the python examples
> > should be re-organized to start with these core examples. Right now the
> > python README requires you to start by installing an unspecified
> > "intermediary" which is going to cause confusion and frustration.
> > 
> > The very first README for every binding should show how to run
> > send/receive examples against the example broker, and request_response
> > against the example server. AFTER we have demonstrated that proton is
> > useful *on its own* we can and should provide further examples of using
> > it with other brokers, tornado, ruby/go/whatever specific frameworks and
> > what have you.
> > 
> > Some bindings (Go, possibly C++) provide additional API or toolkit to
> > server multiple connections concurrently. They should also provide
> > concurrent versions of the core examples. The go examples have send and
> > receive take a list of addresses as arguments and send/receive on all
> > addresses concurrently. I would suggest that as a model.
> > 
> > Interested in feedback! I'll be working on Go and C++ in coming weeks so
> > I'd like to co-ordinate with ruby and python efforts so we can present
> > something coherent to our users.
> > 
> > Cheers,
> > Alan.
> > 
> > 
> 
> Working with a completely different code base the same set of questions came 
> up. What makes a good example suite?
> Today this kit has:
>  * HelloWorld
>  ** HelloWorld_simple
>  ** HelloWorld_robust
>  * Interop
>  ** Interop.Client
>  ** Interop.Server
>  ** Interop.Drain
>  ** Interop.Spout
>  * AnonymousRelay
>  ** AnonymousRelay
>  * PeerToPeer
>  ** PeerToPeer.Client
>  ** PeerToPeer.Server
>  * ReceiveSelector
>  ** ReceiveSelector
> 
> 1. The HelloWorld, Interop, AnonymousRelay, and ReceiveSelector examples 
> require an external broker or a Dispatch router network
> 
> 2. HelloWorld has a _simple and a _robust. Criticism of send_simple has basis 
> as long as there's only one send example. If you throw in another example 
> with exception checking, error recovery, configuration options, logging, 
> proper resource closure, and so on with some/many of the things a real 
> application will need eventually then 'send_simple' is a good way to describe 
> the simple one. That's how the two HelloWorld variants came to be.
> 
> 3. The Interop sets client/server and drain/spout faithfully reproduce the 
> command line options of the Qpid Messaging examples. Getting these examples 
> to work in the new client were helped a lot by having known-good Qpid code as 
> the peer for the test.
> 
> Your list of requirements seems good and I like your suggested names. 
> I'd add the requirement that new binding examples MUST interoperate with the 
> existing examples and bindings.
> 

Yes indeed. Interop and consistent naming/usage of examples will make it
much easier to set up some basic interop smoke tests between bindings.
E.g. the Go examples work with the python broker, simple_send and
simple_recv. If all bindings have similar examples then it would be
fairly easy to automate tests for a matrix of combinations.


Reply via email to