You are viewing a plain text version of this content. The canonical link for it is here.
Posted to proton@qpid.apache.org by Alan Conway <ac...@redhat.com> on 2015/05/25 18:46:32 UTC
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.
Re: New language bindings - when are they ready? [was Re: Ruby
Engine APIs up for review]
Posted by "Darryl L. Pierce" <dp...@redhat.com>.
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/
Re: New language bindings - when are they ready? [was Re: Ruby
Engine APIs up for review]
Posted by Alan Conway <ac...@redhat.com>.
On Tue, 2015-05-26 at 10:54 -0400, Chuck Rolke wrote:
>
> ----- Original Message -----
> > From: "Alan Conway" <ac...@redhat.com>
> > To: proton@qpid.apache.org
> > Cc: "Darryl L. Pierce" <dp...@redhat.com>, "Gordon Sim" <gs...@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.
Re: New language bindings - when are they ready? [was Re: Ruby
Engine APIs up for review]
Posted by Chuck Rolke <cr...@redhat.com>.
----- Original Message -----
> From: "Alan Conway" <ac...@redhat.com>
> To: proton@qpid.apache.org
> Cc: "Darryl L. Pierce" <dp...@redhat.com>, "Gordon Sim" <gs...@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.
-Chuck