---
name: "rte_ring_enqueue_zc_burst_elem_start"
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_peek_zc.h"
---

# rte\_ring\_enqueue\_zc\_burst\_elem\_start(3)

Part of [rte\_ring\_peek\_zc.h(3)](/rte_ring_peek_zc.h/3.md).

## NAME

rte\_ring\_peek\_zc.h

## SYNOPSIS

`#include <rte_ring_peek_elem_pvt.h>`\

### Data Structures

struct **rte\_ring\_zc\_data**\

### Functions

static **\_\_rte\_always\_inline** unsigned int **rte\_ring\_enqueue\_zc\_bulk\_elem\_start** (struct **rte\_ring** \*r, unsigned int esize, unsigned int n, struct **rte\_ring\_zc\_data** \*zcd, unsigned int \*free\_space)\
 static **\_\_rte\_always\_inline** unsigned int **rte\_ring\_enqueue\_zc\_bulk\_start** (struct **rte\_ring** \*r, unsigned int n, struct **rte\_ring\_zc\_data** \*zcd, unsigned int \*free\_space)\
 static **\_\_rte\_always\_inline** unsigned int **rte\_ring\_enqueue\_zc\_burst\_elem\_start** (struct **rte\_ring** \*r, unsigned int esize, unsigned int n, struct **rte\_ring\_zc\_data** \*zcd, unsigned int \*free\_space)\
 static **\_\_rte\_always\_inline** unsigned int **rte\_ring\_enqueue\_zc\_burst\_start** (struct **rte\_ring** \*r, unsigned int n, struct **rte\_ring\_zc\_data** \*zcd, unsigned int \*free\_space)\
 static **\_\_rte\_always\_inline** void **rte\_ring\_enqueue\_zc\_elem\_finish** (struct **rte\_ring** \*r, unsigned int n)\
 static **\_\_rte\_always\_inline** void **rte\_ring\_enqueue\_zc\_finish** (struct **rte\_ring** \*r, unsigned int n)\
 static **\_\_rte\_always\_inline** unsigned int **rte\_ring\_dequeue\_zc\_bulk\_elem\_start** (struct **rte\_ring** \*r, unsigned int esize, unsigned int n, struct **rte\_ring\_zc\_data** \*zcd, unsigned int \*available)\
 static **\_\_rte\_always\_inline** unsigned int **rte\_ring\_dequeue\_zc\_bulk\_start** (struct **rte\_ring** \*r, unsigned int n, struct **rte\_ring\_zc\_data** \*zcd, unsigned int \*available)\
 static **\_\_rte\_always\_inline** unsigned int **rte\_ring\_dequeue\_zc\_burst\_elem\_start** (struct **rte\_ring** \*r, unsigned int esize, unsigned int n, struct **rte\_ring\_zc\_data** \*zcd, unsigned int \*available)\
 static **\_\_rte\_always\_inline** unsigned int **rte\_ring\_dequeue\_zc\_burst\_start** (struct **rte\_ring** \*r, unsigned int n, struct **rte\_ring\_zc\_data** \*zcd, unsigned int \*available)\
 static **\_\_rte\_always\_inline** void **rte\_ring\_dequeue\_zc\_elem\_finish** (struct **rte\_ring** \*r, unsigned int n)\
 static **\_\_rte\_always\_inline** void **rte\_ring\_dequeue\_zc\_finish** (struct **rte\_ring** \*r, unsigned int n)\

## Detailed Description

It is not recommended to include this file directly. Please include \<**rte\_ring\_elem.h**\> instead.

Ring Peek Zero Copy APIs These APIs make it possible to split public enqueue/dequeue API into 3 parts:

- •

  enqueue/dequeue start

- •

  copy data to/from the ring

- •

  enqueue/dequeue finish Along with the advantages of the peek APIs, these APIs provide the ability to avoid copying of the data to temporary area (for ex: array of mbufs on the stack).

Note that currently these APIs are available only for two sync modes: 1) Single Producer/Single Consumer (RTE\_RING\_SYNC\_ST) 2) Serialized Producer/Serialized Consumer (RTE\_RING\_SYNC\_MT\_HTS). It is user's responsibility to create/init ring with appropriate sync modes selected.

Following are some examples showing the API usage. 1) struct elem\_obj {uint64\_t a; uint32\_t b, c;}; struct elem\_obj \*obj;

// Create ring with sync type RTE\_RING\_SYNC\_ST or RTE\_RING\_SYNC\_MT\_HTS // Reserve space on the ring n = rte\_ring\_enqueue\_zc\_bulk\_elem\_start(r, sizeof(elem\_obj), 1, &zcd, NULL);

// Produce the data directly on the ring memory obj = (struct elem\_obj \*)zcd-\>ptr1; obj-\>a = rte\_get\_a(); obj-\>b = rte\_get\_b(); obj-\>c = rte\_get\_c(); rte\_ring\_enqueue\_zc\_elem\_finish(ring, n);

2\) // Create ring with sync type RTE\_RING\_SYNC\_ST or RTE\_RING\_SYNC\_MT\_HTS // Reserve space on the ring n = rte\_ring\_enqueue\_zc\_burst\_start(r, 32, &zcd, NULL);

// Pkt I/O core polls packets from the NIC if (n != 0) { nb\_rx = rte\_eth\_rx\_burst(portid, queueid, zcd-\>ptr1, zcd-\>n1); if (nb\_rx == zcd-\>n1 && n != zcd-\>n1) nb\_rx = rte\_eth\_rx\_burst(portid, queueid, zcd-\>ptr2, n - zcd-\>n1);

// Provide packets to the packet processing cores rte\_ring\_enqueue\_zc\_finish(r, nb\_rx); }

Note that between *start* and *finish* none other thread can proceed with enqueue/dequeue operation till *finish* completes.

Definition in file **rte\_ring\_peek\_zc.h**.

## Function Documentation

### static \_\_rte\_always\_inline unsigned int rte\_ring\_enqueue\_zc\_bulk\_elem\_start (struct rte\_ring \* r, unsigned int esize, unsigned int n, struct rte\_ring\_zc\_data \* zcd, unsigned int \* free\_space)` [static]`

Start to enqueue several objects on the ring. Note that no actual objects are put in the queue by this function, it just reserves space for the user on the ring. User has to copy objects into the queue using the returned pointers. User should call rte\_ring\_enqueue\_zc\_elem\_finish to complete the enqueue operation.

**Parameters**

*r* A pointer to the ring structure. \
 *esize* The size of ring element, in bytes. It must be a multiple of 4. \
 *n* The number of objects to add in the ring. \
 *zcd* Structure containing the pointers and length of the space reserved on the ring storage. \
 *free\_space* If non-NULL, returns the amount of space in the ring after the reservation operation has finished.

**Returns**

The number of objects that can be enqueued, either 0 or n

Definition at line **180** of file **rte\_ring\_peek\_zc.h**.

### static \_\_rte\_always\_inline unsigned int rte\_ring\_enqueue\_zc\_bulk\_start (struct rte\_ring \* r, unsigned int n, struct rte\_ring\_zc\_data \* zcd, unsigned int \* free\_space)` [static]`

Start to enqueue several pointers to objects on the ring. Note that no actual pointers are put in the queue by this function, it just reserves space for the user on the ring. User has to copy pointers to objects into the queue using the returned pointers. User should call rte\_ring\_enqueue\_zc\_finish to complete the enqueue operation.

**Parameters**

*r* A pointer to the ring structure. \
 *n* The number of objects to add in the ring. \
 *zcd* Structure containing the pointers and length of the space reserved on the ring storage. \
 *free\_space* If non-NULL, returns the amount of space in the ring after the reservation operation has finished.

**Returns**

The number of objects that can be enqueued, either 0 or n

Definition at line **210** of file **rte\_ring\_peek\_zc.h**.

### static \_\_rte\_always\_inline unsigned int rte\_ring\_enqueue\_zc\_burst\_elem\_start (struct rte\_ring \* r, unsigned int esize, unsigned int n, struct rte\_ring\_zc\_data \* zcd, unsigned int \* free\_space)` [static]`

Start to enqueue several objects on the ring. Note that no actual objects are put in the queue by this function, it just reserves space for the user on the ring. User has to copy objects into the queue using the returned pointers. User should call rte\_ring\_enqueue\_zc\_elem\_finish to complete the enqueue operation.

**Parameters**

*r* A pointer to the ring structure. \
 *esize* The size of ring element, in bytes. It must be a multiple of 4. \
 *n* The number of objects to add in the ring. \
 *zcd* Structure containing the pointers and length of the space reserved on the ring storage. \
 *free\_space* If non-NULL, returns the amount of space in the ring after the reservation operation has finished.

**Returns**

The number of objects that can be enqueued, either 0 or n

Definition at line **241** of file **rte\_ring\_peek\_zc.h**.

### static \_\_rte\_always\_inline unsigned int rte\_ring\_enqueue\_zc\_burst\_start (struct rte\_ring \* r, unsigned int n, struct rte\_ring\_zc\_data \* zcd, unsigned int \* free\_space)` [static]`

Start to enqueue several pointers to objects on the ring. Note that no actual pointers are put in the queue by this function, it just reserves space for the user on the ring. User has to copy pointers to objects into the queue using the returned pointers. User should call rte\_ring\_enqueue\_zc\_finish to complete the enqueue operation.

**Parameters**

*r* A pointer to the ring structure. \
 *n* The number of objects to add in the ring. \
 *zcd* Structure containing the pointers and length of the space reserved on the ring storage. \
 *free\_space* If non-NULL, returns the amount of space in the ring after the reservation operation has finished.

**Returns**

The number of objects that can be enqueued, either 0 or n.

Definition at line **271** of file **rte\_ring\_peek\_zc.h**.

### static \_\_rte\_always\_inline void rte\_ring\_enqueue\_zc\_elem\_finish (struct rte\_ring \* r, unsigned int n)` [static]`

Complete enqueuing several objects on the ring. Note that number of objects to enqueue should not exceed previous enqueue\_start return value.

**Parameters**

*r* A pointer to the ring structure. \
 *n* The number of objects to add to the ring.

Definition at line **289** of file **rte\_ring\_peek\_zc.h**.

### static \_\_rte\_always\_inline void rte\_ring\_enqueue\_zc\_finish (struct rte\_ring \* r, unsigned int n)` [static]`

Complete enqueuing several pointers to objects on the ring. Note that number of objects to enqueue should not exceed previous enqueue\_start return value.

**Parameters**

*r* A pointer to the ring structure. \
 *n* The number of pointers to objects to add to the ring.

Definition at line **321** of file **rte\_ring\_peek\_zc.h**.

### static \_\_rte\_always\_inline unsigned int rte\_ring\_dequeue\_zc\_bulk\_elem\_start (struct rte\_ring \* r, unsigned int esize, unsigned int n, struct rte\_ring\_zc\_data \* zcd, unsigned int \* available)` [static]`

Start to dequeue several objects from the ring. Note that no actual objects are copied from the queue by this function. User has to copy objects from the queue using the returned pointers. User should call rte\_ring\_dequeue\_zc\_elem\_finish to complete the dequeue operation.

**Parameters**

*r* A pointer to the ring structure. \
 *esize* The size of ring element, in bytes. It must be a multiple of 4. \
 *n* The number of objects to remove from the ring. \
 *zcd* Structure containing the pointers and length of the space reserved on the ring storage. \
 *available* If non-NULL, returns the number of remaining ring entries after the dequeue has finished.

**Returns**

The number of objects that can be dequeued, either 0 or n.

Definition at line **387** of file **rte\_ring\_peek\_zc.h**.

### static \_\_rte\_always\_inline unsigned int rte\_ring\_dequeue\_zc\_bulk\_start (struct rte\_ring \* r, unsigned int n, struct rte\_ring\_zc\_data \* zcd, unsigned int \* available)` [static]`

Start to dequeue several pointers to objects from the ring. Note that no actual pointers are removed from the queue by this function. User has to copy pointers to objects from the queue using the returned pointers. User should call rte\_ring\_dequeue\_zc\_finish to complete the dequeue operation.

**Parameters**

*r* A pointer to the ring structure. \
 *n* The number of objects to remove from the ring. \
 *zcd* Structure containing the pointers and length of the space reserved on the ring storage. \
 *available* If non-NULL, returns the number of remaining ring entries after the dequeue has finished.

**Returns**

The number of objects that can be dequeued, either 0 or n.

Definition at line **416** of file **rte\_ring\_peek\_zc.h**.

### static \_\_rte\_always\_inline unsigned int rte\_ring\_dequeue\_zc\_burst\_elem\_start (struct rte\_ring \* r, unsigned int esize, unsigned int n, struct rte\_ring\_zc\_data \* zcd, unsigned int \* available)` [static]`

Start to dequeue several objects from the ring. Note that no actual objects are copied from the queue by this function. User has to copy objects from the queue using the returned pointers. User should call rte\_ring\_dequeue\_zc\_elem\_finish to complete the dequeue operation.

**Parameters**

*r* A pointer to the ring structure. \
 *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. \
 *zcd* Structure containing the pointers and length of the space reserved on the ring storage. \
 *available* If non-NULL, returns the number of remaining ring entries after the dequeue has finished.

**Returns**

The number of objects that can be dequeued, either 0 or n.

Definition at line **448** of file **rte\_ring\_peek\_zc.h**.

### static \_\_rte\_always\_inline unsigned int rte\_ring\_dequeue\_zc\_burst\_start (struct rte\_ring \* r, unsigned int n, struct rte\_ring\_zc\_data \* zcd, unsigned int \* available)` [static]`

Start to dequeue several pointers to objects from the ring. Note that no actual pointers are removed from the queue by this function. User has to copy pointers to objects from the queue using the returned pointers. User should call rte\_ring\_dequeue\_zc\_finish to complete the dequeue operation.

**Parameters**

*r* A pointer to the ring structure. \
 *n* The number of objects to remove from the ring. \
 *zcd* Structure containing the pointers and length of the space reserved on the ring storage. \
 *available* If non-NULL, returns the number of remaining ring entries after the dequeue has finished.

**Returns**

The number of objects that can be dequeued, either 0 or n.

Definition at line **477** of file **rte\_ring\_peek\_zc.h**.

### static \_\_rte\_always\_inline void rte\_ring\_dequeue\_zc\_elem\_finish (struct rte\_ring \* r, unsigned int n)` [static]`

Complete dequeuing several objects from the ring. Note that number of objects to dequeued should not exceed previous dequeue\_start return value.

**Parameters**

*r* A pointer to the ring structure. \
 *n* The number of objects to remove from the ring.

Definition at line **495** of file **rte\_ring\_peek\_zc.h**.

### static \_\_rte\_always\_inline void rte\_ring\_dequeue\_zc\_finish (struct rte\_ring \* r, unsigned int n)` [static]`

Complete dequeuing several objects from the ring. Note that number of objects to dequeued should not exceed previous dequeue\_start return value.

**Parameters**

*r* A pointer to the ring structure. \
 *n* The number of objects to remove from the ring.

Definition at line **527** of file **rte\_ring\_peek\_zc.h**.

## Author

Generated automatically by Doxygen for DPDK from the source code.