On Mon, May 25, 2015 at 12:46:32PM -0400, Alan Conway wrote: > 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 sounds like a reasonable minimal set of examples to provide a POC
of the language.
Additionally, for each class of APIs (messaging, engine, reactive) we
should have matching examples as well: reactive_send, reactive_recv,
etc. This goes hand-in-hand with your later points WRT proper naming.
> 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.
I was equally confused at first. When I see two examples with similar
names, like direct_send and direct_recv, my first thought was that the
two should be used together. So in addition to better names, the README
file(s) could groups together by topic to make it clearer how to use the
examples. Topics like "Simple Messaging", "Reactive Messaging", etc.
that notes the example app and how it works. I would find that easier to
follow and more intuitive than the current README.
> 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.
--
Darryl L. Pierce, Sr. Software Engineer @ Red Hat, Inc.
Delivering value year after year.
Red Hat ranks #1 in value among software vendors.
http://www.redhat.com/promo/vendor/
pgpsk7mgiqTLQ.pgp
Description: PGP signature
