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 17989eceec6eda422c2bb677b4ee3c6027354d3b
Author: wangjianyu3 <[email protected]>
AuthorDate: Fri May 29 14:53:12 2026 +0800

    include/ring: report net occupancy delta from overwrite enqueue
    
    ring_*_enqueue_overwrite() guarantees the new element is admitted by
    silently evicting older committed elements when the ring is full.
    Until now that loss was invisible to callers: the function returned
    the number of bytes admitted (always == count * elem_size) and gave
    no way to learn how many bytes the eviction took with it.  For users
    that care about end-to-end accounting (note backends in particular)
    this turned overwrite enqueue into a black box.
    
    Surface the eviction count by folding it into the return value:
    
     - ring_sp_enqueue_overwrite_start() / ring_mp_enqueue_overwrite_start()
       now return uint32_t, the number of elements evicted to make room
       for the request.  The MP variant accumulates evictions across
       multiple CAS retries when more than one tail block has to be
       reclaimed before head can advance.  Zero-copy callers can pair
       the start() return value with their own bookkeeping.
    
     - ring_sp_enqueue_overwrite() / ring_mp_enqueue_overwrite() capture
       the start() return value and now return buf.cnt - discard, i.e.
       the net change in ring occupancy rather than the gross number of
       elements written.  When the ring is not full this still equals
       count; when it is full the caller can compute eviction loss as
       count - return.  The macros ring_spmc_enqueue_overwrite /
       ring_mpmc_enqueue_overwrite are unchanged at the call site syntax
       level.
    
    This is a generic ring extension; the first consumer (notebuf folding
    the count into drop_bytes) is added in a separate patch.
    
    Signed-off-by: wangjianyu3 <[email protected]>
---
 include/nuttx/ring.h | 38 +++++++++++++++++++++++++++++---------
 1 file changed, 29 insertions(+), 9 deletions(-)

diff --git a/include/nuttx/ring.h b/include/nuttx/ring.h
index 2d810febc1c..15324c3d140 100644
--- a/include/nuttx/ring.h
+++ b/include/nuttx/ring.h
@@ -1301,16 +1301,19 @@ ring_mc_dequeue_skip(FAR struct ring_s *r, uint32_t 
count)
  *   if needed, then initialize ring_buf_s for zero-copy write.
  *   Caller writes data into buf, then calls ring_sp_finish.
  *
+ *   Returns the number of elements evicted from the ring to make room
+ *   for the request; zero if the ring had enough free space.
+ *
  ****************************************************************************/
 
-static inline_function void
+static inline_function uint32_t
 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 discard = 0;
   uint32_t old_cons;
   uint32_t new_cons;
 
@@ -1344,13 +1347,18 @@ ring_sp_enqueue_overwrite_start(FAR struct ring_s *r, 
uint32_t count,
     }
 
   ring_buf_init(buf, r, prod_idx, count, elem_size);
+  return discard;
 }
 
 /****************************************************************************
  * Name: ring_sp_enqueue_overwrite
  *
  * Description:
- *   Single-producer overwrite enqueue (copy variant).
+ *   Single-producer overwrite enqueue (copy variant).  Returns the net
+ *   number of elements added to the ring (count - discarded);
+ *   when the ring was full, the count of evicted elements is subtracted
+ *   from the inserted count so the caller sees the true delta in
+ *   ring occupancy.
  *
  ****************************************************************************/
 
@@ -1359,14 +1367,15 @@ 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;
+  uint32_t discard;
 
-  ring_sp_enqueue_overwrite_start(r, count, elem_size, &buf);
+  discard = 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;
+  return buf.cnt - discard;
 }
 
 /****************************************************************************
@@ -1378,9 +1387,12 @@ ring_sp_enqueue_overwrite(FAR struct ring_s *r, FAR 
const void *items,
  *   ring_buf_s for zero-copy write. Caller writes data into buf,
  *   then calls ring_mp_finish.
  *
+ *   Returns the total number of elements evicted from the ring across
+ *   all retry rounds; zero if the ring had enough free space.
+ *
  ****************************************************************************/
 
-static inline_function void
+static inline_function uint32_t
 ring_mp_enqueue_overwrite_start(FAR struct ring_s *r, uint32_t count,
                                 size_t elem_size, FAR struct ring_buf_s *buf)
 {
@@ -1390,6 +1402,7 @@ ring_mp_enqueue_overwrite_start(FAR struct ring_s *r, 
uint32_t count,
   uint32_t cons_idx;
   uint32_t free_space;
   uint32_t discard;
+  uint32_t all_discard = 0;
   uint32_t old_cons;
   uint32_t new_cons;
 
@@ -1432,6 +1445,7 @@ ring_mp_enqueue_overwrite_start(FAR struct ring_s *r, 
uint32_t count,
 
           ring_buf_init(buf, r, cons_idx, discard, elem_size);
           ring_mc_finish(r, buf);
+          all_discard += discard;
 
           old_prod = atomic_read(&r->prod_head);
           prod_idx = RTS_IDX(old_prod);
@@ -1445,13 +1459,18 @@ ring_mp_enqueue_overwrite_start(FAR struct ring_s *r, 
uint32_t count,
     }
 
   ring_buf_init(buf, r, prod_idx, count, elem_size);
+  return all_discard;
 }
 
 /****************************************************************************
  * Name: ring_mp_enqueue_overwrite
  *
  * Description:
- *   Multi-producer overwrite enqueue (copy variant).
+ *   Multi-producer overwrite enqueue (copy variant).  Returns the net
+ *   number of elements added to the ring (count - discarded);
+ *   when the ring was full, the count of evicted elements is subtracted
+ *   from the inserted count so the caller sees the true delta in
+ *   ring occupancy.
  *
  ****************************************************************************/
 
@@ -1460,14 +1479,15 @@ 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;
+  uint32_t discard;
 
-  ring_mp_enqueue_overwrite_start(r, count, elem_size, &buf);
+  discard = 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;
+  return buf.cnt - discard;
 }
 
 #endif /* __INCLUDE_NUTTX_RING_H */

Reply via email to