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 f7f3229401599ec517f8b320b2c6626ee53ecc45 Author: Bowen Wang <[email protected]> AuthorDate: Thu Apr 30 09:50:57 2026 +0800 include/ring: add enqueue_overwrite API for SPMC/MPMC modes Add overwrite enqueue that discards oldest committed data when the ring is full, guaranteeing writes always succeed. Typical use case: sensor data streams and log buffers where latest data matters most. The discard path acts as a virtual multi-consumer (CAS on cons_head + mc_finish), so overwrite is only available for MC queues (SPMC/MPMC). SC queues cannot support overwrite because the producer must CAS cons_head, which conflicts with SC's plain-store protocol. Provides both copy and zero-copy (start/finish) variants: ring_spmc_enqueue_overwrite / ring_mpmc_enqueue_overwrite ring_spmc_enqueue_overwrite_start / ring_spmc_enqueue_overwrite_finish ring_mpmc_enqueue_overwrite_start / ring_mpmc_enqueue_overwrite_finish Signed-off-by: Bowen Wang <[email protected]> --- include/nuttx/ring.h | 205 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 205 insertions(+) diff --git a/include/nuttx/ring.h b/include/nuttx/ring.h index cb1613e8e05..4ac14d15100 100644 --- a/include/nuttx/ring.h +++ b/include/nuttx/ring.h @@ -223,6 +223,34 @@ #define ring_mpsc_dequeue_skip(r, count) \ ring_sc_dequeue_skip(RING_BASE(r), count) +/* Overwrite enqueue: when the ring is full, discard oldest data to + * make room. The discard path acts as a virtual multi-consumer, + * so the dequeue side MUST use MC protocol (ring_spmc_dequeue or + * ring_mpmc_dequeue) regardless of the number of real consumers. + * + * Only available for MC queues (SPMC/MPMC). SC queues cannot + * support overwrite because the producer must CAS cons_head to + * discard, which conflicts with SC's plain-store protocol. + */ + +#define ring_spmc_enqueue_overwrite(r, items, count) \ + ring_sp_enqueue_overwrite(RING_BASE(r), items, count, sizeof(*(items))) + +#define ring_mpmc_enqueue_overwrite(r, items, count) \ + ring_mp_enqueue_overwrite(RING_BASE(r), items, count, sizeof(*(items))) + +#define ring_spmc_enqueue_overwrite_start(r, count, elem_size, b) \ + ring_sp_enqueue_overwrite_start(RING_BASE(r), count, elem_size, b) + +#define ring_spmc_enqueue_overwrite_finish(r, b) \ + ring_sp_finish(RING_BASE(r), b) + +#define ring_mpmc_enqueue_overwrite_start(r, count, elem_size, b) \ + ring_mp_enqueue_overwrite_start(RING_BASE(r), count, elem_size, b) + +#define ring_mpmc_enqueue_overwrite_finish(r, b) \ + ring_mp_finish(RING_BASE(r), b) + #define ring_spsc_enqueue_start(r, count, elem_size, b) \ ring_sp_start(RING_BASE(r), count, elem_size, b) @@ -953,4 +981,181 @@ ring_mc_dequeue_skip(FAR struct ring_s *r, uint32_t count) return buf.cnt; } +/**************************************************************************** + * Name: ring_sp_enqueue_overwrite_start + * + * Description: + * Single-producer overwrite start. Discard oldest committed data + * if needed, then initialize ring_buf_s for zero-copy write. + * Caller writes data into buf, then calls ring_sp_finish. + * + ****************************************************************************/ + +static inline_function void +ring_sp_enqueue_overwrite_start(FAR struct ring_s *r, uint32_t count, + size_t elem_size, FAR struct ring_buf_s *buf) +{ + uint32_t prod_idx; + uint32_t cons_idx; + uint32_t free_space; + uint32_t discard; + uint32_t old_cons; + uint32_t new_cons; + + if (count > r->capacity) + { + count = r->capacity; + } + + prod_idx = RTS_IDX(atomic_read(&r->prod_tail)); + + for (; ; ) + { + old_cons = atomic_read_acquire(&r->cons_head); + cons_idx = RTS_IDX(old_cons); + free_space = r->capacity - + ((prod_idx - cons_idx) & RING_IDX_MASK); + + if (free_space >= count) + { + break; + } + + discard = count - free_space; + new_cons = RTS_PACK(RTS_CNT(old_cons) + 1, cons_idx + discard); + if (atomic_cmpxchg_relaxed(&r->cons_head, &old_cons, new_cons)) + { + ring_buf_init(buf, r, cons_idx, discard, elem_size); + ring_mc_finish(r, buf); + break; + } + } + + ring_buf_init(buf, r, prod_idx, count, elem_size); +} + +/**************************************************************************** + * Name: ring_sp_enqueue_overwrite + * + * Description: + * Single-producer overwrite enqueue (copy variant). + * + ****************************************************************************/ + +static inline_function uint32_t +ring_sp_enqueue_overwrite(FAR struct ring_s *r, FAR const void *items, + uint32_t count, size_t elem_size) +{ + struct ring_buf_s buf; + + ring_sp_enqueue_overwrite_start(r, count, elem_size, &buf); + ring_copy_from(&buf, + (FAR const char *)items + (count - buf.cnt) * elem_size, + elem_size); + ring_sp_finish(r, &buf); + + return buf.cnt; +} + +/**************************************************************************** + * Name: ring_mp_enqueue_overwrite_start + * + * Description: + * Multi-producer overwrite start. Discard oldest committed data + * if needed, reserve producer slots via CAS, then initialize + * ring_buf_s for zero-copy write. Caller writes data into buf, + * then calls ring_mp_finish. + * + ****************************************************************************/ + +static inline_function void +ring_mp_enqueue_overwrite_start(FAR struct ring_s *r, uint32_t count, + size_t elem_size, FAR struct ring_buf_s *buf) +{ + uint32_t old_prod; + uint32_t new_prod; + uint32_t prod_idx; + uint32_t cons_idx; + uint32_t free_space; + uint32_t discard; + uint32_t old_cons; + uint32_t new_cons; + + if (count > r->capacity) + { + count = r->capacity; + } + + old_prod = atomic_read(&r->prod_head); + for (; ; ) + { + uint32_t prod_tail_idx; + + old_cons = atomic_read_acquire(&r->cons_head); + prod_tail_idx = RTS_IDX(atomic_read_acquire(&r->prod_tail)); + prod_idx = RTS_IDX(old_prod); + cons_idx = RTS_IDX(old_cons); + + free_space = r->capacity - + ((prod_idx - cons_idx) & RING_IDX_MASK); + + if (free_space < count) + { + uint32_t committed; + + committed = (prod_tail_idx - cons_idx) & RING_IDX_MASK; + discard = count - free_space; + if (discard > committed) + { + old_prod = atomic_read(&r->prod_head); + continue; + } + + new_cons = RTS_PACK(RTS_CNT(old_cons) + 1, cons_idx + discard); + if (!atomic_cmpxchg_relaxed(&r->cons_head, &old_cons, new_cons)) + { + old_prod = atomic_read(&r->prod_head); + continue; + } + + ring_buf_init(buf, r, cons_idx, discard, elem_size); + ring_mc_finish(r, buf); + + old_prod = atomic_read(&r->prod_head); + prod_idx = RTS_IDX(old_prod); + } + + new_prod = RTS_PACK(RTS_CNT(old_prod) + 1, prod_idx + count); + if (atomic_cmpxchg_relaxed(&r->prod_head, &old_prod, new_prod)) + { + break; + } + } + + ring_buf_init(buf, r, prod_idx, count, elem_size); +} + +/**************************************************************************** + * Name: ring_mp_enqueue_overwrite + * + * Description: + * Multi-producer overwrite enqueue (copy variant). + * + ****************************************************************************/ + +static inline_function uint32_t +ring_mp_enqueue_overwrite(FAR struct ring_s *r, FAR const void *items, + uint32_t count, size_t elem_size) +{ + struct ring_buf_s buf; + + ring_mp_enqueue_overwrite_start(r, count, elem_size, &buf); + ring_copy_from(&buf, + (FAR const char *)items + (count - buf.cnt) * elem_size, + elem_size); + ring_mp_finish(r, &buf); + + return buf.cnt; +} + #endif /* __INCLUDE_NUTTX_RING_H */
