rte_ring_rts.h

       Generated automatically by Doxygen for DPDK from the source code.

DPDK                                             Version 24.11.2                               rte_ring_rts.h(3)

       It is not recommended to include this file directly. Please include <rte_ring.h> instead.

       Contains functions for Relaxed Tail Sync (RTS) ring mode. The main idea remains the same as for our
       original MP/MC synchronization mechanism. The main difference is that tail value is increased not by
       every thread that finished enqueue/dequeue, but only by the current last one doing enqueue/dequeue. That
       allows threads to skip spinning on tail value, leaving actual tail value change to last thread at a given
       instance. RTS requires 2 64-bit CAS for each enqueue(/dequeue) operation: one for head update, second for
       tail update. As a gain it allows thread to avoid spinning/waiting on tail value. In comparison original
       MP/MC algorithm requires one 32-bit CAS for head update and waiting/spinning on tail value.

       Brief outline:

       • introduce update counter (cnt) for both head and tail.

       • increment head.cnt for each head.value update

       • write head.value and head.cnt atomically (64-bit CAS)

       • move  tail.value  ahead  only  when  tail.cnt  + 1 == head.cnt (indicating that this is the last thread
         updating the tail)

       • increment tail.cnt when each enqueue/dequeue op finishes (no matter if tail.value going  to  change  or
         not)

       • write tail.value and tail.cnt atomically (64-bit CAS)

       To avoid producer/consumer starvation:

       • limit  max  allowed  distance  between head and tail value (HTD_MAX). I.E. thread is allowed to proceed
         with changing head.value, only when:  head.value  -  tail.value  <=  HTD_MAX  HTD_MAX  is  an  optional
         parameter.  With HTD_MAX == 0 we'll have fully serialized ring - i.e. only one thread at a time will be
         able to enqueue/dequeue to/from the ring. With HTD_MAX >= ring.capacity -  no  limitation.  By  default
         HTD_MAX == ring.capacity / 8.

       Definition in file rte_ring_rts.h.

static__rte_always_inlineunsignedintrte_ring_mp_rts_enqueue_bulk_elem(structrte_ring*r,constvoid*obj_table,unsignedintesize,unsignedintn,unsignedint*free_space)[static]
       Enqueue several objects on the RTS ring (multi-producers safe).

       Parametersr A pointer to the ring structure.
           obj_table A pointer to a table of objects.
           esize The size of ring element, in bytes. It must be a multiple of 4. This must  be  the  same  value
           used while creating the ring. Otherwise the results are undefined.
           n The number of objects to add in the ring from the obj_table.
           free_space  if  non-NULL,  returns  the  amount  of space in the ring after the enqueue operation has
           finished.

       Returns
           The number of objects enqueued, either 0 or n

       Definition at line 80 of file rte_ring_rts.h.

   static__rte_always_inlineunsignedintrte_ring_mc_rts_dequeue_bulk_elem(structrte_ring*r,void*obj_table,unsignedintesize,unsignedintn,unsignedint*available)[static]
       Dequeue several objects from an RTS ring (multi-consumers safe).

       Parametersr A pointer to the ring structure.
           obj_table A pointer to a table of objects that will be filled.
           esize  The  size  of  ring element, in bytes. It must be a multiple of 4. This must be the same value
           used while creating the ring. Otherwise the results are undefined.
           n The number of objects to dequeue from the ring to the obj_table.
           available If non-NULL, returns the number of remaining ring entries after the dequeue has finished.

       Returns
           The number of objects dequeued, either 0 or n

       Definition at line 107 of file rte_ring_rts.h.

   static__rte_always_inlineunsignedintrte_ring_mp_rts_enqueue_burst_elem(structrte_ring*r,constvoid*obj_table,unsignedintesize,unsignedintn,unsignedint*free_space)[static]
       Enqueue several objects on the RTS ring (multi-producers safe).

       Parametersr A pointer to the ring structure.
           obj_table A pointer to a table of objects.
           esize The size of ring element, in bytes. It must be a multiple of 4. This must  be  the  same  value
           used while creating the ring. Otherwise the results are undefined.
           n The number of objects to add in the ring from the obj_table.
           free_space  if  non-NULL,  returns  the  amount  of space in the ring after the enqueue operation has
           finished.

       Returns

           • n: Actual number of objects enqueued.

       Definition at line 134 of file rte_ring_rts.h.

   static__rte_always_inlineunsignedintrte_ring_mc_rts_dequeue_burst_elem(structrte_ring*r,void*obj_table,unsignedintesize,unsignedintn,unsignedint*available)[static]
       Dequeue several objects from an RTS ring (multi-consumers safe). When the requested objects are more than
       the available objects, only dequeue the actual number of objects.

       Parametersr A pointer to the ring structure.
           obj_table A pointer to a table of objects that will be filled.
           esize  The  size  of  ring element, in bytes. It must be a multiple of 4. This must be the same value
           used while creating the ring. Otherwise the results are undefined.
           n The number of objects to dequeue from the ring to the obj_table.
           available If non-NULL, returns the number of remaining ring entries after the dequeue has finished.

       Returns

           • n: Actual number of objects dequeued, 0 if ring is empty

       Definition at line 163 of file rte_ring_rts.h.

   static__rte_always_inlineunsignedintrte_ring_mp_rts_enqueue_bulk(structrte_ring*r,void*const*obj_table,unsignedintn,unsignedint*free_space)[static]
       Enqueue several objects on the RTS ring (multi-producers safe).

       Parametersr A pointer to the ring structure.
           obj_table A pointer to a table of void * pointers (objects).
           n The number of objects to add in the ring from the obj_table.
           free_space  if  non-NULL,  returns  the  amount  of space in the ring after the enqueue operation has
           finished.

       Returns
           The number of objects enqueued, either 0 or n

       Definition at line 186 of file rte_ring_rts.h.

   static__rte_always_inlineunsignedintrte_ring_mc_rts_dequeue_bulk(structrte_ring*r,void**obj_table,unsignedintn,unsignedint*available)[static]
       Dequeue several objects from an RTS ring (multi-consumers safe).

       Parametersr A pointer to the ring structure.
           obj_table A pointer to a table of void * pointers (objects) that will be filled.
           n The number of objects to dequeue from the ring to the obj_table.
           available If non-NULL, returns the number of remaining ring entries after the dequeue has finished.

       Returns
           The number of objects dequeued, either 0 or n

       Definition at line 209 of file rte_ring_rts.h.

   static__rte_always_inlineunsignedintrte_ring_mp_rts_enqueue_burst(structrte_ring*r,void*const*obj_table,unsignedintn,unsignedint*free_space)[static]
       Enqueue several objects on the RTS ring (multi-producers safe).

       Parametersr A pointer to the ring structure.
           obj_table A pointer to a table of void * pointers (objects).
           n The number of objects to add in the ring from the obj_table.
           free_space  if  non-NULL,  returns  the  amount  of space in the ring after the enqueue operation has
           finished.

       Returns

           • n: Actual number of objects enqueued.

       Definition at line 232 of file rte_ring_rts.h.

   static__rte_always_inlineunsignedintrte_ring_mc_rts_dequeue_burst(structrte_ring*r,void**obj_table,unsignedintn,unsignedint*available)[static]
       Dequeue several objects from an RTS ring (multi-consumers safe). When the requested objects are more than
       the available objects, only dequeue the actual number of objects.

       Parametersr A pointer to the ring structure.
           obj_table A pointer to a table of void * pointers (objects) that will be filled.
           n The number of objects to dequeue from the ring to the obj_table.
           available If non-NULL, returns the number of remaining ring entries after the dequeue has finished.

       Returns

           • n: Actual number of objects dequeued, 0 if ring is empty

       Definition at line 257 of file rte_ring_rts.h.

   staticuint32_trte_ring_get_prod_htd_max(conststructrte_ring*r)[inline],[static]
       Return producer max Head-Tail-Distance (HTD).

       Parametersr A pointer to the ring structure.

       Returns
           Producer HTD value, if producer is set in appropriate sync mode, or UINT32_MAX otherwise.

       Definition at line 274 of file rte_ring_rts.h.

   staticintrte_ring_set_prod_htd_max(structrte_ring*r,uint32_tv)[inline],[static]
       Set producer max Head-Tail-Distance (HTD). Note that producer has to use appropriate sync mode (RTS).

       Parametersr A pointer to the ring structure.
           v new HTD value to setup.

       Returns
           Zero on success, or negative error code otherwise.

       Definition at line 293 of file rte_ring_rts.h.

   staticuint32_trte_ring_get_cons_htd_max(conststructrte_ring*r)[inline],[static]
       Return consumer max Head-Tail-Distance (HTD).

       Parametersr A pointer to the ring structure.

       Returns
           Consumer HTD value, if consumer is set in appropriate sync mode, or UINT32_MAX otherwise.

       Definition at line 312 of file rte_ring_rts.h.

   staticintrte_ring_set_cons_htd_max(structrte_ring*r,uint32_tv)[inline],[static]
       Set consumer max Head-Tail-Distance (HTD). Note that consumer has to use appropriate sync mode (RTS).

       Parametersr A pointer to the ring structure.
           v new HTD value to setup.

       Returns
           Zero on success, or negative error code otherwise.

       Definition at line 331 of file rte_ring_rts.h.

       rte_ring_rts.h

       #include <rte_ring_rts_elem_pvt.h>

   Functions
       static __rte_always_inline unsigned int rte_ring_mp_rts_enqueue_bulk_elem (struct rte_ring *r, const void
           *obj_table, unsigned int esize, unsigned int n, unsigned int *free_space)
       static __rte_always_inline unsigned int rte_ring_mc_rts_dequeue_bulk_elem (struct rte_ring *r, void
           *obj_table, unsigned int esize, unsigned int n, unsigned int *available)
       static __rte_always_inline unsigned int rte_ring_mp_rts_enqueue_burst_elem (struct rte_ring *r, const
           void *obj_table, unsigned int esize, unsigned int n, unsigned int *free_space)
       static __rte_always_inline unsigned int rte_ring_mc_rts_dequeue_burst_elem (struct rte_ring *r, void
           *obj_table, unsigned int esize, unsigned int n, unsigned int *available)
       static __rte_always_inline unsigned int rte_ring_mp_rts_enqueue_bulk (struct rte_ring *r, void *const
           *obj_table, unsigned int n, unsigned int *free_space)
       static __rte_always_inline unsigned int rte_ring_mc_rts_dequeue_bulk (struct rte_ring *r, void
           **obj_table, unsigned int n, unsigned int *available)
       static __rte_always_inline unsigned int rte_ring_mp_rts_enqueue_burst (struct rte_ring *r, void *const
           *obj_table, unsigned int n, unsigned int *free_space)
       static __rte_always_inline unsigned int rte_ring_mc_rts_dequeue_burst (struct rte_ring *r, void
           **obj_table, unsigned int n, unsigned int *available)
       static uint32_t rte_ring_get_prod_htd_max (const struct rte_ring *r)
       static int rte_ring_set_prod_htd_max (struct rte_ring *r, uint32_t v)
       static uint32_t rte_ring_get_cons_htd_max (const struct rte_ring *r)
       static int rte_ring_set_cons_htd_max (struct rte_ring *r, uint32_t v)