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

Data Structures
struct	rte_dispatcher_stats

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.

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

Definition in file rte_dispatcher.h.

Typedef Documentation

◆ rte_dispatcher_match_t

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 application is not expected to process the event at the point of the match call. Such matters should be deferred to the process callback invocation.

The match callback may be used as an opportunity to prefetch data.

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.

Definition at line 56 of file rte_dispatcher.h.

◆ rte_dispatcher_process_t

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.

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.

◆ rte_dispatcher_finalize_t

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.

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.

Function Documentation

◆ rte_dispatcher_create()

__rte_experimental struct rte_dispatcher * rte_dispatcher_create ( uint8_t event_dev_id )

Create a dispatcher with the specified id.

Parameters

event_dev_id The identifier of the event device from which this dispatcher will dequeue events.

Returns: A pointer to a new dispatcher instance, or NULL on failure, in which case rte_errno is set.

◆ rte_dispatcher_free()

__rte_experimental int rte_dispatcher_free ( struct rte_dispatcher * dispatcher )

Free a dispatcher.

Parameters

dispatcher The dispatcher instance.

Returns

0: Success
<0: Error code on failure

◆ rte_dispatcher_service_id_get()

__rte_experimental uint32_t rte_dispatcher_service_id_get ( const struct rte_dispatcher * dispatcher )

Retrieve the service identifier of a dispatcher.

Parameters

dispatcher The dispatcher instance.

Returns: The dispatcher service's id.

◆ 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
	)

Binds an event device port to a specific lcore on the specified dispatcher.

This function configures the event port id to be used by the event dispatcher service, if run on the specified lcore.

Multiple event device ports may be bound to the same lcore. A particular port must not be bound to more than one lcore.

If the dispatcher service is mapped (with rte_service_map_lcore_set()) to a lcore to which no ports are bound, the service function will be a no-operation.

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

Parameters

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: Unable to allocate sufficient resources.
-EEXISTS: Event port is already configured.
-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
	)

Unbind 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 lcore specified by lcore_id.

Parameters

dispatcher	The dispatcher instance.
event_port_id	The event device port identifier.
lcore_id	The lcore which was using this event port.

Returns

0: Success
-ENOENT: Event port id not bound to this lcore_id.

◆ 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.

The match callback function is used to select if a particular event should be delivered, using the corresponding process callback function.

The reason for having two distinct steps is to allow the dispatcher to deliver all events as a batch. This in turn will cause processing of a particular kind of events to happen in a back-to-back manner, improving cache locality.

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

An event is delivered to at most one handler. Events where no handler is found are dropped.

The application must not depend on the order of which the match functions are invoked.

Ordering of events is not guaranteed to be maintained between different deliver callbacks. For example, suppose there are two callbacks registered, matching different subsets of events arriving on an atomic queue. A batch of events [ev0, ev1, ev2] are dequeued on a particular port, all pertaining to the same flow. The match callback for registration A returns true for ev0 and ev2, and the matching function for registration B 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.

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.

Parameters

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.

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

Parameters

dispatcher	The dispatcher instance.
handler_id	The handler registration id returned by the original rte_dispatcher_register() call.

Returns

0: Success
-EINVAL: The handler_id parameter was invalid.

◆ 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.

An application may optionally install one or more finalize callbacks.

All finalize callbacks are invoked by the dispatcher when a complete batch of events (retrieve using rte_event_dequeue_burst()) have been delivered to the application (or have been dropped).

The finalize callback is not tied to any particular handler.

The finalize callback provides an opportunity for the application to do per-batch processing. One case where this may be useful is if an event output buffer is used, and is shared among several handlers. In such a case, proper output buffer flushing may be assured using a finalize callback.

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.

Parameters

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.

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

Parameters

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()

__rte_experimental void rte_dispatcher_start ( struct rte_dispatcher * dispatcher )

Start a dispatcher instance.

Enables the dispatcher service.

The underlying event device must have been started prior to calling rte_dispatcher_start().

For the dispatcher to actually perform work (i.e., dispatch events), its service must have been mapped to one or more service lcores, and its service run state set to '1'. A dispatcher's service is retrieved using rte_dispatcher_service_id_get().

Each service lcore to which the dispatcher is mapped should have at least one event port configured. Such configuration is performed by calling rte_dispatcher_bind_port_to_lcore(), prior to starting the dispatcher.

Parameters

dispatcher The dispatcher instance.

◆ rte_dispatcher_stop()

__rte_experimental void rte_dispatcher_stop ( struct rte_dispatcher * dispatcher )

Stop a running dispatcher instance.

Disables the dispatcher service.

Parameters

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.

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

Parameters

	dispatcher	The dispatcher instance.
[out]	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.

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

Parameters

dispatcher The dispatcher instance.

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ rte_dispatcher_match_t

◆ rte_dispatcher_process_t

◆ rte_dispatcher_finalize_t

Function Documentation

◆ rte_dispatcher_create()

◆ rte_dispatcher_free()

◆ rte_dispatcher_service_id_get()

◆ rte_dispatcher_bind_port_to_lcore()

◆ rte_dispatcher_unbind_port_from_lcore()

◆ rte_dispatcher_register()

◆ rte_dispatcher_unregister()

◆ rte_dispatcher_finalize_register()

◆ rte_dispatcher_finalize_unregister()

◆ rte_dispatcher_start()

◆ rte_dispatcher_stop()

◆ rte_dispatcher_stats_get()

◆ rte_dispatcher_stats_reset()