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 e55e5026b0b894339c83893c5b006d46327bef02 Author: chenzihan1 <[email protected]> AuthorDate: Fri May 29 11:21:27 2026 +0800 ring: add ring_sc_peek/ring_mc_peek for peek with external index Add two peek functions that read data from the ring using a caller- managed index without advancing cons_tail: - ring_sc_peek: single-consumer peek, no retry, suitable for SC or panic-path scenarios where overwrite race is not a concern. - ring_mc_peek: multi-consumer peek with optimistic-read-then-verify loop, retries automatically if the read region was overwritten during copy. Signed-off-by: chenzihan1 <[email protected]> --- include/nuttx/ring.h | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 140 insertions(+), 1 deletion(-) diff --git a/include/nuttx/ring.h b/include/nuttx/ring.h index 0023a17c6aa..2d810febc1c 100644 --- a/include/nuttx/ring.h +++ b/include/nuttx/ring.h @@ -209,7 +209,6 @@ */ #define RING_DECLARE(name, type, cap) \ - static_assert((cap) > 0, "ring cap must be > 0"); \ struct ring_##name##_s \ { \ struct ring_s base; \ @@ -316,6 +315,20 @@ #define ring_capacity(r) (RING_BASE(r)->capacity) #define ring_space(r) (ring_capacity(r) - ring_count(r)) +/* Check whether cons_index is still valid (not overwritten). + * Returns true if cons_index >= current cons_tail (data still valid). + */ + +#define ring_is_valid_cons(cons_index, cons_tail) \ + ((int32_t)((cons_index) - (cons_tail)) >= 0) + +/* Clamp an external index if it fell behind cons_tail (overwritten). + * Returns the effective read position. + */ + +#define ring_clamp_cons(cons_index, cons_tail) \ + (ring_is_valid_cons(cons_index, cons_tail) ? (cons_index) : (cons_tail)) + #define ring_spsc_enqueue(r, items, count) \ (ring_is_ready(r) ? \ ring_sp_enqueue(RING_BASE(r), items, count, sizeof(*(items))) : 0) @@ -431,6 +444,18 @@ #define ring_mpsc_dequeue_finish(r, b) \ ring_sc_finish(RING_BASE(r), b) +#define ring_mpsc_peek(r, items, count, index) \ + ring_sc_peek(RING_BASE(r), items, count, sizeof(*(items)), index) + +#define ring_spsc_peek(r, items, count, index) \ + ring_sc_peek(RING_BASE(r), items, count, sizeof(*(items)), index) + +#define ring_mpmc_peek(r, items, count, index) \ + ring_mc_peek(RING_BASE(r), items, count, sizeof(*(items)), index) + +#define ring_spmc_peek(r, items, count, index) \ + ring_mc_peek(RING_BASE(r), items, count, sizeof(*(items)), index) + /**************************************************************************** * Public Types ****************************************************************************/ @@ -982,6 +1007,120 @@ ring_sc_finish(FAR struct ring_s *r, FAR struct ring_buf_s *buf) } } +/**************************************************************************** + * Name: ring_sc_peek + * + * Description: + * Single-consumer peek with external index. Read data from ring + * without advancing cons_tail. The caller's index tracks the read + * position independently. + * + * Returned Value: + * Number of elements peeked. + * + ****************************************************************************/ + +static inline_function uint32_t +ring_sc_peek(FAR struct ring_s *r, FAR void *items, uint32_t count, + size_t elem_size, FAR uint32_t *index) +{ + uint32_t cons_index; + uint32_t prod_index; + uint32_t available; + uint32_t n; + + cons_index = RTS_IDX(RING_FIELD(&r->cons_tail)); + if (index) + { + cons_index = ring_clamp_cons(*index, cons_index); + } + + UP_RMB(); + prod_index = RTS_IDX(RING_FIELD(&r->prod_tail)); + available = RTS_IDX(prod_index - cons_index); + n = count < available ? count : available; + + if (items) + { + struct ring_buf_s buf; + + ring_buf_init(&buf, r, cons_index, n, elem_size); + ring_copy_to(&buf, items, elem_size); + cons_index = RTS_IDX(cons_index + n); + } + + if (index) + { + *index = cons_index; + } + + return n; +} + +/**************************************************************************** + * Name: ring_mc_peek + * + * Description: + * Multi-consumer peek with external index and overwrite detection. + * Uses optimistic-read-then-verify to ensure data consistency when + * producers may overwrite the region being read. + * + * Returned Value: + * Number of elements peeked. + * + ****************************************************************************/ + +static inline_function uint32_t +ring_mc_peek(FAR struct ring_s *r, FAR void *items, uint32_t count, + size_t elem_size, FAR uint32_t *index) +{ + uint32_t cons_index; + uint32_t n; + + do + { + struct ring_buf_s buf; + uint32_t prod_index; + uint32_t available; + + cons_index = RTS_IDX(atomic_read_acquire(&r->cons_tail)); + if (index) + { + cons_index = ring_clamp_cons(*index, cons_index); + } + + prod_index = RTS_IDX(atomic_read_acquire(&r->prod_tail)); + available = RTS_IDX(prod_index - cons_index); + n = count < available ? count : available; + + if (n == 0 || !items) + { + break; + } + + ring_buf_init(&buf, r, cons_index, n, elem_size); + ring_copy_to(&buf, items, elem_size); + + /* Verify data wasn't overwritten during copy: + * If cons_tail advanced past our read position, retry. + */ + } + while (!ring_is_valid_cons(cons_index, + RTS_IDX(atomic_read_acquire(&r->cons_tail)))); + + if (items) + { + cons_index = RTS_IDX(cons_index + n); + } + + if (index) + { + *index = cons_index; + } + + return n; +} + /**************************************************************************** * Name: ring_mc_finish *
