Polling Groups

Functions for managing polling groups and event handling. More...

Classes
struct	xlio_poll_group_attr
	Polling group attributes. More...

Macros
#define	XLIO_GROUP_FLAG_SAFE   0x1
#define	XLIO_GROUP_FLAG_DIRTY   0x2

Typedefs
typedef uintptr_t	xlio_poll_group_t
	Polling group handle. More...

Functions
int	xlio_poll_group_create (const struct xlio_poll_group_attr *attr, xlio_poll_group_t *group_out)
	Create a new polling group. More...
int	xlio_poll_group_destroy (xlio_poll_group_t group)
	Destroy a polling group. More...
int	xlio_poll_group_update (xlio_poll_group_t group, const struct xlio_poll_group_attr *attr)
	Update polling group attributes. More...
void	xlio_poll_group_poll (xlio_poll_group_t group)
	Poll for events on a polling group. More...

Detailed Description

Functions for managing polling groups and event handling.

Polling groups are the core event management mechanism in the XLIO Ultra API. They allow applications to register event callbacks and efficiently poll for network events across multiple sockets.

Polling group is a collection of sockets and resources required for their operation. Different polling groups can be used concurrently without serialization.

Polling groups provide loggical sockets organization for the following purposes:

• Achieving concurrency and scaling
• Implementing different RX / completion logic

Recommendations:

• Groups are expected to be long lived objects. Frequent creation/destruction has a penalty.
• Reduce the number of different network interfaces within a group to minimum. This will optimize the HW objects utilization. However, maintaining extra groups can have an overhead.

Macro Definition Documentation

XLIO_GROUP_FLAG_DIRTY

#define XLIO_GROUP_FLAG_DIRTY   0x2

Group will keep dirty sockets to be flushed with xlio_poll_group_flush().

XLIO_GROUP_FLAG_SAFE

#define XLIO_GROUP_FLAG_SAFE   0x1

Sockets and rings will be protected with locks regardless of XLIO configuration.

Typedef Documentation

xlio_poll_group_t

typedef uintptr_t xlio_poll_group_t

Polling group handle.

Opaque handle representing a polling group for event management.

Function Documentation

xlio_poll_group_create()

int xlio_poll_group_create	(	const struct xlio_poll_group_attr *	attr,
		xlio_poll_group_t *	group_out
	)

Create a new polling group.

Creates a new polling group with the specified attributes. Event callbacks are registered per group, allowing applications to implement different handling logic for different types of connections.

Parameters

attr	Polling group attributes
group_out	Pointer to store the created group handle

Returns

0 on success, -1 on error (errno is set)

Error Codes:

• EINVAL: Invalid parameters (group_out is NULL, attr is NULL, or socket_event_cb is NULL)
• ENOMEM: Insufficient memory

Note

socket_event_cb is mandatory.

See also

xlio_poll_group_destroy()

xlio_poll_group_attr

xlio_poll_group_destroy()

int xlio_poll_group_destroy

(

xlio_poll_group_t

group

)

Destroy a polling group.

Destroys the specified polling group and frees associated resources. All leftover sockets associated with this group are destroyed implicitly.

Parameters

group

The polling group to destroy

Returns

0 on success, -1 on error

xlio_poll_group_poll()

void xlio_poll_group_poll

(

xlio_poll_group_t

group

)

Poll for events on a polling group.

This is the main event processing function. It polls hardware for events, executes TCP timers, and invokes registered callbacks. Most network events are processed from the context of this call.

Parameters

group

The polling group to poll

Note

This function should be called regularly in the main event loop. It's non-blocking and will return immediately if no events are available.

xlio_poll_group_update()

int xlio_poll_group_update	(	xlio_poll_group_t	group,
		const struct xlio_poll_group_attr *	attr
	)

Update polling group attributes.

Updates the attributes of an existing polling group. This allows changing callback functions or flags without recreating the group.

Parameters

group	The polling group to update
attr	New attributes for the group

Returns

0 on success, -1 on error (errno is set)

Error Codes:

• EINVAL: Invalid parameters (attr is NULL or socket_event_cb is NULL)