Improve documentation on queue progress guarantees

[nitsanw]

Currently the java doc does not state, or sometimes incorrectly states, the progress guarantees (wait free, lock free, blocking etc) and edge cases on JCTools queues. This can lead to poorly informed choices.

[franz1981]

+1 on my side, but that's not easy anyway...
I'm thinking about the XADD queues (my current obsession), but it is applicable to many others qs: the mpsc variant for example, producer side (ie offer) is wait free (bounded, but not population obvious) if we exclude from the equation the allocation of chunk; consumer side (ie poll), by consequence, seems to be wait free, but in practice could be blocked for some time, awaiting the element/chunk to be visible.
Overall progress conditions (offer and poll in sequence) are bounded to what poll deliver, probably..
My concern is that such academic definitions aren't precise enough to capture the user expectations and maybe just describing on the doc what could happen (eg poll can spin awaiting element publication) would be a simpler, but more straightforward way to match user needs.

[nitsanw]

Yes, it's not an easy task. And the result may be more confusing than enlightening. I think the way forward is to go through it for offer/poll on a few implementations and see if there's any common parts that can be hoisted into the common package javadoc instead of being repeated. References to external sources are also good (e.g. a Wiki page on the XADD queue algorithm would help ;-) ).

[franz1981]

You got a point here :P
I will come soon with a wiki page re the XADD q algorithm :)
If you have any adjustment/optimization to it, drop me few lines via email too so I will put it on the wiki..given that's something new there is no paper (AFAIK) re it so we can change it to suit our needs...

Re the doc I believe that we have lot of common points in many qs and we can save some docs...