rte_ring_elem.h

       Generated automatically by Doxygen for DPDK from the source code.

DPDK                                             Version 24.11.2                              rte_ring_elem.h(3)

       RTE Ring with user defined element size

       Definition in file rte_ring_elem.h.

ssize_trte_ring_get_memsize_elem(unsignedintesize,unsignedintcount)
       Calculate the memory size needed for a ring with given element size

       This function returns the number of bytes needed for a ring, given the number of elements in it and the
       size of the element. This value is the sum of the size of the structure rte_ring and the size of the
       memory needed for storing the elements. The value is aligned to a cache line size.

       Parametersesize The size of ring element, in bytes. It must be a multiple of 4.
           count The number of elements in the ring (must be a power of 2).

       Returns

           • The memory size needed for the ring on success.

           • -EINVAL - esize is not a multiple of 4 or count provided is not a power of 2.

   structrte_ring*rte_ring_create_elem(constchar*name,unsignedintesize,unsignedintcount,intsocket_id,unsignedintflags)
       Create a new ring named name that stores elements with given size.

       This function uses memzone_reserve() to allocate memory. Then it calls rte_ring_init() to  initialize  an
       empty ring.

       The  new  ring  size is set to count, which must be a power of two. Water marking is disabled by default.
       The real usable ring size is count-1 instead of count to differentiate a full ring from an empty ring.

       The ring is added in RTE_TAILQ_RING list.

       Parametersname The name of the ring.
           esize The size of ring element, in bytes. It must be a multiple of 4.
           count The number of elements in the ring (must be a power of 2).
           socket_id The socket_id argument is the  socket  identifier  in  case  of  NUMA.  The  value  can  be
           SOCKET_ID_ANY if there is no NUMA constraint for the reserved zone.
           flags An OR of the following:

           • One of mutually exclusive flags that define producer behavior:

             • RING_F_SP_ENQ:  If  this  flag  is  set,  the  default  behavior when using rte_ring_enqueue()orrte_ring_enqueue_bulk()is'single-producer'.

             • RING_F_MP_RTS_ENQ: If this flag is set, the default behavior  when  using  rte_ring_enqueue()orrte_ring_enqueue_bulk()is'multi-producerRTSmode'.

             • RING_F_MP_HTS_ENQ:  If  this  flag  is set, the default behavior when using rte_ring_enqueue()orrte_ring_enqueue_bulk()is'multi-producerHTSmode'.Ifnoneoftheseflagsisset,thendefault'multi-producer'behaviorisselected.

           • One of mutually exclusive flags that define consumer behavior:

             • RING_F_SC_DEQ: If this flag is  set,  the  default  behavior  when  using  rte_ring_dequeue()orrte_ring_dequeue_bulk()is'single-consumer'.Otherwise,itis'multi-consumers'.

             • RING_F_MC_RTS_DEQ:  If  this  flag  is set, the default behavior when using rte_ring_dequeue()orrte_ring_dequeue_bulk()is'multi-consumerRTSmode'.

             • RING_F_MC_HTS_DEQ: If this flag is set, the default behavior  when  using  rte_ring_dequeue()orrte_ring_dequeue_bulk()is'multi-consumerHTSmode'.Ifnoneoftheseflagsisset,thendefault'multi-consumer'behaviorisselected.Returns
           On  success,  the  pointer to the new allocated ring. NULL on error with rte_errno set appropriately.
           Possible errno values include:

           • E_RTE_NO_CONFIG - function could not get pointer to rte_config structure

           • EINVAL - esize is not a multiple of 4 or count provided is not a power of 2.

           • ENOSPC - the maximum number of memzones has already been allocated

           • EEXIST - a memzone with the same name already exists

           • ENOMEM - no appropriate memory area found in which to create memzone

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

       This function uses a 'compare and set' instruction to move the producer index atomically.

       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 127 of file rte_ring_elem.h.

   static__rte_always_inlineunsignedintrte_ring_sp_enqueue_bulk_elem(structrte_ring*r,constvoid*obj_table,unsignedintesize,unsignedintn,unsignedint*free_space)[static]
       Enqueue several objects on a ring

       Warning
           This API is NOT 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 156 of file rte_ring_elem.h.

   static__rte_always_inlineunsignedintrte_ring_enqueue_bulk_elem(structrte_ring*r,constvoid*obj_table,unsignedintesize,unsignedintn,unsignedint*free_space)[static]
       Enqueue several objects on a ring.

       This  function  calls the multi-producer or the single-producer version depending on the default behavior
       that was specified at ring creation time (see flags).

       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 190 of file rte_ring_elem.h.

   static__rte_always_inlineintrte_ring_mp_enqueue_elem(structrte_ring*r,void*obj,unsignedintesize)[static]
       Enqueue one object on a ring (multi-producers safe).

       This function uses a 'compare and set' instruction to move the producer index atomically.

       Parametersr A pointer to the ring structure.
           obj A pointer to the object to be added.
           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.

       Returns

           • 0: Success; objects enqueued.

           • -ENOBUFS: Not enough room in the ring to enqueue; no object is enqueued.

       Definition at line 234 of file rte_ring_elem.h.

   static__rte_always_inlineintrte_ring_sp_enqueue_elem(structrte_ring*r,void*obj,unsignedintesize)[static]
       Enqueue one object on a ring

       Warning
           This API is NOT multi-producers safe

       Parametersr A pointer to the ring structure.
           obj A pointer to the object to be added.
           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.

       Returns

           • 0: Success; objects enqueued.

           • -ENOBUFS: Not enough room in the ring to enqueue; no object is enqueued.

       Definition at line 258 of file rte_ring_elem.h.

   static__rte_always_inlineintrte_ring_enqueue_elem(structrte_ring*r,void*obj,unsignedintesize)[static]
       Enqueue one object on a ring.

       This function calls the multi-producer or the single-producer version, depending on the default behaviour
       that was specified at ring creation time (see flags).

       Parametersr A pointer to the ring structure.
           obj A pointer to the object to be added.
           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.

       Returns

           • 0: Success; objects enqueued.

           • -ENOBUFS: Not enough room in the ring to enqueue; no object is enqueued.

       Definition at line 284 of file rte_ring_elem.h.

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

       This function uses a 'compare and set' instruction to move the consumer index atomically.

       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 313 of file rte_ring_elem.h.

   static__rte_always_inlineunsignedintrte_ring_sc_dequeue_bulk_elem(structrte_ring*r,void*obj_table,unsignedintesize,unsignedintn,unsignedint*available)[static]
       Dequeue several objects from a ring (NOT 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, must be strictly positive.
           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 341 of file rte_ring_elem.h.

   static__rte_always_inlineunsignedintrte_ring_dequeue_bulk_elem(structrte_ring*r,void*obj_table,unsignedintesize,unsignedintn,unsignedint*available)[static]
       Dequeue several objects from a ring.

       This  function  calls  the  multi-consumers  or  the  single-consumer  version,  depending on the default
       behaviour that was specified at ring creation time (see flags).

       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 372 of file rte_ring_elem.h.

   static__rte_always_inlineintrte_ring_mc_dequeue_elem(structrte_ring*r,void*obj_p,unsignedintesize)[static]
       Dequeue one object from a ring (multi-consumers safe).

       This function uses a 'compare and set' instruction to move the consumer index atomically.

       Parametersr A pointer to the ring structure.
           obj_p A pointer to the object 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.

       Returns

           • 0: Success; objects dequeued.

           • -ENOENT: Not enough entries in the ring to dequeue; no object is dequeued.

       Definition at line 417 of file rte_ring_elem.h.

   static__rte_always_inlineintrte_ring_sc_dequeue_elem(structrte_ring*r,void*obj_p,unsignedintesize)[static]
       Dequeue one object from a ring (NOT multi-consumers safe).

       Parametersr A pointer to the ring structure.
           obj_p A pointer to the object 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.

       Returns

           • 0: Success; objects dequeued.

           • -ENOENT: Not enough entries in the ring to dequeue, no object is dequeued.

       Definition at line 441 of file rte_ring_elem.h.

   static__rte_always_inlineintrte_ring_dequeue_elem(structrte_ring*r,void*obj_p,unsignedintesize)[static]
       Dequeue one object from a ring.

       This function calls the multi-consumers or the single-consumer version depending on the default behaviour
       that was specified at ring creation time (see flags).

       Parametersr A pointer to the ring structure.
           obj_p A pointer to the object 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.

       Returns

           • 0: Success, objects dequeued.

           • -ENOENT: Not enough entries in the ring to dequeue, no object is dequeued.

       Definition at line 469 of file rte_ring_elem.h.

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

       This function uses a 'compare and set' instruction to move the producer index atomically.

       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 498 of file rte_ring_elem.h.

   static__rte_always_inlineunsignedintrte_ring_sp_enqueue_burst_elem(structrte_ring*r,constvoid*obj_table,unsignedintesize,unsignedintn,unsignedint*free_space)[static]
       Enqueue several objects on a ring

       Warning
           This API is NOT 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 527 of file rte_ring_elem.h.

   static__rte_always_inlineunsignedintrte_ring_enqueue_burst_elem(structrte_ring*r,constvoid*obj_table,unsignedintesize,unsignedintn,unsignedint*free_space)[static]
       Enqueue several objects on a ring.

       This function calls the multi-producer or the single-producer version depending on the  default  behavior
       that was specified at ring creation time (see flags).

       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 558 of file rte_ring_elem.h.

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

       This function uses a 'compare and set' instruction to move the consumer index atomically.

       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 608 of file rte_ring_elem.h.

   static__rte_always_inlineunsignedintrte_ring_sc_dequeue_burst_elem(structrte_ring*r,void*obj_table,unsignedintesize,unsignedintn,unsignedint*available)[static]
       Dequeue several objects from a ring (NOT multi-consumers safe).When the request 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 637 of file rte_ring_elem.h.

   static__rte_always_inlineunsignedintrte_ring_dequeue_burst_elem(structrte_ring*r,void*obj_table,unsignedintesize,unsignedintn,unsignedint*available)[static]
       Dequeue multiple objects from a ring up to a maximum number.

       This  function  calls  the  multi-consumers  or  the  single-consumer  version,  depending on the default
       behaviour that was specified at ring creation time (see flags).

       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

           • Number of objects dequeued

       Definition at line 668 of file rte_ring_elem.h.

       rte_ring_elem.h

       #include <rte_ring_core.h>
       #include <rte_ring_elem_pvt.h>
       #include <rte_ring_hts.h>
       #include <rte_ring_rts.h>
       #include <rte_ring_peek.h>
       #include <rte_ring_peek_zc.h>
       #include <rte_ring.h>

   Functions
       ssize_t rte_ring_get_memsize_elem (unsigned int esize, unsigned int count)
       struct rte_ring * rte_ring_create_elem (const char *name, unsigned int esize, unsigned int count, int
           socket_id, unsigned int flags)
       static __rte_always_inline unsigned int rte_ring_mp_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_sp_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_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 int rte_ring_mp_enqueue_elem (struct rte_ring *r, void *obj, unsigned int
           esize)
       static __rte_always_inline int rte_ring_sp_enqueue_elem (struct rte_ring *r, void *obj, unsigned int
           esize)
       static __rte_always_inline int rte_ring_enqueue_elem (struct rte_ring *r, void *obj, unsigned int esize)
       static __rte_always_inline unsigned int rte_ring_mc_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_sc_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_dequeue_bulk_elem (struct rte_ring *r, void *obj_table,
           unsigned int esize, unsigned int n, unsigned int *available)
       static __rte_always_inline int rte_ring_mc_dequeue_elem (struct rte_ring *r, void *obj_p, unsigned int
           esize)
       static __rte_always_inline int rte_ring_sc_dequeue_elem (struct rte_ring *r, void *obj_p, unsigned int
           esize)
       static __rte_always_inline int rte_ring_dequeue_elem (struct rte_ring *r, void *obj_p, unsigned int
           esize)
       static __rte_always_inline unsigned int rte_ring_mp_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_sp_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_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_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_sc_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_dequeue_burst_elem (struct rte_ring *r, void *obj_table,
           unsigned int esize, unsigned int n, unsigned int *available)