You are viewing a plain text version of this content. The canonical link for it is here.
Posted to proton@qpid.apache.org by "Justin Ross (JIRA)" <ji...@apache.org> on 2012/12/13 23:16:12 UTC
[jira] [Commented] (PROTON-26) Engine api naming proposal
[ https://issues.apache.org/jira/browse/PROTON-26?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13531571#comment-13531571 ]
Justin Ross commented on PROTON-26:
-----------------------------------
That's really not the case. Rejecting it is fine, but it's mostly gone undiscussed. That's partly my fault. A post to the mailing list with highlights suitable for inline comments is incoming.
> Engine api naming proposal
> --------------------------
>
> Key: PROTON-26
> URL: https://issues.apache.org/jira/browse/PROTON-26
> Project: Qpid Proton
> Issue Type: Improvement
> Components: proton-c, proton-j
> Reporter: Justin Ross
> Assignee: Rafael H. Schloming
> Labels: api
> Fix For: 0.2
>
> Attachments: engine-naming-01.patch, proton-engine-naming-proposal-2.pdf, proton-engine-naming-proposal-3.pdf
>
>
> See https://docs.google.com/spreadsheet/ccc?key=0ArGmVtK1EBOMdEw0bkp4OE5UOWpRRkx3RzVoTjliX0E#gid=0
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
Re: Engine API naming
Posted by Justin Ross <jr...@redhat.com>.
On Thu, 20 Dec 2012, Rafael Schloming wrote:
> On Tue, Dec 18, 2012 at 2:58 PM, Justin Ross <jr...@redhat.com> wrote:
>
>> On Fri, 14 Dec 2012, Rafael Schloming wrote:
>>
>> On Thu, Dec 13, 2012 at 5:37 PM, Justin <jr...@redhat.com> wrote:
>>>
>>> I've found the whole process of proposing API review dispiriting. You
>>>> can, of course, take it or leave it. I in no way wish to claim I have
>>>> better choices. I only wish to point out things that might deserve more
>>>> deliberation.
>>>>
>>>>
>>> Can you please elaborate on your comment about it being "dispiriting"?
>>> You've made several such remarks that have a distinctly negative
>>> connotation without providing enough material behind them for a
>>> constructive discourse.
>>>
>>
>> You say I haven't provided enough material for a constructive discourse.
>> Really? What does a guy have to do? I've made a good faith effort to
>> produce a document comparing the engine APIs in C and Java, and I've
>> produced further revisions of it.
>>
>> It's more or less exactly the kind of thing one would use to hold a
>> conversation in person or on the phone to review and discuss the naming.
>> We've had multiple occasions to do so; we have so far declined. I've been
>> present at many of those, and I know the general sentiment was "ugh".
>>
>> I kept putting energy into it, and it kept meeting with little interest.
>> That asymmetry is dispiriting. That's why I stopped and moved on to other
>> problems.
>>
>
> I didn't mean you haven't provided enough material for technical
> discussion, I meant you've indicated that you're displeased with the
> process, but haven't (until just now) provided details about why.
>
> FWIW, I don't think you should feel quite so discouraged. I think if you
> divide your suggestions along the lines of convention/vocabulary, then most
> of what you've suggested in the convention area has been adopted in some
> form or another, and the API is significantly improved as a result. I'm
> personally quite happy you put in the effort you have so far.
>
> As for the vocabulary discussion, I can understand why you would feel that
> is slower and more frustrating. I personally think the vocabulary
> discussion is very much intertwined with documentation to the point that it
> is very difficult to progress one without the other, and as always it's
> difficult to find time to progress the documentation. Despite that there
> have in fact been some improvements coming out of the vocabulary portion of
> the discussion already, your initial post definitely led to some
> improvements in terminology for the disposition API, and I think all the
> areas you've identified as being confusing genuinely need work even if that
> work might be as much with documentation as with naming.
Thank you for the thoughtful reply. You're of course correct about the
documentation. That's part of the reason so many of my proposed names are
simply wrong. For my personal way of working, naming has an additional
importance: it is how I determine the constraints and responsibilities
(and thus ultimately the documentation) for each part of an api. Iow, I
tend to think a naming discussion is the right basis for developing
documentation. It can of course work the other way around too.
Justin
Re: Engine API naming
Posted by Rafael Schloming <rh...@alum.mit.edu>.
On Tue, Dec 18, 2012 at 2:58 PM, Justin Ross <jr...@redhat.com> wrote:
> On Fri, 14 Dec 2012, Rafael Schloming wrote:
>
> On Thu, Dec 13, 2012 at 5:37 PM, Justin <jr...@redhat.com> wrote:
>>
>> I've found the whole process of proposing API review dispiriting. You
>>> can, of course, take it or leave it. I in no way wish to claim I have
>>> better choices. I only wish to point out things that might deserve more
>>> deliberation.
>>>
>>>
>> Can you please elaborate on your comment about it being "dispiriting"?
>> You've made several such remarks that have a distinctly negative
>> connotation without providing enough material behind them for a
>> constructive discourse.
>>
>
> You say I haven't provided enough material for a constructive discourse.
> Really? What does a guy have to do? I've made a good faith effort to
> produce a document comparing the engine APIs in C and Java, and I've
> produced further revisions of it.
>
> It's more or less exactly the kind of thing one would use to hold a
> conversation in person or on the phone to review and discuss the naming.
> We've had multiple occasions to do so; we have so far declined. I've been
> present at many of those, and I know the general sentiment was "ugh".
>
> I kept putting energy into it, and it kept meeting with little interest.
> That asymmetry is dispiriting. That's why I stopped and moved on to other
> problems.
>
I didn't mean you haven't provided enough material for technical
discussion, I meant you've indicated that you're displeased with the
process, but haven't (until just now) provided details about why.
FWIW, I don't think you should feel quite so discouraged. I think if you
divide your suggestions along the lines of convention/vocabulary, then most
of what you've suggested in the convention area has been adopted in some
form or another, and the API is significantly improved as a result. I'm
personally quite happy you put in the effort you have so far.
As for the vocabulary discussion, I can understand why you would feel that
is slower and more frustrating. I personally think the vocabulary
discussion is very much intertwined with documentation to the point that it
is very difficult to progress one without the other, and as always it's
difficult to find time to progress the documentation. Despite that there
have in fact been some improvements coming out of the vocabulary portion of
the discussion already, your initial post definitely led to some
improvements in terminology for the disposition API, and I think all the
areas you've identified as being confusing genuinely need work even if that
work might be as much with documentation as with naming.
--Rafael
Re: Engine API naming
Posted by Justin Ross <jr...@redhat.com>.
On Fri, 14 Dec 2012, Rafael Schloming wrote:
> On Thu, Dec 13, 2012 at 5:37 PM, Justin <jr...@redhat.com> wrote:
>
>> I've found the whole process of proposing API review dispiriting. You
>> can, of course, take it or leave it. I in no way wish to claim I have
>> better choices. I only wish to point out things that might deserve more
>> deliberation.
>>
>
> Can you please elaborate on your comment about it being "dispiriting"?
> You've made several such remarks that have a distinctly negative
> connotation without providing enough material behind them for a
> constructive discourse.
You say I haven't provided enough material for a constructive discourse.
Really? What does a guy have to do? I've made a good faith effort to
produce a document comparing the engine APIs in C and Java, and I've
produced further revisions of it.
It's more or less exactly the kind of thing one would use to hold a
conversation in person or on the phone to review and discuss the naming.
We've had multiple occasions to do so; we have so far declined. I've been
present at many of those, and I know the general sentiment was "ugh".
I kept putting energy into it, and it kept meeting with little interest.
That asymmetry is dispiriting. That's why I stopped and moved on to other
problems.
Justin
Re: Engine API naming
Posted by Rafael Schloming <rh...@alum.mit.edu>.
On Thu, Dec 13, 2012 at 5:37 PM, Justin <jr...@redhat.com> wrote:
> I've found the whole process of proposing API review dispiriting. You
> can, of course, take it or leave it. I in no way wish to claim I have
> better choices. I only wish to point out things that might deserve more
> deliberation.
>
Can you please elaborate on your comment about it being "dispiriting"?
You've made several such remarks that have a distinctly negative
connotation without providing enough material behind them for a
constructive discourse.
I'll respond to the technical points in a different thread.
--Rafael
Re: Engine API naming
Posted by "Weston M. Price" <wp...@redhat.com>.
Nice suggestions actually. I think some of the discrepancy has to do with the difference between languages and the idioms that have long been fossilized int the different naming conventions.
Again, all suggestions on proposed look good to me.
Regards,
-W
On Dec 13, 2012, at 5:37 PM, Justin <jr...@redhat.com> wrote:
> API usability is important and deserves attention.
>
> Take, for instance, DeliveryState versus Disposition. That only serves to confuse people. It's a difference that has no content. I also think link.drained and link.offered are very unclear.
>
> I've found the whole process of proposing API review dispiriting. You can, of course, take it or leave it. I in no way wish to claim I have better choices. I only wish to point out things that might deserve more deliberation.
>
> Justin
>
> ---
>
> Endpoint state
>
> PN_LOCAL_UNINIT
>
> Existing C name: PN_LOCAL_UNINIT
> Proposed C name: PN_LOCAL_UNINITIALIZED
> Existing Java name: EndpointState.UNINITIALIZED
> Proposed Java name:
>
> One api has the remote-local distinction in one bitset, and one does
> not. Is this difference desirable?
>
> PN_REMOTE_UNINIT
>
> Existing C name: PN_REMOTE_UNINIT
> Proposed C name: PN_REMOTE_UNINITIALIZED
> Existing Java name: EndpointState.UNINITIALIZED
> Proposed Java name:
>
> Personally, I'm at ease with UNINIT as an abbreviation here
>
> Types
>
> pn_disposition_t
>
> Existing C name: pn_disposition_t
> Proposed C name:
> Existing Java name: DeliveryState
> Proposed Java name: Disposition
>
> DeliveryState vs. Disposition. A good example of a confusing
> difference. I have a slight preference for DeliveryState (it's self-
> explanatory), but matching is the main thing.
>
> pn_delivery_tag_t
>
> Existing C name: pn_delivery_tag_t
> Proposed C name:
> Existing Java name: [anonymous byte array]
> Proposed Java name:
>
> DeliveryTag?
>
> Session
>
> pn_session_connection
>
> Existing C name: pn_session_connection
> Proposed C name: pn_session_get_connection
>
> According to Rafi's system, this should have _get_.
>
> Link
>
> pn_link_session
>
> Existing C name: pn_link_session
> Proposed C name: pn_link_get_session
>
> Sender
>
> pn_link_drained
>
> Existing C name: pn_link_drained
> Proposed C name: pn_link_drain_credit [?]
> Existing Java name: Sender.drained
> Proposed Java name: Sender.drainCredit [?]
>
> I can't tell what's going on here. I particularly dislike
> pn_link_drained and _offered. They look like predicates but have no
> return value.
>
> Receiver
>
> pn_link_flow
>
> Existing C name: pn_link_flow
> Proposed C name: pn_link_issue_credit
> Existing Java name: Receiver.flow
> Proposed Java name: Receiver.issueCredit
>
> Consider pn_link_increase_credit, pn_link_issue_credit; working in the
> word "credit" somehow would help a lot
>
> 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
>
> Delivery
>
> pn_delivery_link
>
> Existing C name: pn_delivery_link
> Proposed C name: pn_delivery_get_link
>
> pn_delivery_local_state
>
> Existing C name: pn_delivery_local_state
> Proposed C name: pn_delivery_state
> Existing Java name: Delivery.getLocalState
> Proposed Java name: Delivery.state
>
> "Local" is not used elsewhere for local/remote distinctions
>
> 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.
>
>
> On Thu, 13 Dec 2012, Justin Ross (JIRA) wrote:
>
>>
>> [ https://issues.apache.org/jira/browse/PROTON-26?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13531571#comment-13531571 ]
>>
>> Justin Ross commented on PROTON-26:
>> -----------------------------------
>>
>> That's really not the case. Rejecting it is fine, but it's mostly gone undiscussed. That's partly my fault. A post to the mailing list with highlights suitable for inline comments is incoming.
>>
>>> Engine api naming proposal
>>> --------------------------
>>>
>>> Key: PROTON-26
>>> URL: https://issues.apache.org/jira/browse/PROTON-26
>>> Project: Qpid Proton
>>> Issue Type: Improvement
>>> Components: proton-c, proton-j
>>> Reporter: Justin Ross
>>> Assignee: Rafael H. Schloming
>>> Labels: api
>>> Fix For: 0.2
>>>
>>> Attachments: engine-naming-01.patch, proton-engine-naming-proposal-2.pdf, proton-engine-naming-proposal-3.pdf
>>>
>>>
>>> See https://docs.google.com/spreadsheet/ccc?key=0ArGmVtK1EBOMdEw0bkp4OE5UOWpRRkx3RzVoTjliX0E#gid=0
>>
>> --
>> This message is automatically generated by JIRA.
>> If you think it was sent incorrectly, please contact your JIRA administrators
>> For more information on JIRA, see: http://www.atlassian.com/software/jira
>>
Re: Engine API naming
Posted by Justin Ross <jr...@redhat.com>.
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
Re: Engine API naming
Posted by "Weston M. Price" <wp...@redhat.com>.
On Dec 13, 2012, at 7:23 PM, Rob Godfrey <ro...@gmail.com> wrote:
> On 14 December 2012 01:02, Weston M. Price <wp...@redhat.com> wrote:
>
>>
>> On Dec 13, 2012, at 6:22 PM, Rob Godfrey <ro...@gmail.com> 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.
>>>
>>> <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.
>>>
>>
>> That was the point of the thread, not nit picking certain things.
>>
>>
> I'm not nit-picking - just trying to be being clear that I think some of
> the naming suggestions would actually make the API worse. I think drain()
> and update( .. ) give a truer sense of the intention of the API call
> (though if someone can suggest alternative names that given an even better
> sense of the action associated with the call, then I have no issue).
>
Easy dude...decaf perhaps?
I was simply agreeing with Justin about the discrepancy between the API names in the varying implementations. I don't know anything about intention or anything
else. I assume you guys already have that figured out don't you?
I just work here.
Re: Engine API naming
Posted by Justin Ross <jr...@redhat.com>.
On Fri, 14 Dec 2012, Rob Godfrey wrote:
> On 14 December 2012 01:02, Weston M. Price <wp...@redhat.com> wrote:
>>>
>>> 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.
>>>
>>
>> That was the point of the thread, not nit picking certain things.
>>
>>
> I'm not nit-picking - just trying to be being clear that I think some of
> the naming suggestions would actually make the API worse. I think drain()
> and update( .. ) give a truer sense of the intention of the API call
> (though if someone can suggest alternative names that given an even better
> sense of the action associated with the call, then I have no issue).
Very much agreed! My suggestions are really just pointed ways of raising
question. I appreciate the discussion.
Justin
Re: Engine API naming
Posted by Rob Godfrey <ro...@gmail.com>.
On 14 December 2012 01:02, Weston M. Price <wp...@redhat.com> wrote:
>
> On Dec 13, 2012, at 6:22 PM, Rob Godfrey <ro...@gmail.com> 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.
> >
> > <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.
> >
>
> That was the point of the thread, not nit picking certain things.
>
>
I'm not nit-picking - just trying to be being clear that I think some of
the naming suggestions would actually make the API worse. I think drain()
and update( .. ) give a truer sense of the intention of the API call
(though if someone can suggest alternative names that given an even better
sense of the action associated with the call, then I have no issue).
-- Rob
Re: Engine API naming
Posted by "Weston M. Price" <wp...@redhat.com>.
On Dec 13, 2012, at 6:22 PM, Rob Godfrey <ro...@gmail.com> 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.
>
> <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.
>
That was the point of the thread, not nit picking certain things.
> -- Rob
>
>
>>
>> On Thu, 13 Dec 2012, Justin Ross (JIRA) wrote:
>>
>>
>>> [ https://issues.apache.org/**jira/browse/PROTON-26?page=**
>>> com.atlassian.jira.plugin.**system.issuetabpanels:comment-**
>>> tabpanel&focusedCommentId=**13531571#comment-13531571<https://issues.apache.org/jira/browse/PROTON-26?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13531571#comment-13531571>]
>>>
>>> Justin Ross commented on PROTON-26:
>>> ------------------------------**-----
>>>
>>> That's really not the case. Rejecting it is fine, but it's mostly gone
>>> undiscussed. That's partly my fault. A post to the mailing list with
>>> highlights suitable for inline comments is incoming.
>>>
>>> Engine api naming proposal
>>>> --------------------------
>>>>
>>>> Key: PROTON-26
>>>> URL: https://issues.apache.org/**jira/browse/PROTON-26<https://issues.apache.org/jira/browse/PROTON-26>
>>>> Project: Qpid Proton
>>>> Issue Type: Improvement
>>>> Components: proton-c, proton-j
>>>> Reporter: Justin Ross
>>>> Assignee: Rafael H. Schloming
>>>> Labels: api
>>>> Fix For: 0.2
>>>>
>>>> Attachments: engine-naming-01.patch,
>>>> proton-engine-naming-proposal-**2.pdf, proton-engine-naming-proposal-**
>>>> 3.pdf
>>>>
>>>>
>>>> See https://docs.google.com/**spreadsheet/ccc?key=**
>>>> 0ArGmVtK1EBOMdEw0bkp4OE5UOWpRR**kx3RzVoTjliX0E#gid=0<https://docs.google.com/spreadsheet/ccc?key=0ArGmVtK1EBOMdEw0bkp4OE5UOWpRRkx3RzVoTjliX0E#gid=0>
>>>>
>>>
>>> --
>>> This message is automatically generated by JIRA.
>>> If you think it was sent incorrectly, please contact your JIRA
>>> administrators
>>> For more information on JIRA, see: http://www.atlassian.com/**
>>> software/jira <http://www.atlassian.com/software/jira>
>>>
>>>
Re: Engine API naming
Posted by Rob Godfrey <ro...@gmail.com>.
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.
<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.
-- Rob
>
> On Thu, 13 Dec 2012, Justin Ross (JIRA) wrote:
>
>
>> [ https://issues.apache.org/**jira/browse/PROTON-26?page=**
>> com.atlassian.jira.plugin.**system.issuetabpanels:comment-**
>> tabpanel&focusedCommentId=**13531571#comment-13531571<https://issues.apache.org/jira/browse/PROTON-26?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13531571#comment-13531571>]
>>
>> Justin Ross commented on PROTON-26:
>> ------------------------------**-----
>>
>> That's really not the case. Rejecting it is fine, but it's mostly gone
>> undiscussed. That's partly my fault. A post to the mailing list with
>> highlights suitable for inline comments is incoming.
>>
>> Engine api naming proposal
>>> --------------------------
>>>
>>> Key: PROTON-26
>>> URL: https://issues.apache.org/**jira/browse/PROTON-26<https://issues.apache.org/jira/browse/PROTON-26>
>>> Project: Qpid Proton
>>> Issue Type: Improvement
>>> Components: proton-c, proton-j
>>> Reporter: Justin Ross
>>> Assignee: Rafael H. Schloming
>>> Labels: api
>>> Fix For: 0.2
>>>
>>> Attachments: engine-naming-01.patch,
>>> proton-engine-naming-proposal-**2.pdf, proton-engine-naming-proposal-**
>>> 3.pdf
>>>
>>>
>>> See https://docs.google.com/**spreadsheet/ccc?key=**
>>> 0ArGmVtK1EBOMdEw0bkp4OE5UOWpRR**kx3RzVoTjliX0E#gid=0<https://docs.google.com/spreadsheet/ccc?key=0ArGmVtK1EBOMdEw0bkp4OE5UOWpRRkx3RzVoTjliX0E#gid=0>
>>>
>>
>> --
>> This message is automatically generated by JIRA.
>> If you think it was sent incorrectly, please contact your JIRA
>> administrators
>> For more information on JIRA, see: http://www.atlassian.com/**
>> software/jira <http://www.atlassian.com/software/jira>
>>
>>
Re: Engine API naming
Posted by Rafael Schloming <rh...@alum.mit.edu>.
On Tue, Dec 18, 2012 at 3:21 PM, Justin Ross <jr...@redhat.com> wrote:Types
>
>>> pn_disposition_t
>>>
>>> Existing C name: pn_disposition_t
>>> Proposed C name:
>>> Existing Java name: DeliveryState
>>> Proposed Java name: Disposition
>>>
>>> DeliveryState vs. Disposition. A good example of a confusing
>>> difference. I have a slight preference for DeliveryState (it's self-
>>> explanatory), but matching is the main thing.
>>>
>>
> No one is saying anything about this one?
I agree they should be the same, I'm not sure which one I prefer, but would
be relatively at ease with either. Session
>>> pn_session_connection
>>>
>>> Existing C name: pn_session_connection
>>> Proposed C name: pn_session_get_connection
>>>
>>> According to Rafi's system, this should have _get_.
>>>
>>>
>> Why do you say this? There is no pn_session_set_connection.
>>
>
> Allow me to explain. I thought you were reserving the _get_-less variants
> for "dynamic/computed/derived" slots. I went back and reread your
> statement, I think you meant a slightly broader set of things. To me,
> connection is a "passive slot" that just happens to get set once when you
> create the session.
>
> This kind of subtlety is why I don't much care for the distinction between
> _get_ and _get_-less attributes. I'd rather have one rule.
I agree there is a bit of a tradeoff there. To me the important point in
the case of dynamic/computed properties is to signal that you need to call
the accesser for a fresh value whenever library state may have changed. I
feel like this is most important for values like credit or delivery state
that are subject to asynchronous update by the remote peer. In this
particular case I think these values are *technically* dynamic as future
features like link migration (i.e. moving a link from one
connection/session to another) might cause them to change, however it's
also possibly that we could do that via a copy/replicate operation between
the local link endpoints rather than actually moving the object, in which
case they would be read-only or a passive slot as you say.
One way to clear up potential ambiguity would be to never have the _get_
unless there is a corresponding _set_. This would make adding a _set_ an
API change, however it would be easy to retain backwards compatibility by
having both the _foo and the _get_foo and deprecating the _foo. I'm also
relaxed about adding the _get_ in this case, as even if we do some kind of
link migration thing that would cause the value to become more dynamic,
it's still only changing based on something the local endpoint asked for,
in which case it is not unexpected that it would change.
>
>> Receiver
>>
>>>
>>> pn_link_flow
>>>
>>> Existing C name: pn_link_flow
>>> Proposed C name: pn_link_issue_credit
>>> Existing Java name: Receiver.flow
>>> Proposed Java name: Receiver.issueCredit
>>>
>>> Consider pn_link_increase_credit, pn_link_issue_credit; working in
>>> the
>>> word "credit" somehow would help a lot
>>>
>>>
>> Why do you think introducing the word "credit" would help? How is that
>> anymore meaningful to a blank-slate user than flow and drain? Note this is
>> not a rhetorical question, there might be a good answer to it, but in the
>> absence of some documentation, I'm not seeing it.
>>
>
> To the newbie API user, if you're reading a code sample and see
> rcvr.flow(10), it's not obvious that you're manipulating credit. Indeed,
> the newbie API user probably doesn't even know that credit is a factor at
> all. The word "credit", very simply, tells him or her that credit is a
> thing, and it's being changed.
>
What I'm struggling with here is the degree to which it is important for a
user to know that credit is a thing. In some sense the whole notion of
credit is really just an implementation detail. If you think in terms of
the overall interaction between the two endpoints you can explain the
semantics of flow without referencing credit at all, for example if I were
trying to explain what rcvr.flow(10) does to a newbie API user, I could say
something like "it allows up to 10 messages to flow from the source to the
target", and maybe go on to say that "values passed to flow are cumulative,
e.g. rcvr.flow(2); rcvr.flow(2) is equivalent to rcv.flow(4)".
--Rafael
Re: Engine API naming
Posted by Justin Ross <jr...@redhat.com>.
Comments below.
On Fri, 14 Dec 2012, Rafael Schloming wrote:
> On Thu, Dec 13, 2012 at 5:37 PM, Justin <jr...@redhat.com> wrote:
>
>> API usability is important and deserves attention.
>>
>> Take, for instance, DeliveryState versus Disposition. That only serves to
>> confuse people. It's a difference that has no content. I also think
>> link.drained and link.offered are very unclear.
>>
>> I've found the whole process of proposing API review dispiriting. You
>> can, of course, take it or leave it. I in no way wish to claim I have
>> better choices. I only wish to point out things that might deserve more
>> deliberation.
>>
>> Justin
>>
>> ---
>>
>> Endpoint state
>>
>> PN_LOCAL_UNINIT
>>
>> Existing C name: PN_LOCAL_UNINIT
>> Proposed C name: PN_LOCAL_UNINITIALIZED
>> Existing Java name: EndpointState.UNINITIALIZED
>> Proposed Java name:
>>
>> One api has the remote-local distinction in one bitset, and one does
>> not. Is this difference desirable?
>>
>
> The reason the C API has them in a single bitset is for clarity. There are
> numerous places where you need to pass in the local and/or remote state. If
> you separate these out into two bitsets, then you need two arguments
> everywhere, and it's difficult to remember which is the local state and
> which is the remote state, e.g.:
>
> pn_session_t *ssn = pn_session_head(connection, PN_UNINIT, PN_ACTIVE);
> vs
> pn_session_t *ssn = pn_session_head(connection, PN_LOCAL_UNINIT |
> PN_REMOTE_ACTIVE);
>
> It's also hypothetically a tad more extensible as we can add other state
> flags into the bit set in the future to support additional kinds of queries.
>
> PN_REMOTE_UNINIT
>>
>> Existing C name: PN_REMOTE_UNINIT
>> Proposed C name: PN_REMOTE_UNINITIALIZED
>> Existing Java name: EndpointState.UNINITIALIZED
>> Proposed Java name:
>>
>> Personally, I'm at ease with UNINIT as an abbreviation here
>>
>
> I'm confused by the comment. Are you suggesting a change here or not? My
> preference is to keep the C as is.
I'm suggesting they should be the same, whichever way you go. Like you
suggest, I'd be happy if Java went to EndpointState.UNINIT. (And I'd be
just fine the other way too.)
>>
>> Types
>>
>> pn_disposition_t
>>
>> Existing C name: pn_disposition_t
>> Proposed C name:
>> Existing Java name: DeliveryState
>> Proposed Java name: Disposition
>>
>> DeliveryState vs. Disposition. A good example of a confusing
>> difference. I have a slight preference for DeliveryState (it's self-
>> explanatory), but matching is the main thing.
No one is saying anything about this one?
>>
>> pn_delivery_tag_t
>>
>> Existing C name: pn_delivery_tag_t
>> Proposed C name:
>> Existing Java name: [anonymous byte array]
>> Proposed Java name:
>>
>> DeliveryTag?
>>
>
> The C API also defines a pn_bytes_t which is almost identical to
> pn_delivery_tag_t:
>
> typedef struct pn_delivery_tag_t {
> size_t size;
> const char *bytes;
> } pn_delivery_tag_t;
>
> typedef struct {
> size_t size;
> char *start;
> } pn_bytes_t;
>
> The reason for the const is both so you can pass a const pointer to
> pn_delivery, and so that we can return a pointer to the bytes stored by the
> pn_delivery without worrying about users modifying them:
>
> pn_delivery_t *pn_delivery(pn_link_t *link, pn_delivery_tag_t tag);
> pn_delivery_tag_t pn_delivery_tag(pn_delivery_t *delivery);
>
> We could name the pn_delivery_tag_t something more generic though, e.g.
> pn_const_bytes_t or something like that.
>
>
>> Session
>>
>> pn_session_connection
>>
>> Existing C name: pn_session_connection
>> Proposed C name: pn_session_get_connection
>>
>> According to Rafi's system, this should have _get_.
>>
>
> Why do you say this? There is no pn_session_set_connection.
Allow me to explain. I thought you were reserving the _get_-less variants
for "dynamic/computed/derived" slots. I went back and reread your
statement, I think you meant a slightly broader set of things. To me,
connection is a "passive slot" that just happens to get set once when you
create the session.
This kind of subtlety is why I don't much care for the distinction between
_get_ and _get_-less attributes. I'd rather have one rule.
> Link
>>
>> pn_link_session
>>
>> Existing C name: pn_link_session
>> Proposed C name: pn_link_get_session
>>
>
> Same comment as above.
>
>
>>
>> Sender
>>
>> pn_link_drained
>>
>> Existing C name: pn_link_drained
>> Proposed C name: pn_link_drain_credit [?]
>> Existing Java name: Sender.drained
>> Proposed Java name: Sender.drainCredit [?]
>>
>> I can't tell what's going on here. I particularly dislike
>> pn_link_drained and _offered. They look like predicates but have no
>> return value.
>>
>
> These really need to be documented before a meaningful discussion can take
> place.
>
> Receiver
>>
>> pn_link_flow
>>
>> Existing C name: pn_link_flow
>> Proposed C name: pn_link_issue_credit
>> Existing Java name: Receiver.flow
>> Proposed Java name: Receiver.issueCredit
>>
>> Consider pn_link_increase_credit, pn_link_issue_credit; working in the
>> word "credit" somehow would help a lot
>>
>
> Why do you think introducing the word "credit" would help? How is that
> anymore meaningful to a blank-slate user than flow and drain? Note this is
> not a rhetorical question, there might be a good answer to it, but in the
> absence of some documentation, I'm not seeing it.
To the newbie API user, if you're reading a code sample and see
rcvr.flow(10), it's not obvious that you're manipulating credit. Indeed,
the newbie API user probably doesn't even know that credit is a factor at
all. The word "credit", very simply, tells him or her that credit is a
thing, and it's being changed.
>
> 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
>>
>> Delivery
>>
>> pn_delivery_link
>>
>> Existing C name: pn_delivery_link
>> Proposed C name: pn_delivery_get_link
>>
>
> Same comment as above, there is no pn_delivery_set_link, nor could there
> ever be such a thing.
>
> pn_delivery_local_state
>>
>> Existing C name: pn_delivery_local_state
>> Proposed C name: pn_delivery_state
>> Existing Java name: Delivery.getLocalState
>> Proposed Java name: Delivery.state
>>
>> "Local" is not used elsewhere for local/remote distinctions
>>
>> 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.
>>
>
> Updated returns true whenever the remote state has been updated, so there
> is a one to one correspondence between [remote] calls to update and what
> updated reports. This is similarly the case for settle/settled. The verb is
> performing a local action, the interrogative is querying whether the same
> action was performed remotely. <http://www.atlassian.com/software/jira>
Okay, that's nice. That puts me at ease with "update".
Re: Engine API naming
Posted by Rafael Schloming <rh...@alum.mit.edu>.
On Thu, Dec 13, 2012 at 5:37 PM, Justin <jr...@redhat.com> wrote:
> API usability is important and deserves attention.
>
> Take, for instance, DeliveryState versus Disposition. That only serves to
> confuse people. It's a difference that has no content. I also think
> link.drained and link.offered are very unclear.
>
> I've found the whole process of proposing API review dispiriting. You
> can, of course, take it or leave it. I in no way wish to claim I have
> better choices. I only wish to point out things that might deserve more
> deliberation.
>
> Justin
>
> ---
>
> Endpoint state
>
> PN_LOCAL_UNINIT
>
> Existing C name: PN_LOCAL_UNINIT
> Proposed C name: PN_LOCAL_UNINITIALIZED
> Existing Java name: EndpointState.UNINITIALIZED
> Proposed Java name:
>
> One api has the remote-local distinction in one bitset, and one does
> not. Is this difference desirable?
>
The reason the C API has them in a single bitset is for clarity. There are
numerous places where you need to pass in the local and/or remote state. If
you separate these out into two bitsets, then you need two arguments
everywhere, and it's difficult to remember which is the local state and
which is the remote state, e.g.:
pn_session_t *ssn = pn_session_head(connection, PN_UNINIT, PN_ACTIVE);
vs
pn_session_t *ssn = pn_session_head(connection, PN_LOCAL_UNINIT |
PN_REMOTE_ACTIVE);
It's also hypothetically a tad more extensible as we can add other state
flags into the bit set in the future to support additional kinds of queries.
PN_REMOTE_UNINIT
>
> Existing C name: PN_REMOTE_UNINIT
> Proposed C name: PN_REMOTE_UNINITIALIZED
> Existing Java name: EndpointState.UNINITIALIZED
> Proposed Java name:
>
> Personally, I'm at ease with UNINIT as an abbreviation here
>
I'm confused by the comment. Are you suggesting a change here or not? My
preference is to keep the C as is.
>
> Types
>
> pn_disposition_t
>
> Existing C name: pn_disposition_t
> Proposed C name:
> Existing Java name: DeliveryState
> Proposed Java name: Disposition
>
> DeliveryState vs. Disposition. A good example of a confusing
> difference. I have a slight preference for DeliveryState (it's self-
> explanatory), but matching is the main thing.
>
> pn_delivery_tag_t
>
> Existing C name: pn_delivery_tag_t
> Proposed C name:
> Existing Java name: [anonymous byte array]
> Proposed Java name:
>
> DeliveryTag?
>
The C API also defines a pn_bytes_t which is almost identical to
pn_delivery_tag_t:
typedef struct pn_delivery_tag_t {
size_t size;
const char *bytes;
} pn_delivery_tag_t;
typedef struct {
size_t size;
char *start;
} pn_bytes_t;
The reason for the const is both so you can pass a const pointer to
pn_delivery, and so that we can return a pointer to the bytes stored by the
pn_delivery without worrying about users modifying them:
pn_delivery_t *pn_delivery(pn_link_t *link, pn_delivery_tag_t tag);
pn_delivery_tag_t pn_delivery_tag(pn_delivery_t *delivery);
We could name the pn_delivery_tag_t something more generic though, e.g.
pn_const_bytes_t or something like that.
> Session
>
> pn_session_connection
>
> Existing C name: pn_session_connection
> Proposed C name: pn_session_get_connection
>
> According to Rafi's system, this should have _get_.
>
Why do you say this? There is no pn_session_set_connection.
Link
>
> pn_link_session
>
> Existing C name: pn_link_session
> Proposed C name: pn_link_get_session
>
Same comment as above.
>
> Sender
>
> pn_link_drained
>
> Existing C name: pn_link_drained
> Proposed C name: pn_link_drain_credit [?]
> Existing Java name: Sender.drained
> Proposed Java name: Sender.drainCredit [?]
>
> I can't tell what's going on here. I particularly dislike
> pn_link_drained and _offered. They look like predicates but have no
> return value.
>
These really need to be documented before a meaningful discussion can take
place.
Receiver
>
> pn_link_flow
>
> Existing C name: pn_link_flow
> Proposed C name: pn_link_issue_credit
> Existing Java name: Receiver.flow
> Proposed Java name: Receiver.issueCredit
>
> Consider pn_link_increase_credit, pn_link_issue_credit; working in the
> word "credit" somehow would help a lot
>
Why do you think introducing the word "credit" would help? How is that
anymore meaningful to a blank-slate user than flow and drain? Note this is
not a rhetorical question, there might be a good answer to it, but in the
absence of some documentation, I'm not seeing it.
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
>
> Delivery
>
> pn_delivery_link
>
> Existing C name: pn_delivery_link
> Proposed C name: pn_delivery_get_link
>
Same comment as above, there is no pn_delivery_set_link, nor could there
ever be such a thing.
pn_delivery_local_state
>
> Existing C name: pn_delivery_local_state
> Proposed C name: pn_delivery_state
> Existing Java name: Delivery.getLocalState
> Proposed Java name: Delivery.state
>
> "Local" is not used elsewhere for local/remote distinctions
>
> 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.
>
Updated returns true whenever the remote state has been updated, so there
is a one to one correspondence between [remote] calls to update and what
updated reports. This is similarly the case for settle/settled. The verb is
performing a local action, the interrogative is querying whether the same
action was performed remotely. <http://www.atlassian.com/software/jira>
--Rafael
Engine API naming
Posted by Justin <jr...@redhat.com>.
API usability is important and deserves attention.
Take, for instance, DeliveryState versus Disposition. That only serves to
confuse people. It's a difference that has no content. I also think
link.drained and link.offered are very unclear.
I've found the whole process of proposing API review dispiriting. You
can, of course, take it or leave it. I in no way wish to claim I have
better choices. I only wish to point out things that might deserve
more deliberation.
Justin
---
Endpoint state
PN_LOCAL_UNINIT
Existing C name: PN_LOCAL_UNINIT
Proposed C name: PN_LOCAL_UNINITIALIZED
Existing Java name: EndpointState.UNINITIALIZED
Proposed Java name:
One api has the remote-local distinction in one bitset, and one does
not. Is this difference desirable?
PN_REMOTE_UNINIT
Existing C name: PN_REMOTE_UNINIT
Proposed C name: PN_REMOTE_UNINITIALIZED
Existing Java name: EndpointState.UNINITIALIZED
Proposed Java name:
Personally, I'm at ease with UNINIT as an abbreviation here
Types
pn_disposition_t
Existing C name: pn_disposition_t
Proposed C name:
Existing Java name: DeliveryState
Proposed Java name: Disposition
DeliveryState vs. Disposition. A good example of a confusing
difference. I have a slight preference for DeliveryState (it's self-
explanatory), but matching is the main thing.
pn_delivery_tag_t
Existing C name: pn_delivery_tag_t
Proposed C name:
Existing Java name: [anonymous byte array]
Proposed Java name:
DeliveryTag?
Session
pn_session_connection
Existing C name: pn_session_connection
Proposed C name: pn_session_get_connection
According to Rafi's system, this should have _get_.
Link
pn_link_session
Existing C name: pn_link_session
Proposed C name: pn_link_get_session
Sender
pn_link_drained
Existing C name: pn_link_drained
Proposed C name: pn_link_drain_credit [?]
Existing Java name: Sender.drained
Proposed Java name: Sender.drainCredit [?]
I can't tell what's going on here. I particularly dislike
pn_link_drained and _offered. They look like predicates but have no
return value.
Receiver
pn_link_flow
Existing C name: pn_link_flow
Proposed C name: pn_link_issue_credit
Existing Java name: Receiver.flow
Proposed Java name: Receiver.issueCredit
Consider pn_link_increase_credit, pn_link_issue_credit; working in the
word "credit" somehow would help a lot
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
Delivery
pn_delivery_link
Existing C name: pn_delivery_link
Proposed C name: pn_delivery_get_link
pn_delivery_local_state
Existing C name: pn_delivery_local_state
Proposed C name: pn_delivery_state
Existing Java name: Delivery.getLocalState
Proposed Java name: Delivery.state
"Local" is not used elsewhere for local/remote distinctions
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.
On Thu, 13 Dec 2012, Justin Ross (JIRA) wrote:
>
> [ https://issues.apache.org/jira/browse/PROTON-26?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13531571#comment-13531571 ]
>
> Justin Ross commented on PROTON-26:
> -----------------------------------
>
> That's really not the case. Rejecting it is fine, but it's mostly gone undiscussed. That's partly my fault. A post to the mailing list with highlights suitable for inline comments is incoming.
>
>> Engine api naming proposal
>> --------------------------
>>
>> Key: PROTON-26
>> URL: https://issues.apache.org/jira/browse/PROTON-26
>> Project: Qpid Proton
>> Issue Type: Improvement
>> Components: proton-c, proton-j
>> Reporter: Justin Ross
>> Assignee: Rafael H. Schloming
>> Labels: api
>> Fix For: 0.2
>>
>> Attachments: engine-naming-01.patch, proton-engine-naming-proposal-2.pdf, proton-engine-naming-proposal-3.pdf
>>
>>
>> See https://docs.google.com/spreadsheet/ccc?key=0ArGmVtK1EBOMdEw0bkp4OE5UOWpRRkx3RzVoTjliX0E#gid=0
>
> --
> This message is automatically generated by JIRA.
> If you think it was sent incorrectly, please contact your JIRA administrators
> For more information on JIRA, see: http://www.atlassian.com/software/jira
>