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 *
