fd_group.h File Reference

File descriptor group utility functions. More...

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

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

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

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.

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 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 if success or -errno if failed

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 if success or -errno if failed

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 if success or -errno if failed

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, -errno on error

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_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 processed events or -errno if failed