qpid-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Justin Ross <justin.r...@gmail.com>
Subject Re: Proton C++ API update
Date Fri, 15 Apr 2016 17:47:59 GMT
To address that use case, I had in mind some improved logging tied to event
dispatch.  We don't have it now, but we have a natural place to put it.  I
think we'd want this even if we did reinstate the catchall.

On Fri, Apr 15, 2016 at 10:29 AM, Alexandre Trufanow <
alexandre.trufanow.mx@gmail.com> wrote:

> The changes look good overall, removing the event class makes the handler's
> API much cleaner IMO.
> I found the on_unhandled callback very useful for testing/debugging, when I
> didn't know what event to expect for my unit tests. Do you think there
> could be another way of setting a catchall for events? The obvious
> workaround would be to implement all callbacks but this is much more
> clunky.
>
> Thanks
> Alexandre
>
> On Thu, Apr 14, 2016 at 8:06 PM, Justin Ross <justin.ross@gmail.com>
> wrote:
>
> > Hi, everyone.  Our work on the Proton C++ API has progressed quite a bit,
> > and it's time to talk about the changes.
> >
> > First, a confession.  I described the API we delivered in 0.12.0 as
> > "substantially settled", excepting some of the extension APIs and those
> API
> > elements that were hidden in the API docs.
> >
> > Our work since then has now exceeded what one can reasonably allow inside
> > the confines of "substantially settled".  I'll try to detail the changes
> > and their rationales.  After that I'll talk about our plan moving
> forward.
> >
> > There have also been many additions that do not affect API compatibility.
> > I won't list all of those here, but you can explore them on the API spec.
> >
> > http://home.apache.org/~jross/pumpjack/index.html
> >
> > Before I enumerate the changes, however, I'd like to say that we really
> > very much appreciate the use and feedback we've received on the API so
> > far.  It is absolutely invaluable, we're grateful, and we want more.
> >
> > ## Event handling
> >
> > http://home.apache.org/~jross/pumpjack/core/handler/index.html
> >
> >  - Handler callback signatures
> >    - The handler callbacks now take relevant objects as inputs
> >    - We removed event (the arg and the API type)
> >    - In each callback, the first input argument is an entry-point into
> the
> > endpoint object tree and can be used for navigation to parent objects
> such
> > as container
> >  - We renamed on-start and on-stop to on-container-start and
> > on-container-stop; these now take container
> >  - We removed on-unhandled
> >  - We renamed on-unhandled-error to simply on-error
> >
> > You can see the effect on the examples here:
> >
> >
> >
> https://github.com/apache/qpid-proton/blob/master/examples/cpp/helloworld.cpp
> > https://github.com/apache/qpid-proton/tree/master/examples/cpp
> >
> > ## Message
> >
> > http://home.apache.org/~jross/pumpjack/core/message/index.html
> >
> >  - We renamed "address" to "to", retaining "address" as an alias; "to"
> > matches the AMQP spec and better illustrates the relation to "reply-to"
> >  - We renamed application-properties to properties; "properties" is used
> in
> > the sense of application-supplied properties throughout the API
> >
> > ## Sender and receiver instead of link
> >
> > http://home.apache.org/~jross/pumpjack/core/sender/index.html
> > http://home.apache.org/~jross/pumpjack/core/receiver/index.html
> >
> >  - We previously offered properties and methods on link that were useful
> > only if the link was a receiver or vice versa; instead we now provide
> only
> > the relevant members on sender and receiver respectively
> >  - This is reflected in the event handlers as well: there are now
> dedicated
> > handler methods for senders versus receivers
> >  - Sender and receiver options are split accordingly
> >
> > ## Source and target instead of terminus
> >
> > http://home.apache.org/~jross/pumpjack/core/source/index.html
> > http://home.apache.org/~jross/pumpjack/core/target/index.html
> >
> >  - Same story as sender and receiver; source and target now contain no
> > context-dependent members
> >  - Source and target options are split accordingly
> >
> > ## Tracker and delivery^r instead of delivery
> >
> > http://home.apache.org/~jross/pumpjack/core/tracker/index.html
> > http://home.apache.org/~jross/pumpjack/core/delivery/index.html
> >
> >  - Delivery was previously used for both the sending and receiving sides
> of
> > a transfer; it is now separated for the same reasons as sender and
> > receiver, source and target
> >  - A tracker is associated with sending: it tracks a message transfer
> from
> > the sender's perspective
> >  - A delivery (in the revised sense) is a message transfer being received
> >
> > ## Flow control
> >
> >
> >
> http://home.apache.org/~jross/pumpjack/core/receiver/index.html#flow-control
> >
> >  - We now use API names that speak in terms of credit: receiver.credit,
> > receiver.add-credit, sender.credit, receiver-options.credit-window
> >
> > ## Endpoint properties and methods
> >
> >
> >
> http://home.apache.org/~jross/pumpjack/core/connection/index.html#endpoint-lifecycle
> >
> >  - We introduced boolean properties for endpoint states instead of the
> > endpoint.state bit field
> >  - Endpoint.close takes an optional error-condition
> >
> > ## Endpoint options
> >
> >
> http://home.apache.org/~jross/pumpjack/core/connection-options/index.html
> > http://home.apache.org/~jross/pumpjack/core/session-options/index.html
> > http://home.apache.org/~jross/pumpjack/core/sender-options/index.html
> > http://home.apache.org/~jross/pumpjack/core/receiver-options/index.html
> >
> >  - Connection.virtual-host instead of host, to clarify its purpose versus
> > the host info supplied in URLs
> >  - Connection.max-sessions instead of max-channels, in order to speak in
> > user terms, not AMQP spec terms
> >  - Added session-options
> >  - Some 0.12.0 link options will be removed until their status is decided
> >
> > ## Data types
> >
> > http://home.apache.org/~jross/pumpjack/types/index.html
> >
> >  - We have dropped the "amqp-" prefixes from type names; if a
> > language-provided type fits the need, we use that; if the language
> doesn't
> > offer one, we can introduce the type without any concern about collisions
> >  - We will use string, not the URL class, as the first-class
> representation
> > of a URL in API signatures; we will continue to use the URL class
> directly
> > in our examples to simplify simple parsing jobs
> >
> > ## Future plans
> >
> > We have either already made or will be making these changes for Proton
> > 0.13.0.  The amount of outstanding work may require a Proton release
> delay.
> >
> > As with 0.12.0, not all parts of the API will be declared stable at that
> > point.  Specifically:
> >
> >  - We will mark some elements of the API experimental and subject to
> > change; for instance, the IO and codec namespaces will remain
> experimental
> >  - We will mark some elements internal (and thus not exposed in API docs)
> > until we are confident they are ready for broader use
> >
> > Apart from these exclusions, however, we will be supporting the Proton
> > 0.13.0 C++ core and data types as stable API going forward.
> >
> > Please give us your thoughts on the proposed API.  We'll do our best to
> > explain our thinking or adapt it.
> >
> > Thanks,
> > Justin
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message