---
name: "rte_ring_enqueue_bulk_elem"
section: "3"
platform: "linux"
package: "dpdk-doc"
version: "24.11.4-0+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/rte_ring_elem.h"
---

# rte\_ring\_enqueue\_bulk\_elem(3)

Part of [rte\_ring\_elem.h(3)](/rte_ring_elem.h/3.md).

## NAME

rte\_ring\_elem.h

## SYNOPSIS

`#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)\

## Detailed Description

RTE Ring with user defined element size

Definition in file **rte\_ring\_elem.h**.

## Function Documentation

### ssize\_t rte\_ring\_get\_memsize\_elem (unsigned int esize, unsigned int count)

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.

**Parameters**

*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).

**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.

### struct rte\_ring \* rte\_ring\_create\_elem (const char \* name, unsigned int esize, unsigned int count, int socket\_id, unsigned int flags)

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.

**Parameters**

*name* 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() or rte\_ring\_enqueue\_bulk() is 'single-producer'.**

- •

  **RING\_F\_MP\_RTS\_ENQ: If this flag is set, the default behavior when using rte\_ring\_enqueue() or rte\_ring\_enqueue\_bulk() is 'multi-producer RTS mode'.**

- •

  **RING\_F\_MP\_HTS\_ENQ: If this flag is set, the default behavior when using rte\_ring\_enqueue() or rte\_ring\_enqueue\_bulk() is 'multi-producer HTS mode'. If none of these flags is set, then default 'multi-producer' behavior is selected.**

- •

  **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() or rte\_ring\_dequeue\_bulk() is 'single-consumer'. Otherwise, it is 'multi-consumers'.**

- •

  **RING\_F\_MC\_RTS\_DEQ: If this flag is set, the default behavior when using rte\_ring\_dequeue() or rte\_ring\_dequeue\_bulk() is 'multi-consumer RTS mode'.**

- •

  **RING\_F\_MC\_HTS\_DEQ: If this flag is set, the default behavior when using rte\_ring\_dequeue() or rte\_ring\_dequeue\_bulk() is 'multi-consumer HTS mode'. If none of these flags is set, then default 'multi-consumer' behavior is selected.**

**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\_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]`

**Enqueue several objects on the ring (multi-producers safe).**

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

**Parameters**

*r* **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\_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]`

**Enqueue several objects on a ring**

**Warning**

**This API is NOT multi-producers safe**

**Parameters**

*r* **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\_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]`

**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).**

**Parameters**

*r* **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\_inline int rte\_ring\_mp\_enqueue\_elem (struct rte\_ring \* r, void \* obj, unsigned int esize)` [static]`

**Enqueue one object on a ring (multi-producers safe).**

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

**Parameters**

*r* **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\_inline int rte\_ring\_sp\_enqueue\_elem (struct rte\_ring \* r, void \* obj, unsigned int esize)` [static]`

**Enqueue one object on a ring**

**Warning**

**This API is NOT multi-producers safe**

**Parameters**

*r* **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\_inline int rte\_ring\_enqueue\_elem (struct rte\_ring \* r, void \* obj, unsigned int esize)` [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).**

**Parameters**

*r* **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\_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]`

**Dequeue several objects from a ring (multi-consumers safe).**

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

**Parameters**

*r* **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\_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]`

**Dequeue several objects from a ring (NOT multi-consumers safe).**

**Parameters**

*r* **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\_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]`

**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).**

**Parameters**

*r* **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\_inline int rte\_ring\_mc\_dequeue\_elem (struct rte\_ring \* r, void \* obj\_p, unsigned int esize)` [static]`

**Dequeue one object from a ring (multi-consumers safe).**

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

**Parameters**

*r* **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\_inline int rte\_ring\_sc\_dequeue\_elem (struct rte\_ring \* r, void \* obj\_p, unsigned int esize)` [static]`

**Dequeue one object from a ring (NOT multi-consumers safe).**

**Parameters**

*r* **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\_inline int rte\_ring\_dequeue\_elem (struct rte\_ring \* r, void \* obj\_p, unsigned int esize)` [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).**

**Parameters**

*r* **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\_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]`

**Enqueue several objects on the ring (multi-producers safe).**

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

**Parameters**

*r* **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\_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]`

**Enqueue several objects on a ring**

**Warning**

**This API is NOT multi-producers safe**

**Parameters**

*r* **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\_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]`

**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).**

**Parameters**

*r* **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\_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]`

**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.**

**Parameters**

*r* **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\_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]`

**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**

**Parameters**

*r* **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\_inline unsigned int rte\_ring\_dequeue\_burst\_elem (struct rte\_ring \* r, void \* obj\_table, unsigned int esize, unsigned int n, unsigned int \* 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).**

**Parameters**

*r* **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.**

## Author

**Generated automatically by Doxygen for DPDK from the source code.**