counterexample: you can call ::poll(2) if there isn't anything to available. It will either block or return as desired. That's literally what I would expect a poll function to do: check if something is available; c.f. busy-polling.
Maybe it is a language difference?
Polling, as a term, already generally means asking if there is anything ready. The library might instead have had a poll() to indicate readiness and an unsafeTakeReadyBatch()/releaseBatch() or similar to handle the low level receipt primitives. Or you could even have had a checkForReady() and left poll() to implement a generic version of your busy waiting example, polling with a given sleep and timeout until items were ready, as a convenience for the user.
It's fine as is, of course, as you document expected usage quite well.
So are you saying that POLL was a bad choice of name because polling means "check if there is something available and if there is get it"?
What would be a better name? How about availableToFetch and fetch? Any other better idea?
I don't like remove because you are not actually removing the object from the ring.
A much better name would have been FETCH and not POLL
We'll be changing everything from poll to fetch in the next version => availableToFetch() and fetch()
availableToPoll() is now availableToFetch()
poll() is now fetch()
peek() is now fetch(false)
Note that fetch() == fetch(true)