--- name: "rte_ring_peek.h" 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.h" --- # rte\_ring\_peek.h(3) ## NAME rte\_ring\_peek.h ## SYNOPSIS `#include `\ ### Functions static **\_\_rte\_always\_inline** unsigned int **rte\_ring\_enqueue\_bulk\_elem\_start** (struct **rte\_ring** \*r, unsigned int n, unsigned int \*free\_space)\ static **\_\_rte\_always\_inline** unsigned int **rte\_ring\_enqueue\_bulk\_start** (struct **rte\_ring** \*r, unsigned int n, unsigned int \*free\_space)\ static **\_\_rte\_always\_inline** unsigned int **rte\_ring\_enqueue\_burst\_elem\_start** (struct **rte\_ring** \*r, unsigned int n, unsigned int \*free\_space)\ static **\_\_rte\_always\_inline** unsigned int **rte\_ring\_enqueue\_burst\_start** (struct **rte\_ring** \*r, unsigned int n, unsigned int \*free\_space)\ static **\_\_rte\_always\_inline** void **rte\_ring\_enqueue\_elem\_finish** (struct **rte\_ring** \*r, const void \*obj\_table, unsigned int esize, unsigned int n)\ static **\_\_rte\_always\_inline** void **rte\_ring\_enqueue\_finish** (struct **rte\_ring** \*r, void \*const \*obj\_table, unsigned int n)\ static **\_\_rte\_always\_inline** unsigned int **rte\_ring\_dequeue\_bulk\_elem\_start** (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\_start** (struct **rte\_ring** \*r, void \*\*obj\_table, unsigned int n, unsigned int \*available)\ static **\_\_rte\_always\_inline** unsigned int **rte\_ring\_dequeue\_burst\_elem\_start** (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\_start** (struct **rte\_ring** \*r, void \*\*obj\_table, unsigned int n, unsigned int \*available)\ static **\_\_rte\_always\_inline** void **rte\_ring\_dequeue\_elem\_finish** (struct **rte\_ring** \*r, unsigned int n)\ static **\_\_rte\_always\_inline** void **rte\_ring\_dequeue\_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 API Introduction of **rte\_ring** with serialized producer/consumer (HTS sync mode) makes possible to split public enqueue/dequeue API into two phases: - • enqueue/dequeue start - • enqueue/dequeue finish That allows user to inspect objects in the ring without removing them from it (aka MT safe peek). Note that right now this new API is 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 a user responsibility to create/init ring with appropriate sync modes selected. As an example: // read 1 elem from the ring: n = rte\_ring\_dequeue\_bulk\_start(ring, &obj, 1, NULL); if (n != 0) { //examine object if (object\_examine(obj) == KEEP) //decided to keep it in the ring. rte\_ring\_dequeue\_finish(ring, 0); else //decided to remove it from the ring. rte\_ring\_dequeue\_finish(ring, n); } Note that between *start* and *finish* none other thread can proceed with enqueue(/dequeue) operation till *finish* completes. Definition in file **rte\_ring\_peek.h**. ## Function Documentation ### static \_\_rte\_always\_inline unsigned int rte\_ring\_enqueue\_bulk\_elem\_start (struct rte\_ring \* r, unsigned int n, 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 for user such ability. User has to call appropriate enqueue\_elem\_finish() to copy objects into the queue and complete given enqueue operation. **Parameters** *r* A pointer to the ring structure. \ *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 that can be enqueued, either 0 or n Definition at line **70** of file **rte\_ring\_peek.h**. ### static \_\_rte\_always\_inline unsigned int rte\_ring\_enqueue\_bulk\_start (struct rte\_ring \* r, unsigned int n, 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 for user such ability. User has to call appropriate enqueue\_finish() to copy objects into the queue and complete given enqueue operation. **Parameters** *r* A pointer to the ring structure. \ *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 that can be enqueued, either 0 or n Definition at line **95** of file **rte\_ring\_peek.h**. ### static \_\_rte\_always\_inline unsigned int rte\_ring\_enqueue\_burst\_elem\_start (struct rte\_ring \* r, unsigned int n, 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 for user such ability. User has to call appropriate enqueue\_elem\_finish() to copy objects into the queue and complete given enqueue operation. **Parameters** *r* A pointer to the ring structure. \ *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** Actual number of objects that can be enqueued. Definition at line **119** of file **rte\_ring\_peek.h**. ### static \_\_rte\_always\_inline unsigned int rte\_ring\_enqueue\_burst\_start (struct rte\_ring \* r, unsigned int n, 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 for user such ability. User has to call appropriate enqueue\_finish() to copy objects into the queue and complete given enqueue operation. **Parameters** *r* A pointer to the ring structure. \ *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** Actual number of objects that can be enqueued. Definition at line **144** of file **rte\_ring\_peek.h**. ### static \_\_rte\_always\_inline void rte\_ring\_enqueue\_elem\_finish (struct rte\_ring \* r, const void \* obj\_table, unsigned int esize, unsigned int n)` [static]` Complete to enqueue 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. \ *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 to the ring from the obj\_table. Definition at line **167** of file **rte\_ring\_peek.h**. ### static \_\_rte\_always\_inline void rte\_ring\_enqueue\_finish (struct rte\_ring \* r, void \*const \* obj\_table, unsigned int n)` [static]` Complete to enqueue 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. \ *obj\_table* A pointer to a table of objects. \ *n* The number of objects to add to the ring from the obj\_table. Definition at line **206** of file **rte\_ring\_peek.h**. ### static \_\_rte\_always\_inline unsigned int rte\_ring\_dequeue\_bulk\_elem\_start (struct rte\_ring \* r, void \* obj\_table, unsigned int esize, unsigned int n, unsigned int \* available)` [static]` Start to dequeue several objects from the ring. Note that user has to call appropriate dequeue\_finish() to complete given dequeue operation and actually remove objects the ring. **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 **234** of file **rte\_ring\_peek.h**. ### static \_\_rte\_always\_inline unsigned int rte\_ring\_dequeue\_bulk\_start (struct rte\_ring \* r, void \*\* obj\_table, unsigned int n, unsigned int \* available)` [static]` Start to dequeue several objects from the ring. Note that user has to call appropriate dequeue\_finish() to complete given dequeue operation and actually remove objects the ring. **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** Actual number of objects dequeued. Definition at line **259** of file **rte\_ring\_peek.h**. ### static \_\_rte\_always\_inline unsigned int rte\_ring\_dequeue\_burst\_elem\_start (struct rte\_ring \* r, void \* obj\_table, unsigned int esize, unsigned int n, unsigned int \* available)` [static]` Start to dequeue several objects from the ring. Note that user has to call appropriate dequeue\_finish() to complete given dequeue operation and actually remove objects the ring. **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 actual number of objects dequeued. Definition at line **288** of file **rte\_ring\_peek.h**. ### static \_\_rte\_always\_inline unsigned int rte\_ring\_dequeue\_burst\_start (struct rte\_ring \* r, void \*\* obj\_table, unsigned int n, unsigned int \* available)` [static]` Start to dequeue several objects from the ring. Note that user has to call appropriate dequeue\_finish() to complete given dequeue operation and actually remove objects the ring. **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 actual number of objects dequeued. Definition at line **313** of file **rte\_ring\_peek.h**. ### static \_\_rte\_always\_inline void rte\_ring\_dequeue\_elem\_finish (struct rte\_ring \* r, unsigned int n)` [static]` Complete to dequeue several objects from the ring. Note that number of objects to dequeue 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 **331** of file **rte\_ring\_peek.h**. ### static \_\_rte\_always\_inline void rte\_ring\_dequeue\_finish (struct rte\_ring \* r, unsigned int n)` [static]` Complete to dequeue several objects from the ring. Note that number of objects to dequeue 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 **363** of file **rte\_ring\_peek.h**. ## Author Generated automatically by Doxygen for DPDK from the source code.