On Tue, 2015-05-26 at 10:54 -0400, Chuck Rolke wrote: > > ----- Original Message ----- > > From: "Alan Conway" <[email protected]> > > To: [email protected] > > Cc: "Darryl L. Pierce" <[email protected]>, "Gordon Sim" <[email protected]> > > 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.
