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.
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?
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
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.