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 <mgoul...@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.
