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 releases?
Or observable behavior in the release you, dear developer, have in your hands
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.
 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
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.