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 f63125df0bd8d9da596f7688274e3197d8d5f993 Author: chenzihan1 <[email protected]> AuthorDate: Wed Sep 2 21:09:17 2026 +0800 include/ring: add all-or-nothing bulk enqueue/dequeue None bluk is best-effort: it takes as much as fits and reports how much that was. That suits a byte stream, where a short write only shortens the data, but not a framed one, where the reader locates each record by a length field carried in the record before it. A fragment left in the ring desynchronises the reader from the frame boundaries, so every later record is misparsed - the ring is not one record short, its whole remaining content is lost. Callers can pre-check ring_space() and skip the enqueue themselves, but that reads the consumer index twice for what is one decision, and every caller with a framed payload has to repeat it. Add a bulk variant that reserves count slots or none at all, so buf.cnt comes back as count or 0 and never as a prefix. Signed-off-by: chenzihan1 <[email protected]> --- include/nuttx/ring.h | 294 +++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 262 insertions(+), 32 deletions(-) diff --git a/include/nuttx/ring.h b/include/nuttx/ring.h index daabe3c615a..00377e1eee4 100644 --- a/include/nuttx/ring.h +++ b/include/nuttx/ring.h @@ -60,6 +60,29 @@ * ring_spsc_enqueue(&g_ring, &val, 1); * ring_spsc_dequeue(&g_ring, &out, 1); * + * Enqueue takes as much as fits and reports how much that was. When the + * payload is indivisible - a framed record whose reader splits on a length + * field, say - use the bulk form instead: it takes all of it or none, and + * returns count or 0, so the ring never holds a fragment: + * ring_spsc_enqueue_bulk(&g_ring, buf, n, &space); // n or 0 + * ring_mpsc_enqueue_bulk(&g_ring, buf, n, &space); + * ring_spmc_enqueue_bulk(&g_ring, buf, n, &space); + * ring_mpmc_enqueue_bulk(&g_ring, buf, n, NULL); + * + * Dequeue mirrors this. The bulk form returns count or 0 and leaves an + * incomplete record in the ring for a later pass, rather than handing back + * part of one. On the MC forms it also closes a race a hand-rolled + * ring_count() test cannot: the check sits inside the CAS: + * ring_spsc_dequeue_bulk(&g_ring, buf, n, &avail); // n or 0 + * ring_mpsc_dequeue_bulk(&g_ring, buf, n, &avail); + * ring_spmc_dequeue_bulk(&g_ring, buf, n, &avail); + * ring_mpmc_dequeue_bulk(&g_ring, buf, n, NULL); + * + * The bulk forms take one extra argument, NULL to decline it: the space + * (enqueue) or readable count (dequeue) left after the call, saving a + * follow-up ring_space() / ring_count(). Only a hint on the MP/MC forms, + * where a rival may claim more right after the reservation lands. + * * MPSC - Multiple Producers, Single Consumer: * ring_mpsc_enqueue(&g_ring, &val, 1); * ring_mpsc_dequeue(&g_ring, &out, 1); @@ -104,11 +127,19 @@ * buf.len2 * elem_size); * ring_spsc_enqueue_finish(&g_ring, &buf); * + * ring_spsc_enqueue_start_bulk(&g_ring, count, elem_size, NULL, &buf); + * if (buf.cnt != 0) + * { ... fill and finish as above ... } + * * // Dequeue (all modes): * ring_spsc_dequeue_start(&g_ring, count, elem_size, &buf); * // Read from buf.ptr1 (len1) and buf.ptr2 (len2) * ring_spsc_dequeue_finish(&g_ring, &buf); * + * ring_spsc_dequeue_start_bulk(&g_ring, count, elem_size, NULL, &buf); + * if (buf.cnt != 0) + * { ... read and finish as above ... } + * * 6. Zero-copy overwrite (start/finish pattern): * * struct ring_buf_s buf; @@ -229,31 +260,57 @@ (ring_is_ready(r) ? \ ring_sp_enqueue(r, items, count, sizeof(*(items))) : 0) +#define ring_spsc_enqueue_bulk(r, items, count, space) \ + (ring_is_ready(r) ? \ + ring_sp_enqueue_bulk(r, items, count, sizeof(*(items)), space) : 0) + #define ring_spsc_dequeue(r, items, count) \ (ring_is_ready(r) ? \ ring_sc_dequeue(r, items, count, sizeof(*(items))) : 0) +#define ring_spsc_dequeue_bulk(r, items, count, avail) \ + (ring_is_ready(r) ? \ + ring_sc_dequeue_bulk(r, items, count, sizeof(*(items)), avail) : 0) + #define ring_spsc_skip(r, count) \ (ring_is_ready(r) ? ring_sc_skip(r, count) : 0) #define ring_mpmc_enqueue(r, items, count) \ ring_mp_enqueue(r, items, count, sizeof(*(items))) +#define ring_mpmc_enqueue_bulk(r, items, count, space) \ + ring_mp_enqueue_bulk(r, items, count, sizeof(*(items)), space) + #define ring_mpmc_dequeue(r, items, count) \ ring_mc_dequeue(r, items, count, sizeof(*(items))) +#define ring_mpmc_dequeue_bulk(r, items, count, avail) \ + ring_mc_dequeue_bulk(r, items, count, sizeof(*(items)), avail) + #define ring_spmc_enqueue(r, items, count) \ ring_sp_enqueue(r, items, count, sizeof(*(items))) +#define ring_spmc_enqueue_bulk(r, items, count, space) \ + ring_sp_enqueue_bulk(r, items, count, sizeof(*(items)), space) + #define ring_spmc_dequeue(r, items, count) \ ring_mc_dequeue(r, items, count, sizeof(*(items))) +#define ring_spmc_dequeue_bulk(r, items, count, avail) \ + ring_mc_dequeue_bulk(r, items, count, sizeof(*(items)), avail) + #define ring_mpsc_enqueue(r, items, count) \ ring_mp_enqueue(r, items, count, sizeof(*(items))) +#define ring_mpsc_enqueue_bulk(r, items, count, space) \ + ring_mp_enqueue_bulk(r, items, count, sizeof(*(items)), space) + #define ring_mpsc_dequeue(r, items, count) \ ring_sc_dequeue(r, items, count, sizeof(*(items))) +#define ring_mpsc_dequeue_bulk(r, items, count, avail) \ + ring_sc_dequeue_bulk(r, items, count, sizeof(*(items)), avail) + #define ring_mpmc_skip(r, count) ring_mc_skip(r, count) #define ring_spmc_skip(r, count) ring_mc_skip(r, count) #define ring_mpsc_skip(r, count) ring_sc_skip(r, count) @@ -290,42 +347,66 @@ #define ring_mpmc_overwrite_finish(r, b) ring_mp_finish(r, b) #define ring_spsc_enqueue_start(r, count, elem_size, b) \ - ring_sp_start(r, count, elem_size, b) + ring_sp_start(r, count, elem_size, false, NULL, b) + +#define ring_spsc_enqueue_start_bulk(r, count, elem_size, space, b) \ + ring_sp_start(r, count, elem_size, true, space, b) #define ring_spsc_enqueue_finish(r, b) ring_sp_finish(r, b) #define ring_spsc_dequeue_start(r, count, elem_size, b) \ - ring_sc_start(r, count, elem_size, b) + ring_sc_start(r, count, elem_size, false, NULL, b) + +#define ring_spsc_dequeue_start_bulk(r, count, elem_size, avail, b) \ + ring_sc_start(r, count, elem_size, true, avail, b) #define ring_spsc_dequeue_finish(r, b) ring_sc_finish(r, b) #define ring_mpmc_enqueue_start(r, count, elem_size, b) \ - ring_mp_start(r, count, elem_size, b) + ring_mp_start(r, count, elem_size, false, NULL, b) + +#define ring_mpmc_enqueue_start_bulk(r, count, elem_size, space, b) \ + ring_mp_start(r, count, elem_size, true, space, b) #define ring_mpmc_enqueue_finish(r, b) ring_mp_finish(r, b) #define ring_mpmc_dequeue_start(r, count, elem_size, b) \ - ring_mc_start(r, count, elem_size, b) + ring_mc_start(r, count, elem_size, false, NULL, b) + +#define ring_mpmc_dequeue_start_bulk(r, count, elem_size, avail, b) \ + ring_mc_start(r, count, elem_size, true, avail, b) #define ring_mpmc_dequeue_finish(r, b) ring_mc_finish(r, b) #define ring_spmc_enqueue_start(r, count, elem_size, b) \ - ring_sp_start(r, count, elem_size, b) + ring_sp_start(r, count, elem_size, false, NULL, b) + +#define ring_spmc_enqueue_start_bulk(r, count, elem_size, space, b) \ + ring_sp_start(r, count, elem_size, true, space, b) #define ring_spmc_enqueue_finish(r, b) ring_sp_finish(r, b) #define ring_spmc_dequeue_start(r, count, elem_size, b) \ - ring_mc_start(r, count, elem_size, b) + ring_mc_start(r, count, elem_size, false, NULL, b) + +#define ring_spmc_dequeue_start_bulk(r, count, elem_size, avail, b) \ + ring_mc_start(r, count, elem_size, true, avail, b) #define ring_spmc_dequeue_finish(r, b) ring_mc_finish(r, b) #define ring_mpsc_enqueue_start(r, count, elem_size, b) \ - ring_mp_start(r, count, elem_size, b) + ring_mp_start(r, count, elem_size, false, NULL, b) + +#define ring_mpsc_enqueue_start_bulk(r, count, elem_size, space, b) \ + ring_mp_start(r, count, elem_size, true, space, b) #define ring_mpsc_enqueue_finish(r, b) ring_mp_finish(r, b) #define ring_mpsc_dequeue_start(r, count, elem_size, b) \ - ring_sc_start(r, count, elem_size, b) + ring_sc_start(r, count, elem_size, false, NULL, b) + +#define ring_mpsc_dequeue_start_bulk(r, count, elem_size, avail, b) \ + ring_sc_start(r, count, elem_size, true, avail, b) #define ring_mpsc_dequeue_finish(r, b) ring_sc_finish(r, b) @@ -998,19 +1079,30 @@ ring_copy_to(FAR struct ring_buf_s *buf, FAR void *items, size_t elem_size) ****************************************************************************/ static inline_function void -ring_sp_start(FAR struct ring_s *r, uint32_t count, - size_t elem_size, FAR struct ring_buf_s *buf) +ring_sp_start(FAR struct ring_s *r, uint32_t count, size_t elem_size, + bool bulk, FAR uint32_t *space, FAR struct ring_buf_s *buf) { FAR struct ring_blob_s *blob = r->blob; uint32_t prod_index = RTS_IDX(blob->prod_tail); uint32_t cons_index; - uint32_t free_space; - uint32_t n; + uint32_t used; + uint32_t free_space = 0; + uint32_t n = 0; UP_RMB(); cons_index = RTS_IDX(blob->cons_tail); - free_space = blob->capacity - ring_dist(r, prod_index, cons_index); - n = count < free_space ? count : free_space; + used = ring_dist(r, prod_index, cons_index); + + if (used <= blob->capacity) + { + free_space = blob->capacity - used; + n = count <= free_space ? count : (bulk ? 0 : free_space); + } + + if (space != NULL) + { + *space = free_space - n; + } ring_buf_init(buf, r, prod_index, n, elem_size); } @@ -1025,22 +1117,31 @@ ring_sp_start(FAR struct ring_s *r, uint32_t count, ****************************************************************************/ static inline_function void -ring_mp_start(FAR struct ring_s *r, uint32_t count, - size_t elem_size, FAR struct ring_buf_s *buf) +ring_mp_start(FAR struct ring_s *r, uint32_t count, size_t elem_size, + bool bulk, FAR uint32_t *space, FAR struct ring_buf_s *buf) { FAR struct ring_blob_s *blob = r->blob; uint32_t old_head; uint32_t new_head; + uint32_t free_space; uint32_t n; old_head = atomic_read(&blob->prod_head); do { uint32_t cons_index = RTS_IDX(atomic_read_acquire(&blob->cons_tail)); - uint32_t free_space = blob->capacity - - ring_dist(r, RTS_IDX(old_head), cons_index); + uint32_t used = ring_dist(r, RTS_IDX(old_head), cons_index); - n = count < free_space ? count : free_space; + if (used > blob->capacity) + { + free_space = 0; + n = 0; + break; + } + + free_space = blob->capacity - used; + + n = count <= free_space ? count : (bulk ? 0 : free_space); if (n == 0) { break; @@ -1051,6 +1152,11 @@ ring_mp_start(FAR struct ring_s *r, uint32_t count, } while (!atomic_cmpxchg_relaxed(&blob->prod_head, &old_head, new_head)); + if (space != NULL) + { + *space = free_space - n; + } + ring_buf_init(buf, r, RTS_IDX(old_head), n, elem_size); } @@ -1064,8 +1170,8 @@ ring_mp_start(FAR struct ring_s *r, uint32_t count, ****************************************************************************/ static inline_function void -ring_sc_start(FAR struct ring_s *r, uint32_t count, - size_t elem_size, FAR struct ring_buf_s *buf) +ring_sc_start(FAR struct ring_s *r, uint32_t count, size_t elem_size, + bool bulk, FAR uint32_t *avail, FAR struct ring_buf_s *buf) { FAR struct ring_blob_s *blob = r->blob; uint32_t cons_index = RTS_IDX(blob->cons_tail); @@ -1086,7 +1192,16 @@ ring_sc_start(FAR struct ring_s *r, uint32_t count, if (available <= blob->capacity) { - n = count < available ? count : available; + n = count <= available ? count : (bulk ? 0 : available); + } + else + { + available = 0; + } + + if (avail != NULL) + { + *avail = available - n; } ring_buf_init(buf, r, cons_index, n, elem_size); @@ -1102,19 +1217,21 @@ ring_sc_start(FAR struct ring_s *r, uint32_t count, ****************************************************************************/ static inline_function void -ring_mc_start(FAR struct ring_s *r, uint32_t count, - size_t elem_size, FAR struct ring_buf_s *buf) +ring_mc_start(FAR struct ring_s *r, uint32_t count, size_t elem_size, + bool bulk, FAR uint32_t *avail, FAR struct ring_buf_s *buf) { FAR struct ring_blob_s *blob = r->blob; uint32_t old_head; uint32_t new_head; + uint32_t available; uint32_t n; old_head = atomic_read(&blob->cons_head); do { uint32_t prod_index = RTS_IDX(atomic_read_acquire(&blob->prod_tail)); - uint32_t available = ring_dist(r, prod_index, RTS_IDX(old_head)); + + available = ring_dist(r, prod_index, RTS_IDX(old_head)); /* available > capacity is physically impossible for a consistent * ring; it can only result from a torn snapshot where prod_tail is @@ -1125,11 +1242,12 @@ ring_mc_start(FAR struct ring_s *r, uint32_t count, if (available > blob->capacity) { + available = 0; n = 0; break; } - n = count < available ? count : available; + n = count <= available ? count : (bulk ? 0 : available); if (n == 0) { break; @@ -1140,6 +1258,11 @@ ring_mc_start(FAR struct ring_s *r, uint32_t count, } while (!atomic_cmpxchg_relaxed(&blob->cons_head, &old_head, new_head)); + if (avail != NULL) + { + *avail = available - n; + } + ring_buf_init(buf, r, RTS_IDX(old_head), n, elem_size); } @@ -1455,7 +1578,33 @@ ring_sp_enqueue(FAR struct ring_s *r, FAR const void *items, { struct ring_buf_s buf; - ring_sp_start(r, count, elem_size, &buf); + ring_sp_start(r, count, elem_size, false, NULL, &buf); + ring_copy_from(&buf, items, elem_size); + ring_sp_finish(r, &buf); + + return buf.cnt; +} + +/**************************************************************************** + * Name: ring_sp_enqueue_bulk + * + * Description: + * Single-producer all-or-nothing enqueue. Either every element goes in or + * none does, so the ring never holds a fragment of an indivisible payload. + * + * Returned Value: + * count on success, 0 if the ring could not take the whole payload. + * + ****************************************************************************/ + +static inline_function uint32_t +ring_sp_enqueue_bulk(FAR struct ring_s *r, FAR const void *items, + uint32_t count, size_t elem_size, + FAR uint32_t *space) +{ + struct ring_buf_s buf; + + ring_sp_start(r, count, elem_size, true, space, &buf); ring_copy_from(&buf, items, elem_size); ring_sp_finish(r, &buf); @@ -1482,7 +1631,33 @@ ring_mp_enqueue(FAR struct ring_s *r, FAR const void *items, { struct ring_buf_s buf; - ring_mp_start(r, count, elem_size, &buf); + ring_mp_start(r, count, elem_size, false, NULL, &buf); + ring_copy_from(&buf, items, elem_size); + ring_mp_finish(r, &buf); + + return buf.cnt; +} + +/**************************************************************************** + * Name: ring_mp_enqueue_bulk + * + * Description: + * Multi-producer all-or-nothing enqueue. As ring_sp_enqueue_bulk, over + * the RTS CAS protocol. + * + * Returned Value: + * count on success, 0 if the ring could not take the whole payload. + * + ****************************************************************************/ + +static inline_function uint32_t +ring_mp_enqueue_bulk(FAR struct ring_s *r, FAR const void *items, + uint32_t count, size_t elem_size, + FAR uint32_t *space) +{ + struct ring_buf_s buf; + + ring_mp_start(r, count, elem_size, true, space, &buf); ring_copy_from(&buf, items, elem_size); ring_mp_finish(r, &buf); @@ -1503,7 +1678,34 @@ ring_sc_dequeue(FAR struct ring_s *r, FAR void *items, { struct ring_buf_s buf; - ring_sc_start(r, count, elem_size, &buf); + ring_sc_start(r, count, elem_size, false, NULL, &buf); + ring_copy_to(&buf, items, elem_size); + ring_sc_finish(r, &buf); + + return buf.cnt; +} + +/**************************************************************************** + * Name: ring_sc_dequeue_bulk + * + * Description: + * Single-consumer all-or-nothing dequeue. Either every element comes out + * or none does, leaving an incomplete record in the ring for a later pass + * rather than handing the caller a fragment of it. + * + * Returned Value: + * count on success, 0 if the ring did not hold that many elements. + * + ****************************************************************************/ + +static inline_function uint32_t +ring_sc_dequeue_bulk(FAR struct ring_s *r, FAR void *items, + uint32_t count, size_t elem_size, + FAR uint32_t *avail) +{ + struct ring_buf_s buf; + + ring_sc_start(r, count, elem_size, true, avail, &buf); ring_copy_to(&buf, items, elem_size); ring_sc_finish(r, &buf); @@ -1527,7 +1729,35 @@ ring_mc_dequeue(FAR struct ring_s *r, FAR void *items, { struct ring_buf_s buf; - ring_mc_start(r, count, elem_size, &buf); + ring_mc_start(r, count, elem_size, false, NULL, &buf); + ring_copy_to(&buf, items, elem_size); + ring_mc_finish(r, &buf); + + return buf.cnt; +} + +/**************************************************************************** + * Name: ring_mc_dequeue_bulk + * + * Description: + * Multi-consumer all-or-nothing dequeue. As ring_sc_dequeue_bulk, over + * the RTS CAS protocol - and unlike a ring_count() test the caller could + * write itself, the check happens inside the CAS loop, so a rival consumer + * cannot take the data in between. + * + * Returned Value: + * count on success, 0 if the ring did not hold that many elements. + * + ****************************************************************************/ + +static inline_function uint32_t +ring_mc_dequeue_bulk(FAR struct ring_s *r, FAR void *items, + uint32_t count, size_t elem_size, + FAR uint32_t *avail) +{ + struct ring_buf_s buf; + + ring_mc_start(r, count, elem_size, true, avail, &buf); ring_copy_to(&buf, items, elem_size); ring_mc_finish(r, &buf); @@ -1548,7 +1778,7 @@ ring_sc_skip(FAR struct ring_s *r, uint32_t count) { struct ring_buf_s buf; - ring_sc_start(r, count, 0, &buf); + ring_sc_start(r, count, 0, false, NULL, &buf); ring_sc_finish(r, &buf); return buf.cnt; @@ -1593,7 +1823,7 @@ ring_mc_skip(FAR struct ring_s *r, uint32_t count) { struct ring_buf_s buf; - ring_mc_start(r, count, 0, &buf); + ring_mc_start(r, count, 0, false, NULL, &buf); ring_mc_finish(r, &buf); return buf.cnt;
