DPDK  16.07.2
Macros | Functions
rte_distributor.h File Reference

Go to the source code of this file.

Macros

#define RTE_DISTRIBUTOR_NAMESIZE   32

Functions

struct rte_distributor * rte_distributor_create (const char *name, unsigned socket_id, unsigned num_workers)
int rte_distributor_process (struct rte_distributor *d, struct rte_mbuf **mbufs, unsigned num_mbufs)
int rte_distributor_returned_pkts (struct rte_distributor *d, struct rte_mbuf **mbufs, unsigned max_mbufs)
int rte_distributor_flush (struct rte_distributor *d)
void rte_distributor_clear_returns (struct rte_distributor *d)
struct rte_mbufrte_distributor_get_pkt (struct rte_distributor *d, unsigned worker_id, struct rte_mbuf *oldpkt)
int rte_distributor_return_pkt (struct rte_distributor *d, unsigned worker_id, struct rte_mbuf *mbuf)
void rte_distributor_request_pkt (struct rte_distributor *d, unsigned worker_id, struct rte_mbuf *oldpkt)
struct rte_mbufrte_distributor_poll_pkt (struct rte_distributor *d, unsigned worker_id)

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.

Macro Definition Documentation

#define RTE_DISTRIBUTOR_NAMESIZE   32

Length of name for instance

Definition at line 49 of file rte_distributor.h.

Function Documentation

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

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
nameThe name to be given to the distributor instance.
socket_idThe NUMA node on which the memory is to be allocated
num_workersThe maximum number of workers that will request packets from this distributor
Returns
The newly created distributor instance
Examples:
distributor/main.c.
int rte_distributor_process ( struct rte_distributor *  d,
struct rte_mbuf **  mbufs,
unsigned  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 procesed 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
dThe distributor instance to be used
mbufsThe mbufs to be distributed
num_mbufsThe number of mbufs in the mbufs array
Returns
The number of mbufs processed.
Examples:
distributor/main.c.
int rte_distributor_returned_pkts ( struct rte_distributor *  d,
struct rte_mbuf **  mbufs,
unsigned  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
dThe distributor instance to be used
mbufsThe mbufs pointer array to be filled in
max_mbufsThe size of the mbufs array
Returns
The number of mbufs returned in the mbufs array.
Examples:
distributor/main.c.
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
dThe distributor instance to be used
Returns
The number of queued/in-flight packets that were completed by this call.
Examples:
distributor/main.c.
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
dThe distributor instance to be used
struct rte_mbuf* rte_distributor_get_pkt ( struct rte_distributor *  d,
unsigned  worker_id,
struct rte_mbuf oldpkt 
)
read

API called by a worker to get a new packet to process. Any previous packet given to the worker is assumed to have completed processing, and may be optionally returned to the distributor via the oldpkt parameter.

Parameters
dThe distributor instance to be used
worker_idThe worker instance number to use - must be less that num_workers passed at distributor creation time.
oldpktThe previous packet, if any, being processed by the worker
Returns
A new packet to be processed by the worker thread.
Examples:
distributor/main.c.
int rte_distributor_return_pkt ( struct rte_distributor *  d,
unsigned  worker_id,
struct rte_mbuf mbuf 
)

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
dThe distributor instance to be used
worker_idThe worker instance number to use - must be less that num_workers passed at distributor creation time.
mbufThe previous packet being processed by the worker
void rte_distributor_request_pkt ( struct rte_distributor *  d,
unsigned  worker_id,
struct rte_mbuf oldpkt 
)

API called by a worker to request a new packet to process. Any previous packet given to the worker is 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 a new packet to be provided by the distributor.

NOTE: after calling this function, rte_distributor_poll_pkt() should be used to poll for the packet requested. The rte_distributor_get_pkt() API should not be used to try and retrieve the new packet.

Parameters
dThe distributor instance to be used
worker_idThe worker instance number to use - must be less that num_workers passed at distributor creation time.
oldpktThe previous packet, if any, being processed by the worker
struct rte_mbuf* rte_distributor_poll_pkt ( struct rte_distributor *  d,
unsigned  worker_id 
)
read

API called by a worker to check for a new packet that was previously requested by a call to rte_distributor_request_pkt(). It does not wait for the new packet to be available, but returns NULL if the request has not yet been fulfilled by the distributor.

Parameters
dThe distributor instance to be used
worker_idThe worker instance number to use - must be less that num_workers passed at distributor creation time.
Returns
A new packet to be processed by the worker thread, or NULL if no packet is yet available.