Add Javadoc usage examples to RingBuffer

[mohyazdanpanah]

Hi @pveentjer,

Thanks for your previous review and helpful feedback
I’ve considered your comments and moved the example usage to the appropriate classes.
This new pull request updates the Javadoc by:
• Adding the basic usage example to MutableDirectBuffer
• Adding atomic operation examples to AtomicBuffer

Appreciate your time and guidance in the review process!

[pveentjer]

Thank you for the update. I'll provide review comments shortly.

[mohyazdanpanah]

@pveentjer
Thanks a lot for taking the time to review this

Your feedback is really valuable and full of great points for me to learn from. I appreciate the detailed explanations — they helped me better understand the design intent behind these classes and improve the docs accordingly

[pveentjer]

This code gives the impression it is fine to create ad hoc MutableDirectBuffers. In low latency systems, you don't want to create litter on the fast path because it creates a lot of performance problems. From increased mean to increased latency tail.

It should be clear to the end user that a cached buffer should be used.

[mohyazdanpanah]

@pveentjer
In recent chagnes, makes it clear that the buffer should be created once and reused for multiple writes, which is the main point of your review.

[pveentjer]

I'm nit picking; but could you make the buffer 8 bytes since that is the size of a long. Use Long.BYTES as the constant.

[mohyazdanpanah]

God is in the details. good point. i will change docs and back to you again

[pveentjer]

You are ignoring the return value of the write. It could be that the write isn't accepted because there insufficient space. If you don't handle the return value properly, messages can appear to get lost.

[pveentjer]

Can you also add an example using the tryClaim. The advantage of tryClaim above offer is that you can directly write to the memory of the ringbuffer instead of writing to an intermediate buffer first.

[mohyazdanpanah]

@pveentjer Hello again, new chagne focus on:

1. Used Long.BYTES constant instead of hardcoded 8 for buffer size
2. Checked the return value of write() and handled the failure case
3. Added a second example demonstrating tryClaim() for zero-copy writes directly to the ring buffer
4. Emphasized buffer reuse by keeping the comment about pre-allocating cached buffers

[pveentjer]

Since the read example is a copy, I would drop it.

[pveentjer]

I'm scratching my head on this one. Typically you never want to run into an exception on the fast path because they are very slow (e.g. tons of litter). So I'm not sure if guarding the tryClaim should be guarded in this manner. I'm going to ask and will get back to you.

[pveentjer]

The javadoc of the tryClaim is very clear about it. And there should indeed by a try/catch block.

[pveentjer]

Thanks for your efforts on this PR. It is heading in the right direction.

[mohyazdanpanah]

Thanks for your efforts on this PR. It is heading in the right direction.

Appreciate the feedback — I’ll push the next improvements shortly.

[mohyazdanpanah]

@pveentjer latest change is:

1. Removed the duplicate read example from the tryClaim section (as suggested in the review)
2. Kept the try/catch block around tryClaim as it's documented behavior
3. Maintained clear separation between the two usage patterns (write vs. tryClaim)

[pveentjer]

I see that the tryClaim already has usage documentation. So having it in the header is just duplication.

Could you move the documentation of the read and write to the method level instead of the class level so it is consistent with the tryClaim.

[mohyazdanpanah]

good point, It's done. I just move it and in class level read and write. also some other change, if it's not good please let me know to rellong back this changes

[pveentjer]

If I would be a noob, I could interpret this as: I can do non blocking writes using write(...), but tryClaim is blocking but zero copy?

In other words, the way this is phrased, can cause confusion.