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.

Reply via email to