Contract of RingBuffer.read()

[juddgaddie]

Is it expected that RingBuffer.read(Handler, 1) will always return a message if it has been written to the RingBuffer?

It appears as though RingBuffer.read(Handler, 1) will return 0 messages when a PADDING_MSG_TYPE has been written.

If this is expected I would propose adding some Javadoc clarifying the contract?

[nitsanw]

The doc states:

    /**
     * Read as many messages as are available from the ring buffer.
     *
     * @param handler to be called for processing each message in turn.
     * @return the number of messages that have been processed.
     */
    int read(MessageHandler handler);

    /**
     * Read as many messages as are available from the ring buffer to up a supplied maximum.
     *
     * @param handler           to be called for processing each message in turn.
     * @param messageCountLimit the number of messages will be read in a single invocation.
     * @return the number of messages that have been processed.
     */
    int read(MessageHandler handler, int messageCountLimit);

In the case you describe no messages are processed by the handler, so 0 is returned.
The API does not commit to only returning 0 when buffer is empty, so this is within spec.
I agree that many users may find it confusing. Please suggest alternate wording?

[nitsanw]

"Is it expected that RingBuffer.read(Handler, 1) will always return a message if it has been written to the RingBuffer?"
The answer would seem to be no. It will eventually return it.

[nitsanw]

Also note that the padding message is not the issue, but the symptom, e.g.:
https://github.com/real-logic/Agrona/blob/428e6dba3ff15ea9f0e5db6fab6a74ccbf378cb9/agrona/src/main/java/org/agrona/concurrent/ringbuffer/OneToOneRingBuffer.java#L192
The reason the read terminates is because it has hit the end of contiguous memory, or the edge of the ring buffer. This is also where you'd typically find padding, but not always necessarily.

[juddgaddie]

@mjpt777 Thanks for the update that is now very clear.