rte_distributor.h(3)

📦
version 25.11.3 · 9 versions
, in ubuntu resolute, ubuntu stonking

✨ rte_distributor.h ✨

okay so bestie, you're reading the manual page for rte_distributor.h — yes, THAT one, the DPDK header that's out here doing dynamic load balancing like it's the main character. Library Functions Manual energy. Let's get into it 💅

🎀 SYNOPSIS 🎀

functions (the whole squad)

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 💖

So the distributor is literally this component designed to pass packets one-at-a-time to workers, and it's doing dynamic load balancing while it's at it. No cap. It's out here keeping the vibes balanced so no worker is doing overtime while another one's on their phone.

Definition in file rte_distributor.h.

🦋 Function Documentation 🦋

👑 rte_distributor_create

struct rte_distributor * rte_distributor_create (const char * name, unsigned int socket_id, unsigned int num_workers, unsigned int alg_type)

The function that creates a brand new distributor instance, periodt. ✨

It reserves all the memory needed for distributor operations and initializes the distributor so it's ready to work with however many workers you configured.

Parameters

  • name — the name you're giving to this distributor instance, bestie.
  • socket_id — the NUMA node where the memory gets allocated.
  • num_workers — the maximum number of workers that will be requesting packets from this distributor.
  • alg_type — call the legacy API, or use the new burst API. legacy uses a 32-bit flow ID and works on a single packet at a time. Latest uses a 15-bit flow ID and works on up to 8 packets at a time to workers.

Returns

The newly created distributor instance 🫶

🔥 rte_distributor_process

int rte_distributor_process (struct rte_distributor * d, struct rte_mbuf ** mbufs, unsigned int num_mbufs)

This one processes a set of packets by distributing them among the workers that request packets. And here's the iconic part: the distributor makes sure that no two packets with the same flow id, or tag, in the mbuf get processed on different cores at the same time. Vibe-locked, fr fr.

The user is advocated to set the tag for each mbuf before calling this function. If you don't set the tag, the tag value can be various values depending on driver implementation and configuration. 🙈

not multi-thread safe!! This should only be called on a single lcore. Do not be out here calling it from everywhere, that's giving chaos.

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.

🧚 rte_distributor_returned_pkts

int rte_distributor_returned_pkts (struct rte_distributor * d, struct rte_mbuf ** mbufs, unsigned int max_mbufs)

Gets you a set of mbufs that have been returned to the distributor by the workers. It's giving "give me back my stuff" 💅

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.

💀 rte_distributor_flush

int rte_distributor_flush (struct rte_distributor * d)

Flushes the distributor component so that there are no in-flight or backlogged packets awaiting processing. Clean sweep, no crumbs left behind. ✨

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.

🎀 rte_distributor_clear_returns

void rte_distributor_clear_returns (struct rte_distributor * d)

Clears the array of returned packets — the one that's used as the source for the rte_distributor_returned_pkts() API call. Basically emptying the returns bin. 🗑️

This should only be called on the same lcore as rte_distributor_process().

Parameters

  • d — the distributor instance to be used.

🫶 rte_distributor_get_pkt

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 are assumed to have completed processing, and may be optionally returned to the distributor via the oldpkt parameter. So like, optionally. Your call, bestie. 💖

Parameters

  • d — the distributor instance to be used.
  • worker_id — the worker instance number to use — must be less than num_workers passed at distributor creation time. (yes, it says "less that" in the source, we all saw it, moving on 😭)
  • 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.

🌈 rte_distributor_return_pkt

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. It's the "I'm leaving, here's your stuff back" move. 👋

Parameters

  • d — the distributor instance to be used.
  • worker_id — the worker instance number to use — must be less than 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.

⭐ rte_distributor_request_pkt

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. And here's the plot twist: unlike rte_distributor_get_pkt(), this function does not wait for new packets to be provided by the distributor. It's non-blocking, it has places to be. 🏃‍♀️

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. Mixing those two up is not it, bestie.

Parameters

  • d — the distributor instance to be used.
  • worker_id — the worker instance number to use — must be less than num_workers passed at distributor creation time.
  • oldpkt — the returning packets, if any, processed by the worker.
  • count — the number of returning packets.

💜 rte_distributor_poll_pkt

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 — it just returns if the request hasn't yet been fulfilled by the distributor. Patience is not its thing. 🙈

Parameters

  • d — the distributor instance to be used.
  • worker_id — the worker instance number to use — must be less than 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. (the robots wrote it, we just made it cute 💖)

okay and that's the whole page bestie, you ate that 🫶 this manual page came from DPDK, Version 25.11.3, and it's the rte_distributor.h(3) page, slay 💅✨ no cap, go balance those packets 🌸

📦 where this page comes from