This is an automated email from the ASF dual-hosted git repository.

xiaoxiang781216 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git

commit ca5b9296475eddabfe7d1eda3c2073682623b96d
Author: Bowen Wang <[email protected]>
AuthorDate: Mon Jun 22 21:37:44 2026 +0800

    ring: add offset-relative peek API
    
    The external-index peek requires callers to handle absolute ring indices,
    which forces scanners that inspect buffer contents to reach into ring
    internals.  Add ring_*_peek_at(r, items, count, offset): it reads count
    elements at a fixed offset from the oldest element (cons_tail) without
    advancing, expressing the read position relative to the consumer tail so
    the caller never sees an absolute index.  An out-of-range offset yields
    zero.  Implemented by delegating to the existing single/multi-consumer
    peek primitives.
    
    Signed-off-by: Bowen Wang <[email protected]>
---
 include/nuttx/ring.h | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/include/nuttx/ring.h b/include/nuttx/ring.h
index 57d3eca23ef..23b64389480 100644
--- a/include/nuttx/ring.h
+++ b/include/nuttx/ring.h
@@ -493,6 +493,24 @@
 #define ring_spmc_peek(r, items, count, index) \
   ring_mc_peek(RING_BASE(r), items, count, sizeof(*(items)), index)
 
+/* Peek at a fixed offset from the oldest element (cons_tail), without
+ * advancing.  Unlike the external-index peek above, the read position is
+ * expressed relative to the consumer tail, so the caller never handles
+ * absolute ring indices.
+ */
+
+#define ring_mpsc_peek_at(r, items, count, offset) \
+  ring_sc_peek_at(RING_BASE(r), items, count, sizeof(*(items)), offset)
+
+#define ring_spsc_peek_at(r, items, count, offset) \
+  ring_sc_peek_at(RING_BASE(r), items, count, sizeof(*(items)), offset)
+
+#define ring_mpmc_peek_at(r, items, count, offset) \
+  ring_mc_peek_at(RING_BASE(r), items, count, sizeof(*(items)), offset)
+
+#define ring_spmc_peek_at(r, items, count, offset) \
+  ring_mc_peek_at(RING_BASE(r), items, count, sizeof(*(items)), offset)
+
 /****************************************************************************
  * Public Types
  ****************************************************************************/
@@ -1201,6 +1219,61 @@ ring_mc_peek(FAR struct ring_s *r, FAR void *items, 
uint32_t count,
   return n;
 }
 
+/****************************************************************************
+ * Name: ring_sc_peek_at
+ *
+ * Description:
+ *   Single-consumer peek at a byte/element offset measured from the oldest
+ *   element (cons_tail), without advancing.  The caller works purely in the
+ *   relative offset space and never sees an absolute ring index.
+ *
+ * Returned Value:
+ *   Number of elements peeked (0 if offset is out of range).
+ *
+ ****************************************************************************/
+
+static inline_function uint32_t
+ring_sc_peek_at(FAR struct ring_s *r, FAR void *items, uint32_t count,
+                size_t elem_size, uint32_t offset)
+{
+  uint32_t index;
+
+  if (offset >= ring_count(r))
+    {
+      return 0;
+    }
+
+  index = RTS_IDX(RING_FIELD(&r->cons_tail) + offset);
+  return ring_sc_peek(r, items, count, elem_size, &index);
+}
+
+/****************************************************************************
+ * Name: ring_mc_peek_at
+ *
+ * Description:
+ *   Multi-consumer counterpart of ring_sc_peek_at.  Peeks at an offset from
+ *   cons_tail with the same overwrite-safe semantics as ring_mc_peek.
+ *
+ * Returned Value:
+ *   Number of elements peeked (0 if offset is out of range).
+ *
+ ****************************************************************************/
+
+static inline_function uint32_t
+ring_mc_peek_at(FAR struct ring_s *r, FAR void *items, uint32_t count,
+                size_t elem_size, uint32_t offset)
+{
+  uint32_t index;
+
+  if (offset >= ring_count(r))
+    {
+      return 0;
+    }
+
+  index = RTS_IDX(atomic_read_acquire(&r->cons_tail) + offset);
+  return ring_mc_peek(r, items, count, elem_size, &index);
+}
+
 /****************************************************************************
  * Name: ring_mc_finish
  *

Reply via email to