File descriptor group utility functions. More...

Data Structures
struct	spdk_event_handler_opts

Macros
#define	SPDK_FD_GROUP_ADD(fgrp, efd, fn, arg) spdk_fd_group_add(fgrp, efd, fn, arg, #fn)

#define	SPDK_FD_GROUP_ADD_EXT(fgrp, efd, fn, arg, opts) spdk_fd_group_add_ext(fgrp, efd, fn, arg, #fn, opts)

Typedefs
typedef int(*	spdk_fd_fn) (void *ctx)
	Callback function registered for the event source file descriptor.

typedef int(*	spdk_fd_group_wrapper_fn) (void wrapper_ctx, spdk_fd_fn cb_fn, void cb_ctx)

Enumerations
enum	spdk_fd_type { SPDK_FD_TYPE_DEFAULT = 0x0 , SPDK_FD_TYPE_EVENTFD = 0x1 }
	File descriptor type. More...

Functions
	SPDK_STATIC_ASSERT (sizeof(struct spdk_event_handler_opts)==16, "Incorrect size")

void	spdk_fd_group_get_default_event_handler_opts (struct spdk_event_handler_opts *opts, size_t opts_size)
	Initialize a spdk_event_handler_opts structure to the default values.

int	spdk_fd_group_create (struct spdk_fd_group **fgrp)
	Initialize one fd_group.

void	spdk_fd_group_destroy (struct spdk_fd_group *fgrp)
	Release all resources associated with this fgrp.

int	spdk_fd_group_wait (struct spdk_fd_group *fgrp, int timeout)
	Wait for new events generated inside fgrp, and process them with their registered spdk_fd_fn.

int	spdk_fd_group_get_fd (struct spdk_fd_group *fgrp)
	Return the internal epoll_fd of specific fd_group.

int	spdk_fd_group_nest (struct spdk_fd_group parent, struct spdk_fd_group child)
	Nest the child fd_group in the parent fd_group.

int	spdk_fd_group_unnest (struct spdk_fd_group parent, struct spdk_fd_group child)
	Remove the nested child from the parent.

int	spdk_fd_group_add (struct spdk_fd_group fgrp, int efd, spdk_fd_fn fn, void arg, const char *name)
	Register SPDK_INTERRUPT_EVENT_IN event source to specified fgrp.

int	spdk_fd_group_add_for_events (struct spdk_fd_group fgrp, int efd, uint32_t events, spdk_fd_fn fn, void arg, const char *name)
	Register one event source to specified fgrp with specific event types.

int	spdk_fd_group_add_ext (struct spdk_fd_group fgrp, int efd, spdk_fd_fn fn, void arg, const char name, struct spdk_event_handler_opts opts)
	Register one event type stated in spdk_event_handler_opts agrument to the specified fgrp.

void	spdk_fd_group_remove (struct spdk_fd_group *fgrp, int efd)
	Unregister one event source from one fgrp.

int	spdk_fd_group_event_modify (struct spdk_fd_group *fgrp, int efd, int event_types)
	Change the event notification types associated with the event source.

int	spdk_fd_group_get_epoll_event (struct epoll_event *event)
	Copies the epoll(7) event that caused a callback function to execute.

int	spdk_fd_group_set_wrapper (struct spdk_fd_group fgrp, spdk_fd_group_wrapper_fn cb_fn, void cb_ctx)
	Set a wrapper function to be called when an epoll(7) event is received.

Detailed Description

File descriptor group utility functions.

Typedef Documentation

◆ spdk_fd_fn

typedef int(* spdk_fd_fn) (void *ctx)

Callback function registered for the event source file descriptor.

Parameters

ctx	Context passed as arg to spdk_fd_group_add().

Returns: 0 to indicate that event notification took place but no events were found; positive to indicate that event notification took place and some events were processed; negative if no event information is provided.

Enumeration Type Documentation

◆ spdk_fd_type

enum spdk_fd_type

File descriptor type.

The event handler may have extra checks and can do extra processing based on this.

Enumerator

SPDK_FD_TYPE_EVENTFD

Event file descriptors.

Once an event is generated on these file descriptors, event handler will perform a read operation on it to reset its internal eventfd object counter value to 0.

Function Documentation

◆ spdk_fd_group_add()

int spdk_fd_group_add	(	struct spdk_fd_group *	fgrp,
		int	efd,
		spdk_fd_fn	fn,
		void *	arg,
		const char *	name )

Register SPDK_INTERRUPT_EVENT_IN event source to specified fgrp.

Use spdk_fd_group_add_for_events() for other event types.

Parameters

fgrp	The fgrp registered to.
efd	File descriptor of the event source.
fn	Called each time there are events in event source.
arg	Function argument for fn.
name	Name of the event source.

Returns: 0 on success, negated errno on failure.

◆ spdk_fd_group_add_ext()

int spdk_fd_group_add_ext	(	struct spdk_fd_group *	fgrp,
		int	efd,
		spdk_fd_fn	fn,
		void *	arg,
		const char *	name,
		struct spdk_event_handler_opts *	opts )

Register one event type stated in spdk_event_handler_opts agrument to the specified fgrp.

spdk_event_handler_opts argument consists of event which is a bit mask composed by ORing together enum spdk_interrupt_event_types values. It also consists of fd_type, which can be used by event handler to perform extra checks during the spdk_fd_group_wait call.

Parameters

fgrp	The fgrp registered to.
efd	File descriptor of the event source.
fn	Called each time there are events in event source.
arg	Function argument for fn.
name	Name of the event source.
opts	Extended event handler option.

Returns: 0 if success or -errno if failed

◆ spdk_fd_group_add_for_events()

int spdk_fd_group_add_for_events	(	struct spdk_fd_group *	fgrp,
		int	efd,
		uint32_t	events,
		spdk_fd_fn	fn,
		void *	arg,
		const char *	name )

Register one event source to specified fgrp with specific event types.

Event types argument is a bit mask composed by ORing together enum spdk_interrupt_event_types values.

Parameters

fgrp	The fgrp registered to.
efd	File descriptor of the event source.
events	Event notification types.
fn	Called each time there are events in event source.
arg	Function argument for fn.
name	Name of the event source.

Returns: 0 on success, negated errno on failure.

◆ spdk_fd_group_create()

int spdk_fd_group_create ( struct spdk_fd_group ** fgrp )

Initialize one fd_group.

Parameters

fgrp	A pointer to return the initialized fgrp.

Returns: 0 on success, negated errno on failure.

◆ spdk_fd_group_destroy()

void spdk_fd_group_destroy ( struct spdk_fd_group * fgrp )

Release all resources associated with this fgrp.

Users need to remove all event sources from the fgrp before destroying it.

Parameters

fgrp	The fgrp to destroy.

◆ spdk_fd_group_event_modify()

int spdk_fd_group_event_modify	(	struct spdk_fd_group *	fgrp,
		int	efd,
		int	event_types )

Change the event notification types associated with the event source.

Modules like nbd, need this api to add EPOLLOUT when having data to send, and remove EPOLLOUT if no data to send.

Parameters

fgrp	The fgrp registered to.
efd	File descriptor of the event source.
event_types	The event notification types.

Returns: 0 on success, negated errno on failure.

◆ spdk_fd_group_get_default_event_handler_opts()

void spdk_fd_group_get_default_event_handler_opts	(	struct spdk_event_handler_opts *	opts,
		size_t	opts_size )

Initialize a spdk_event_handler_opts structure to the default values.

Parameters

[out]	opts	Will be filled with default option.
	opts_size	Must be the size of spdk_event_handler_opts structure.

◆ spdk_fd_group_get_epoll_event()

int spdk_fd_group_get_epoll_event ( struct epoll_event * event )

Copies the epoll(7) event that caused a callback function to execute.

This function can only be called by the callback function, doing otherwise results in undefined behavior.

Parameters

event pointer to an epoll(7) event to copy to.

Returns: 0 on success, negated errno on failure.

◆ spdk_fd_group_get_fd()

int spdk_fd_group_get_fd ( struct spdk_fd_group * fgrp )

Return the internal epoll_fd of specific fd_group.

Parameters

fgrp	The pointer of specified fgrp.

Returns: The epoll_fd of specific fgrp.

◆ spdk_fd_group_nest()

int spdk_fd_group_nest	(	struct spdk_fd_group *	parent,
		struct spdk_fd_group *	child )

Nest the child fd_group in the parent fd_group.

After this operation completes, calling spdk_fd_group_wait() on the parent will include events from the child.

Parameters

parent	The parent fd_group.
child	The child fd_group.

Returns: 0 on success. Negated errno on failure. However, on all errno values other than -ENOTRECOVERABLE, the operation has not changed the state of the fd_group.

◆ spdk_fd_group_remove()

void spdk_fd_group_remove	(	struct spdk_fd_group *	fgrp,
		int	efd )

Unregister one event source from one fgrp.

Parameters

fgrp	The fgrp registered to.
efd	File descriptor of the event source.

◆ spdk_fd_group_set_wrapper()

int spdk_fd_group_set_wrapper	(	struct spdk_fd_group *	fgrp,
		spdk_fd_group_wrapper_fn	cb_fn,
		void *	cb_ctx )

Set a wrapper function to be called when an epoll(7) event is received.

The callback associated with that event is passed to the wrapper, which is responsible for executing it. Only one wrapper can be assigned to an fd_group at a time.

Parameters

fgrp	fd group.
cb_fn	Wrapper callback.
cb_ctx	Wrapper callback's context.

Returns: 0 on success, negative errno otherwise.

◆ spdk_fd_group_unnest()

int spdk_fd_group_unnest	(	struct spdk_fd_group *	parent,
		struct spdk_fd_group *	child )

Remove the nested child from the parent.

Parameters

parent	The parent fd_group.
child	The child fd_group.

Returns: 0 on success. Negated errno on failure. However, on all errno values other than -ENOTRECOVERABLE, the operation has not changed the state of the fd_group.

◆ spdk_fd_group_wait()

int spdk_fd_group_wait	(	struct spdk_fd_group *	fgrp,
		int	timeout )

Wait for new events generated inside fgrp, and process them with their registered spdk_fd_fn.

Parameters

fgrp	The fgrp to wait and process.
timeout	Specifies the number of milliseconds that will block. -1 causes indefinitely blocking; 0 causes immediately return.

Returns: the number of events processed on success, negated errno on failure.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ spdk_fd_fn

Enumeration Type Documentation

◆ spdk_fd_type

Function Documentation

◆ spdk_fd_group_add()

◆ spdk_fd_group_add_ext()

◆ spdk_fd_group_add_for_events()

◆ spdk_fd_group_create()

◆ spdk_fd_group_destroy()

◆ spdk_fd_group_event_modify()

◆ spdk_fd_group_get_default_event_handler_opts()

◆ spdk_fd_group_get_epoll_event()

◆ spdk_fd_group_get_fd()

◆ spdk_fd_group_nest()

◆ spdk_fd_group_remove()

◆ spdk_fd_group_set_wrapper()

◆ spdk_fd_group_unnest()

◆ spdk_fd_group_wait()