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.


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

Reply via email to