[Java] Add example usage to RingBuffer and tryClaim for zero-copy writes

Author: mohyazdanpanah

agrona/src/main/java/org/agrona/concurrent/ringbuffer/RingBuffer.java

@@ -21,6 +21,10 @@
 /**
  * Ring-buffer for the concurrent exchanging of binary encoded messages from producer(s) to consumer(s)
  * in a FIFO manner.
+ * <p>
+ * Supports non-blocking writes via {@link #write(int, DirectBuffer, int, int)} and
+ * zero-copy writes via {@link #tryClaim(int, int)}. Messages are read by consumers
+ * using one of the {@code read} or {@code controlledRead} methods.
  */
 public interface RingBuffer
 {
@@ -44,6 +48,25 @@ public interface RingBuffer
     /**
      * Non-blocking write of a message to an underlying ring-buffer.
      *
+     * <p>
+     * Example usage:
+     * <pre>{@code
+     * // Create a ring buffer with a direct buffer of 1024 bytes
+     * ByteBuffer byteBuffer = ByteBuffer.allocateDirect(1024);
+     * RingBuffer ringBuffer = new OneToOneRingBuffer(new UnsafeBuffer(byteBuffer));
+     *
+     * // Pre-allocate a reusable buffer (cached for the lifetime of the writer)
+     * MutableDirectBuffer srcBuffer =
+     *     new UnsafeBuffer(ByteBuffer.allocateDirect(Long.BYTES));
+     *
+     * // Write a message using the cached buffer
+     * srcBuffer.putLong(0, 12345L);
+     * if (!ringBuffer.write(1, srcBuffer, 0, Long.BYTES))
+     * {
+     *     // Handle insufficient capacity (e.g., retry, log, or drop message)
+     * }
+     * }</pre>
+     *
      * @param msgTypeId type of the message encoding.
      * @param srcBuffer containing the encoded binary message.
      * @param offset    at which the encoded message begins.
@@ -155,11 +178,24 @@ public interface RingBuffer
     int read(MessageHandler handler);
 
     /**
-     * Read as many messages as are available to end of the ring buffer to up a supplied maximum.
+     * Read as many messages as are available to the end of the ring buffer.
+     *
      * <p>
-     * If the ring buffer wraps or encounters a type of record, such a padding record, then an implementation
-     * may choose to return and expect the caller to try again. The {@link #size()} method may be called to
-     * determine of a backlog of message bytes remains in the ring buffer.
+     * Example usage:
+     * <pre>{@code
+     * ringBuffer.read(
+     *     (msgTypeId, buffer, index, length) ->
+     *     {
+     *         final long value = buffer.getLong(index);
+     *         // Process value
+     *     }
+     * );
+     * }</pre>
+     *
+     * <p>
+     * If the ring buffer wraps or encounters a padding record, then an implementation
+     * may choose to return and expect the caller to try again. The {@link #size()} method
+     * may be called to determine if a backlog of message bytes remains.
      *
      * @param handler           to be called for processing each message in turn.
      * @param messageCountLimit the number of messages will be read in a single invocation.