On Fri, 14 Dec 2012, Rob Godfrey wrote:

A couple of comments...

On 13 December 2012 23:37, Justin <jr...@redhat.com> wrote:

API usability is important and deserves attention.


<snip>



  pn_link_drain

    Existing C name:    pn_link_drain
    Proposed C name:    pn_link_rescind_credit
    Existing Java name: Receiver.drain
    Proposed Java name: Receiver.rescindCredit

    Consider pn_link_decrease_credit, pn_link_rescind_credit


Drain *doesn't* rescind credit, or decrease credit, so I'd be -1 on these
names. Drain is an indication that the sender should use all available
credit, but if insufficient deliveries are available at the sender to use
up all the credit, only then should it act as if all credit had been
consumed.  At no point is the receiver rescinding credit.

I was very much in guessing mode when I made many of these suggestions. I figured it was better to put out something wrong and spark a conversation than it was to say nothing.

In this case, I think the "credit" arg to drain confused me. It looked like the api was manipulating the credit value in some way opposite to flow. I've now done further research, and instead the credit arg is used to *add* credit.

This is a little confusing, but maybe there are no better choices. Why is the api drain call a combination of increasing the link credit and setting the drain flag? Would it be clearer to just do the latter?


<snip>


  pn_delivery_update

    Existing C name:    pn_delivery_update
    Proposed C name:    pn_delivery_acknowledge
    Existing Java name: Delivery.disposition
    Proposed Java name: Delivery.acknowledge

    Do calls to delivery.update correspond one-to-one to
    delivery.updated?  The naming implies a symmetry that I'm not sure
    is there.


I'm -1 on acknowledged. Acknowledgement is one type of update, but not the
only one. I'm fine with changing the Java to update() to match the C.

On things such as bitmaps vs. enums, I think that's just a language
convention thing... I don't see a huge need to make such things identical.
Naming is something that should be aligned between APIs however.

Okay, thanks. You've mentioned these before, so I'm sorry to make you repeat yourself. Nonetheless, it's nice to have them recorded.

Justin

Reply via email to