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)".


Reply via email to