---
name: "rte_ring_mp_rts_enqueue_burst_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_rts.h"
---

# rte\_ring\_mp\_rts\_enqueue\_burst\_elem(3)

Part of [rte\_ring\_rts.h(3)](/rte_ring_rts.h/3.md).

## NAME

rte\_ring\_rts.h

## SYNOPSIS

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

## Detailed Description

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

## Function Documentation

### 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]`

Enqueue several objects on the RTS ring (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 **80** of file **rte\_ring\_rts.h**.

### 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]`

Dequeue several objects from an RTS ring (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. \
 *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\_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]`

Enqueue several objects on the RTS ring (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 **134** of file **rte\_ring\_rts.h**.

### 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]`

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.

**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 **163** of file **rte\_ring\_rts.h**.

### 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]`

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

**Parameters**

*r* 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\_inline unsigned int rte\_ring\_mc\_rts\_dequeue\_bulk (struct rte\_ring \* r, void \*\* obj\_table, unsigned int n, unsigned int \* available)` [static]`

Dequeue several objects from an RTS ring (multi-consumers safe).

**Parameters**

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

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

**Parameters**

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

**Parameters**

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

### static uint32\_t rte\_ring\_get\_prod\_htd\_max (const struct rte\_ring \* r)` [inline]`, ` [static]`

Return producer max Head-Tail-Distance (HTD).

**Parameters**

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

### static int rte\_ring\_set\_prod\_htd\_max (struct rte\_ring \* r, uint32\_t v)` [inline]`, ` [static]`

Set producer max Head-Tail-Distance (HTD). Note that producer has to use appropriate sync mode (RTS).

**Parameters**

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

### static uint32\_t rte\_ring\_get\_cons\_htd\_max (const struct rte\_ring \* r)` [inline]`, ` [static]`

Return consumer max Head-Tail-Distance (HTD).

**Parameters**

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

### static int rte\_ring\_set\_cons\_htd\_max (struct rte\_ring \* r, uint32\_t v)` [inline]`, ` [static]`

Set consumer max Head-Tail-Distance (HTD). Note that consumer has to use appropriate sync mode (RTS).

**Parameters**

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

## Author

Generated automatically by Doxygen for DPDK from the source code.