semantics vs. behavior

[Michael Goulish <mg...@redhat.com>]

Wow, I never thought I would have a philosophy question about documentation.

Should I be documenting semantics that will be stable across all[1] releases?
Or observable behavior in the release you, dear developer, have in your hands right now?
Or, perhaps, both ?

I'll tell you, as a developer, I would certainly want to know exactly what's
going to happen when I call put() and send() with this release.

------------------------------

[1] for sufficiently small values of "all".
 




> What I said was put is *allowed* to send optimistically, not that it is
> required to. It actually did send optimistically in a previous version of
> the code, however I commented that line out.
>
> I would say the documented semantics of put and send should allow the
> implementation the flexibility to do any of the following:
>
>   1) optimistically transmit whatever it can everytime so long as it
> doesn't block
>   2) never bother transmitting anything until you force it to by calling
> send
>   3) anything in between the first two, e.g. magically transmit once you've
> put enough messages to reach the optimal batch size
>
> The reason for the behaviour you are observing is that we currently do
> option 2 in the C impl, however we've done option 1 in the past (and I
> think we do option 1 still in the Java impl), and we will probably do
> option 3 in the future.

Re: semantics vs. behavior

[Ted Ross <tr...@redhat.com>]

If semantics like "put vs. send" are not stable as documented across 
releases, then the API is not stable and people's applications will 
break when they shouldn't.  In other words, even documented changes in 
semantics represent incompatible breaks in the API.

So, you should be documenting semantics that are stable across 
releases.  Furthermore, those semantics should be as close to what a 
*reasonable* developer would expect as is possible.

-Ted

On 03/05/2013 02:27 PM, Michael Goulish wrote:
> Wow, I never thought I would have a philosophy question about documentation.
>
> Should I be documenting semantics that will be stable across all[1] releases?
> Or observable behavior in the release you, dear developer, have in your hands right now?
> Or, perhaps, both ?
>
> I'll tell you, as a developer, I would certainly want to know exactly what's
> going to happen when I call put() and send() with this release.
>
> ------------------------------
>
> [1] for sufficiently small values of "all".
>   
>
>
>
>
>> What I said was put is *allowed* to send optimistically, not that it is
>> required to. It actually did send optimistically in a previous version of
>> the code, however I commented that line out.
>>
>> I would say the documented semantics of put and send should allow the
>> implementation the flexibility to do any of the following:
>>
>>    1) optimistically transmit whatever it can everytime so long as it
>> doesn't block
>>    2) never bother transmitting anything until you force it to by calling
>> send
>>    3) anything in between the first two, e.g. magically transmit once you've
>> put enough messages to reach the optimal batch size
>>
>> The reason for the behaviour you are observing is that we currently do
>> option 2 in the C impl, however we've done option 1 in the past (and I
>> think we do option 1 still in the Java impl), and we will probably do
>> option 3 in the future.

Re: semantics vs. behavior

[Rafael Schloming <rh...@alum.mit.edu>]

I would say you should document the semantics of the interface and leave
out irrelevant implementation behaviours, and that does often include
observable behaviours.

If we need to stay backwards compatible to all possible observable
behaviours then our implementation will be overly constrained and people
might as well just stay with whatever release they are on. Furthermore,
documenting all possible observable behaviours will only encourage people
to depend on them, so I think you should assume anything you write down is
something we're encouraging people to use/depend on and something we have
an obligation to at least try not to break going forward.

--Rafael

On Tue, Mar 5, 2013 at 11:27 AM, Michael Goulish <mg...@redhat.com>wrote:

>
> Wow, I never thought I would have a philosophy question about
> documentation.
>
> Should I be documenting semantics that will be stable across all[1]
> releases?
> Or observable behavior in the release you, dear developer, have in your
> hands right now?
> Or, perhaps, both ?
>
> I'll tell you, as a developer, I would certainly want to know exactly
> what's
> going to happen when I call put() and send() with this release.
>
> ------------------------------
>
> [1] for sufficiently small values of "all".
>
>
>
>
>
> > What I said was put is *allowed* to send optimistically, not that it is
> > required to. It actually did send optimistically in a previous version of
> > the code, however I commented that line out.
> >
> > I would say the documented semantics of put and send should allow the
> > implementation the flexibility to do any of the following:
> >
> >   1) optimistically transmit whatever it can everytime so long as it
> > doesn't block
> >   2) never bother transmitting anything until you force it to by calling
> > send
> >   3) anything in between the first two, e.g. magically transmit once
> you've
> > put enough messages to reach the optimal batch size
> >
> > The reason for the behaviour you are observing is that we currently do
> > option 2 in the C impl, however we've done option 1 in the past (and I
> > think we do option 1 still in the Java impl), and we will probably do
> > option 3 in the future.
>

Re: semantics vs. behavior

[Rajith Attapattu <ra...@gmail.com>]

Mick, great question!
As I mentioned in the other thread we owe it to application developers
to describe the behaviour.
And if we change the behaviour btw releases we need to document it
prominently in the release notes as is often the case applications
will be written taking advantage of certain behavioural patterns.

A somewhat related example is, DUPS_OK and AUTO_ACK had the same
behaviour (all though wrong) and most applications that used AUTO_ACK
saw a performance drop when we eventually fixed it. Some applications
used the wrong ack mode, just bcos it behaved in a certain way.
Chances are that applications will be written to rely on the current
behaviour. So we need text to explain that all though that this is the
current behaviour things may change in the future. If it does change
then we need to tell them how to fall back to the previous behaviour.
This is my rationale behind making the behaviour configurable.

Rajith

On Tue, Mar 5, 2013 at 2:27 PM, Michael Goulish <mg...@redhat.com> wrote:
>
> Wow, I never thought I would have a philosophy question about documentation.
>
> Should I be documenting semantics that will be stable across all[1] releases?
> Or observable behavior in the release you, dear developer, have in your hands right now?
> Or, perhaps, both ?
>
> I'll tell you, as a developer, I would certainly want to know exactly what's
> going to happen when I call put() and send() with this release.
>
> ------------------------------
>
> [1] for sufficiently small values of "all".
>
>
>
>
>
>> What I said was put is *allowed* to send optimistically, not that it is
>> required to. It actually did send optimistically in a previous version of
>> the code, however I commented that line out.
>>
>> I would say the documented semantics of put and send should allow the
>> implementation the flexibility to do any of the following:
>>
>>   1) optimistically transmit whatever it can everytime so long as it
>> doesn't block
>>   2) never bother transmitting anything until you force it to by calling
>> send
>>   3) anything in between the first two, e.g. magically transmit once you've
>> put enough messages to reach the optimal batch size
>>
>> The reason for the behaviour you are observing is that we currently do
>> option 2 in the C impl, however we've done option 1 in the past (and I
>> think we do option 1 still in the Java impl), and we will probably do
>> option 3 in the future.