rte_dispatcher.h(3)

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

💖 rte_dispatcher.h 💖

okay bestie, welcome to rte_dispatcher.h(3) — yes it's a real manpage, yes it's from the Library Functions Manual, and yes we're gonna get through it together. grab a boba, bc this is part 1 of 2 and there's a LOT of slay ahead 🌸

✨ NAME ✨

rte_dispatcher.h — like, the whole file, that's the name, that's it, no notes 🎀

🦋 SYNOPSIS 🦋

okay so first you gotta pull in the headers, no cap:

#include <stdbool.h>
#include <stdint.h>
#include <rte_compat.h>
#include <rte_eventdev.h>

🌈 Data Structures

  • struct rte_dispatcher_stats — yeah that's the one struct, she's lowkey the whole vibe

🧚 Typedefs

  • typedef bool(* rte_dispatcher_match_t) (const struct rte_event *event, void *cb_data)
  • typedef void(* rte_dispatcher_process_t) (uint8_t event_dev_id, uint8_t event_port_id, struct rte_event *events, uint16_t num, void *cb_data)
  • typedef void(* rte_dispatcher_finalize_t) (uint8_t event_dev_id, uint8_t event_port_id, void *cb_data)

👑 Functions

  • __rte_experimental struct rte_dispatcher * rte_dispatcher_create (uint8_t event_dev_id)
  • __rte_experimental int rte_dispatcher_free (struct rte_dispatcher *dispatcher)
  • __rte_experimental uint32_t rte_dispatcher_service_id_get (const struct rte_dispatcher *dispatcher)
  • __rte_experimental int rte_dispatcher_bind_port_to_lcore (struct rte_dispatcher *dispatcher, uint8_t event_port_id, uint16_t batch_size, uint64_t timeout, unsigned int lcore_id)
  • __rte_experimental int rte_dispatcher_unbind_port_from_lcore (struct rte_dispatcher *dispatcher, uint8_t event_port_id, unsigned int lcore_id)
  • __rte_experimental int rte_dispatcher_register (struct rte_dispatcher *dispatcher, rte_dispatcher_match_t match_fun, void *match_cb_data, rte_dispatcher_process_t process_fun, void *process_cb_data)
  • __rte_experimental int rte_dispatcher_unregister (struct rte_dispatcher *dispatcher, int handler_id)
  • __rte_experimental int rte_dispatcher_finalize_register (struct rte_dispatcher *dispatcher, rte_dispatcher_finalize_t finalize_fun, void *finalize_data)
  • __rte_experimental int rte_dispatcher_finalize_unregister (struct rte_dispatcher *dispatcher, int reg_id)
  • __rte_experimental void rte_dispatcher_start (struct rte_dispatcher *dispatcher)
  • __rte_experimental void rte_dispatcher_stop (struct rte_dispatcher *dispatcher)
  • __rte_experimental void rte_dispatcher_stats_get (const struct rte_dispatcher *dispatcher, struct rte_dispatcher_stats *stats)
  • __rte_experimental void rte_dispatcher_stats_reset (struct rte_dispatcher *dispatcher)

🌸 Detailed Description 🌸

RTE Dispatcher

Warning ⚠️ EXPERIMENTAL: All functions in this file may be changed or removed without prior notice. like… she's not committed to you bestie, she's experimental, she can ghost ANY TIME 💀 do NOT build your whole personality around her API, fr fr.

okay so the purpose of the dispatcher is to help decouple different parts of an application (e.g., modules), sharing the same underlying event device.

it's giving matchmaker energy 🫶 — like, multiple modules all wanna talk to the same event device, and the dispatcher is the bestie in the group chat who forwards everyone's messages so nobody has to text them directly. iconic.

Definition in file rte_dispatcher.h.

🎀 Typedef Documentation 🎀

typedef bool(* rte_dispatcher_match_t) (const struct rte_event *event, void *cb_data)

Function prototype for match callbacks. ✨

Match callbacks are used by an application to decide how the dispatcher distributes events to different parts of the application.

the way that this works is: your app gets to be the bouncer at the club door, deciding which events get let in and which get sent to which module. main character behavior honestly 💅

The application is not expected to process the event at the point of the match call. no no no, do NOT do the actual work here bestie. Such matters should be deferred to the process callback invocation. (she's like "okay i see you but deal with it in the process callback, not now")

The match callback may be used as an opportunity to prefetch data. lowkey a little pro move, highkey valid 🌈

Parameters

  • event — Pointer to event
  • cb_data — The pointer supplied by the application in rte_dispatcher_register().

Returns

Returns true in case this event should be delivered (via the process callback), and false otherwise. yes/yes or no/no, that's the vibe check 🔥

Definition at line 56 of file rte_dispatcher.h.

typedef void(* rte_dispatcher_process_t) (uint8_t event_dev_id, uint8_t event_port_id, struct rte_event *events, uint16_t num, void *cb_data)

Function prototype for process callbacks. 💖

The process callbacks are used by the dispatcher to deliver events for processing. THIS is where the actual work happens, bestie — the events show up, you do the thing, no takebacks 🌸

Parameters

  • event_dev_id — The originating event device id.
  • event_port_id — The originating event port.
  • events — Pointer to an array of events.
  • num — The number of events in the events array.
  • cb_data — The pointer supplied by the application in rte_dispatcher_register().

Definition at line 81 of file rte_dispatcher.h.

typedef void(* rte_dispatcher_finalize_t) (uint8_t event_dev_id, uint8_t event_port_id, void *cb_data)

Function prototype for finalize callbacks. 🦋

The finalize callbacks are used by the dispatcher to notify the application it has delivered all events from a particular batch dequeued from the event device. it's the "okay that's a wrap on this batch, you may now exhale" notification, essentially periodt 💅

Parameters

  • event_dev_id — The originating event device id.
  • event_port_id — The originating event port.
  • cb_data — The pointer supplied by the application in rte_dispatcher_finalize_register().

Definition at line 102 of file rte_dispatcher.h.

and that's part 1 bestie!! part 2 is loading, don't go anywhere 🫶✨

🫶 rte_dispatcher_create() 🫶

__rte_experimental struct rte_dispatcher *rte_dispatcher_create(uint8_t event_dev_id)

Bestie, this is the glow-up moment — it makes you a brand-new dispatcher with the id you picked. ✨

Params:

  • event_dev_id — the identifier of the event device that this dispatcher is gonna dequeue events from. That's its whole personality.

Returns:

  • a pointer to a fresh new dispatcher instance 💅
  • or NULL if it flops, and in that case rte_errno gets set so you know what went wrong.

💀 rte_dispatcher_free() 💀

__rte_experimental int rte_dispatcher_free(struct rte_dispatcher *dispatcher)

Say bye-bye, it's over, we're freeing the dispatcher. 🎀

Params:

  • dispatcher — the dispatcher instance.

Returns:

  • 0: success, iconic
  • <0: error code on failure 😭

⭐ rte_dispatcher_service_id_get() ⭐

__rte_experimental uint32_t rte_dispatcher_service_id_get(const struct rte_dispatcher *dispatcher)

Give me the service identifier for this dispatcher, quick.

Params:

  • dispatcher — the dispatcher instance.

Returns: the dispatcher service's id. That's it, that's the whole thing. 👑

🌸 rte_dispatcher_bind_port_to_lcore() 🌸

__rte_experimental int rte_dispatcher_bind_port_to_lcore(struct rte_dispatcher *dispatcher, uint8_t event_port_id, uint16_t batch_size, uint64_t timeout, unsigned int lcore_id)

Okay so this one matches up an event device port with a specific lcore on the dispatcher you hand it — it's giving matchmaker energy. 💖

What it's actually doing: it configures the event port id that the dispatcher service is gonna use, if it runs on the lcore you specify.

Real talk about the rules here:

  • Multiple event device ports can be bound to the same lcore. No jealousy, we're poly.
  • But a particular port must not be bound to more than one lcore. That's a hard no. 🙈

Also: if the dispatcher service gets mapped (via rte_service_map_lcore_set()) to an lcore that has zero ports bound to it, the service function is just gonna be a no-operation. It's literally not doing anything bestie, it's on standby.

This function may be called by any thread (including unregistered non-EAL threads) — but not while the dispatcher is running on the lcore specified by lcore_id. Do not do that.

Params:

  • dispatcher — the dispatcher instance.
  • event_port_id — the event device port identifier.
  • batch_size — the batch size to use in rte_event_dequeue_burst(), for the configured event device port and lcore.
  • timeout — the timeout parameter to use in rte_event_dequeue_burst(), for the configured event device port and lcore.
  • lcore_id — the lcore by which this event port will be used.

Returns:

  • 0: success ✨
  • -ENOMEM: can't allocate enough resources, tragic
  • -EEXISTS: this event port is already configured, girl we been knew
  • -EINVAL: invalid arguments

🧚 rte_dispatcher_unbind_port_from_lcore() 🧚

__rte_experimental int rte_dispatcher_unbind_port_from_lcore(struct rte_dispatcher *dispatcher, uint8_t event_port_id, unsigned int lcore_id)

The breakup function 🥀 — it unbinds an event device port from a specific lcore.

This function may be called by any thread (including unregistered non-EAL threads), but not while the dispatcher is running on the lcore specified by lcore_id.

Params:

  • dispatcher — the dispatcher instance.
  • event_port_id — the event device port identifier.
  • lcore_id — the lcore which was using this event port (aka the ex).

Returns:

  • 0: success
  • -ENOENT: this event port id was never bound to this lcore_id. Nothing to unbind, nothing to mourn.

🔥 rte_dispatcher_register() 🔥

__rte_experimental int rte_dispatcher_register(struct rte_dispatcher *dispatcher, rte_dispatcher_match_t match_fun, void *match_cb_data, rte_dispatcher_process_t process_fun, void *process_cb_data)

Register an event handler, bestie. This is where you tell the dispatcher how to sort your events. 🎯

Here's the lore: the match callback function is what decides whether a particular event should be delivered, and the corresponding process callback function is what actually handles it.

Why two separate steps though? Because it lets the dispatcher deliver all the events as a batch, which means a particular kind of event gets processed back-to-back, and that improves cache locality. Cache-brained king behavior. 👑

The list of handler callback functions is shared among all lcores — but it will only be executed on lcores that have an eventdev port bound to them and that are running the dispatcher service.

An event is delivered to at most one handler. Events where no handler is found get dropped. 💀 Nobody matched, so it's gone.

The application must not depend on the order in which the match functions are invoked. Fr fr, do not do it.

Ordering of events is not guaranteed to be maintained between different deliver callbacks. Example time, because this one is a whole situation: suppose you've got two callbacks registered that match different subsets of events arriving on an atomic queue. A batch of events [ev0, ev1, ev2] gets dequeued on a particular port, and all of them pertain to the same flow. The match callback for registration A returns true for ev0 and ev2, and the matching function for registration B returns true for ev1. In that scenario, the dispatcher may choose to deliver first [ev0, ev2] using A's deliver function, and then [ev1] to B — or vice versa. Either way. No promises. 🙃

rte_dispatcher_register() may be called by any thread (including unregistered non-EAL threads), but not while the event dispatcher is running on any service lcore.

Params:

  • dispatcher — the dispatcher instance.
  • match_fun — the match callback function.
  • match_cb_data — a pointer to some application-specific opaque data (or NULL), which is supplied back to the application when match_fun is called.
  • process_fun — the process callback function.
  • process_cb_data — a pointer to some application-specific opaque data (or NULL), which is supplied back to the application when process_fun is called.

Returns:

  • >= 0: the identifier for this registration 🎀
  • -ENOMEM: unable to allocate sufficient resources

🦋 rte_dispatcher_unregister() 🦋

__rte_experimental int rte_dispatcher_unregister(struct rte_dispatcher *dispatcher, int handler_id)

Unregister an event handler. We're taking it off the roster.

This function may be called by any thread (including unregistered non-EAL threads), but not while the dispatcher is running on any service lcore.

Params:

  • dispatcher — the dispatcher instance.
  • handler_id — the handler registration id returned by the original rte_dispatcher_register() call. You gotta remember it, keep the receipt.

Returns:

  • 0: success
  • -EINVAL: the handler_id parameter was invalid, awk

🌈 rte_dispatcher_finalize_register() 🌈

__rte_experimental int rte_dispatcher_finalize_register(struct rte_dispatcher *dispatcher, rte_dispatcher_finalize_t finalize_fun, void *finalize_data)

Register a finalize callback function. ✨ Your app may optionally install one or more of these — zero, one, many, your call, no pressure.

All finalize callbacks are invoked by the dispatcher when a complete batch of events (retrieved using rte_event_dequeue_burst()) has been delivered to the application — or has been dropped. Either way, the batch is done, so the finalize runs.

Important: the finalize callback is not tied to any particular handler. She's independent. 💅

So what's the point? It gives the application an opportunity to do per-batch processing. One case where that's useful: if you're using an event output buffer and it's shared among several handlers. In that situation, you can make sure the output buffer gets flushed properly using a finalize callback. Knowledge drop. 🧠

rte_dispatcher_finalize_register() may be called by any thread (including unregistered non-EAL threads), but not while the dispatcher is running on any service lcore.

Params:

  • dispatcher — the dispatcher instance.
  • finalize_fun — the function called after completing the processing of a dequeue batch.
  • finalize_data — a pointer to some application-specific opaque data (or NULL), which is supplied back to the application when finalize_fun is called.

Returns:

  • >= 0: the identifier for this registration 🫶
  • -ENOMEM: unable to allocate sufficient resources

🍓 rte_dispatcher_finalize_unregister() 🍓

__rte_experimental int rte_dispatcher_finalize_unregister(struct rte_dispatcher *dispatcher, int reg_id)

Unregister a finalize callback. Closing that chapter. 🥀

This function may be called by any thread (including unregistered non-EAL threads), but not while the dispatcher is running on any service lcore.

Params:

  • dispatcher — the dispatcher instance.
  • reg_id — the finalize registration id returned by the original rte_dispatcher_finalize_register() call.

Returns:

  • 0: success
  • -EINVAL: the reg_id parameter was invalid

👑 rte_dispatcher_start() 👑 (main character moment)

__rte_experimental void rte_dispatcher_start(struct rte_dispatcher *dispatcher)

Start a dispatcher instance — this is the "enabling the dispatcher service" step. She's awake now. 💖

Checklist before you do this, bestie:

  • The underlying event device must have been started prior to calling rte_dispatcher_start(). Non-negotiable.
  • For the dispatcher to actually do work (aka actually dispatch events), its service must have been mapped to one or more service lcores, and its service run state must be set to '1'. A dispatcher's service is retrieved using rte_dispatcher_service_id_get().
  • Every service lcore the dispatcher is mapped to should have at least one event port configured. You do that by calling rte_dispatcher_bind_port_to_lcore(), and you do it before starting the dispatcher.

Params:

  • dispatcher — the dispatcher instance.

Returns nothing. It's void. It just goes. 🏃‍♀️

😭 rte_dispatcher_stop() 😭

__rte_experimental void rte_dispatcher_stop(struct rte_dispatcher *dispatcher)

Stop a running dispatcher instance. Disables the dispatcher service. Nap time for the dispatcher. 😴

Params:

  • dispatcher — the dispatcher instance.

📊 rte_dispatcher_stats_get() 📊

__rte_experimental void rte_dispatcher_stats_get(const struct rte_dispatcher *dispatcher, struct rte_dispatcher_stats *stats)

Retrieve statistics for a dispatcher instance — numbers, we love numbers. ✨

This function is MT safe and may be called by any thread (including unregistered non-EAL threads). Thread-safe queen. 👑

Params:

  • dispatcher — the dispatcher instance.
  • stats — a pointer to a structure to fill with statistics.

💅 rte_dispatcher_stats_reset() 💅

__rte_experimental void rte_dispatcher_stats_reset(struct rte_dispatcher *dispatcher)

Reset statistics for a dispatcher instance. Fresh start, clean slate, zeroes everywhere. 🎀

This function may be called by any thread (including unregistered non-EAL threads) — but heads up, it may not produce the correct result if the dispatcher is running on any service lcore. So maybe don't do that. 🙈

Params:

  • dispatcher — the dispatcher instance.

👑 AUTHOR 👑

Generated automatically by Doxygen for DPDK from the source code. Not me, not you, not a human — a robot did this. And honestly? It ate. 💅

That's the whole page, bestie — rte_dispatcher.h(3) from DPDK, Version 25.11.3. Go forth and dispatch responsibly, and remember: bind your ports before you start, don't unregister while it's running, and never trust event ordering between callbacks. 🦋 mwah, bye! 🫶💖✨

📦 where this page comes from