--- name: "rte_distributor.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_distributor.h" --- # rte\_distributor.h(3) ## NAME rte\_distributor.h ## SYNOPSIS ### Functions struct rte\_distributor \* **rte\_distributor\_create** (const char \*name, unsigned int socket\_id, unsigned int num\_workers, unsigned int alg\_type)\ int **rte\_distributor\_process** (struct rte\_distributor \*d, struct **rte\_mbuf** \*\*mbufs, unsigned int num\_mbufs)\ int **rte\_distributor\_returned\_pkts** (struct rte\_distributor \*d, struct **rte\_mbuf** \*\*mbufs, unsigned int max\_mbufs)\ int **rte\_distributor\_flush** (struct rte\_distributor \*d)\ void **rte\_distributor\_clear\_returns** (struct rte\_distributor \*d)\ int **rte\_distributor\_get\_pkt** (struct rte\_distributor \*d, unsigned int worker\_id, struct **rte\_mbuf** \*\*pkts, struct **rte\_mbuf** \*\*oldpkt, unsigned int retcount)\ int **rte\_distributor\_return\_pkt** (struct rte\_distributor \*d, unsigned int worker\_id, struct **rte\_mbuf** \*\*oldpkt, int num)\ void **rte\_distributor\_request\_pkt** (struct rte\_distributor \*d, unsigned int worker\_id, struct **rte\_mbuf** \*\*oldpkt, unsigned int count)\ int **rte\_distributor\_poll\_pkt** (struct rte\_distributor \*d, unsigned int worker\_id, struct **rte\_mbuf** \*\*mbufs)\ ## Detailed Description RTE distributor The distributor is a component which is designed to pass packets one-at-a-time to workers, with dynamic load balancing. Definition in file **rte\_distributor.h**. ## Function Documentation ### struct rte\_distributor \* rte\_distributor\_create (const char \* name, unsigned int socket\_id, unsigned int num\_workers, unsigned int alg\_type) Function to create a new distributor instance Reserves the memory needed for the distributor operation and initializes the distributor to work with the configured number of workers. **Parameters** *name* The name to be given to the distributor instance. \ *socket\_id* The NUMA node on which the memory is to be allocated \ *num\_workers* The maximum number of workers that will request packets from this distributor \ *alg\_type* Call the legacy API, or use the new burst API. legacy uses 32-bit flow ID, and works on a single packet at a time. Latest uses 15- bit flow ID and works on up to 8 packets at a time to workers. **Returns** The newly created distributor instance ### int rte\_distributor\_process (struct rte\_distributor \* d, struct rte\_mbuf \*\* mbufs, unsigned int num\_mbufs) Process a set of packets by distributing them among workers that request packets. The distributor will ensure that no two packets that have the same flow id, or tag, in the mbuf will be processed on different cores at the same time. The user is advocated to set tag for each mbuf before calling this function. If user doesn't set the tag, the tag value can be various values depending on driver implementation and configuration. This is not multi-thread safe and should only be called on a single lcore. **Parameters** *d* The distributor instance to be used \ *mbufs* The mbufs to be distributed \ *num\_mbufs* The number of mbufs in the mbufs array **Returns** The number of mbufs processed. ### int rte\_distributor\_returned\_pkts (struct rte\_distributor \* d, struct rte\_mbuf \*\* mbufs, unsigned int max\_mbufs) Get a set of mbufs that have been returned to the distributor by workers This should only be called on the same lcore as **rte\_distributor\_process()** **Parameters** *d* The distributor instance to be used \ *mbufs* The mbufs pointer array to be filled in \ *max\_mbufs* The size of the mbufs array **Returns** The number of mbufs returned in the mbufs array. ### int rte\_distributor\_flush (struct rte\_distributor \* d) Flush the distributor component, so that there are no in-flight or backlogged packets awaiting processing This should only be called on the same lcore as **rte\_distributor\_process()** **Parameters** *d* The distributor instance to be used **Returns** The number of queued/in-flight packets that were completed by this call. ### void rte\_distributor\_clear\_returns (struct rte\_distributor \* d) Clears the array of returned packets used as the source for the **rte\_distributor\_returned\_pkts()** API call. This should only be called on the same lcore as **rte\_distributor\_process()** **Parameters** *d* The distributor instance to be used ### int rte\_distributor\_get\_pkt (struct rte\_distributor \* d, unsigned int worker\_id, struct rte\_mbuf \*\* pkts, struct rte\_mbuf \*\* oldpkt, unsigned int retcount) API called by a worker to get new packets to process. Any previous packets given to the worker is assumed to have completed processing, and may be optionally returned to the distributor via the oldpkt parameter. **Parameters** *d* The distributor instance to be used \ *worker\_id* The worker instance number to use - must be less that num\_workers passed at distributor creation time. \ *pkts* The mbufs pointer array to be filled in (up to 8 packets) \ *oldpkt* The previous packets, if any, being processed by the worker \ *retcount* The number of packets being returned **Returns** The number of packets in the pkts array ### int rte\_distributor\_return\_pkt (struct rte\_distributor \* d, unsigned int worker\_id, struct rte\_mbuf \*\* oldpkt, int num) API called by a worker to return a completed packet without requesting a new packet, for example, because a worker thread is shutting down **Parameters** *d* The distributor instance to be used \ *worker\_id* The worker instance number to use - must be less that num\_workers passed at distributor creation time. \ *oldpkt* The previous packets being processed by the worker \ *num* The number of packets in the oldpkt array ### void rte\_distributor\_request\_pkt (struct rte\_distributor \* d, unsigned int worker\_id, struct rte\_mbuf \*\* oldpkt, unsigned int count) API called by a worker to request a new packet to process. Any previous packets given to the worker are assumed to have completed processing, and may be optionally returned to the distributor via the oldpkt parameter. Unlike **rte\_distributor\_get\_pkt()**, this function does not wait for new packets to be provided by the distributor. NOTE: after calling this function, **rte\_distributor\_poll\_pkt()** should be used to poll for the packets requested. The **rte\_distributor\_get\_pkt()** API should *not* be used to try and retrieve the new packets. **Parameters** *d* The distributor instance to be used \ *worker\_id* The worker instance number to use - must be less that num\_workers passed at distributor creation time. \ *oldpkt* The returning packets, if any, processed by the worker \ *count* The number of returning packets ### int rte\_distributor\_poll\_pkt (struct rte\_distributor \* d, unsigned int worker\_id, struct rte\_mbuf \*\* mbufs) API called by a worker to check for new packets that were previously requested by a call to **rte\_distributor\_request\_pkt()**. It does not wait for the new packets to be available, but returns if the request has not yet been fulfilled by the distributor. **Parameters** *d* The distributor instance to be used \ *worker\_id* The worker instance number to use - must be less that num\_workers passed at distributor creation time. \ *mbufs* The array of mbufs being given to the worker **Returns** The number of packets being given to the worker thread, -1 if no packets are yet available (burst API - RTE\_DIST\_ALG\_BURST) 0 if no packets are yet available (legacy single API - RTE\_DIST\_ALG\_SINGLE) ## Author Generated automatically by Doxygen for DPDK from the source code.