util/fd_group: improve logs and documentation

 *

 * \param fgrp A pointer to return the initialized fgrp.

 *

 * \return 0 if success or -errno if failed

 * \return 0 on success, negated errno on failure.

 */

int spdk_fd_group_create(struct spdk_fd_group **fgrp);

 * \param timeout Specifies the number of milliseconds that will block.

 * -1 causes indefinitely blocking; 0 causes immediately return.

 *

 * \return the number of processed events

 * or -errno if failed

 * \return the number of events processed on success, negated errno on failure.

 */

int spdk_fd_group_wait(struct spdk_fd_group *fgrp, int timeout);

 * \param arg Function argument for fn.

 * \param name Name of the event source.

 *

 * \return 0 if success or -errno if failed

 * \return 0 on success, negated errno on failure.

 */

int spdk_fd_group_add(struct spdk_fd_group *fgrp, int efd,

		      spdk_fd_fn fn, void *arg, const char *name);

 * \param arg Function argument for fn.

 * \param name Name of the event source.

 *

 * \return 0 if success or -errno if failed

 * \return 0 on success, negated errno on failure.

 */

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

 * \param efd File descriptor of the event source.

 * \param event_types The event notification types.

 *

 * \return 0 if success or -errno if failed

 * \return 0 on success, negated errno on failure.

 */

int spdk_fd_group_event_modify(struct spdk_fd_group *fgrp,

			       int efd, int event_types);

 * This function can only be called by the callback function, doing otherwise

 * results in undefined behavior.

 *

 * \param event pointer to an epoll(7) event to copy to

 * \return 0 on success, -errno on error

 * \param event pointer to an epoll(7) event to copy to.

 * \return 0 on success, negated errno on failure.

 */

int spdk_fd_group_get_epoll_event(struct epoll_event *event);

	EVENT_HANDLER_STATE_REMOVED,

};

/* file descriptor of the interrupt event */

/* Taking "ehdlr" as short name for file descriptor handler of the interrupt event. */

struct event_handler {

	TAILQ_ENTRY(event_handler)	next;

			}

			ret = -errno;

			SPDK_ERRLOG("Failed to remove fd %d from group: %s\n", ehdlr->fd, strerror(errno));

			SPDK_ERRLOG("Failed to remove fd: %d from group: %s\n",

				    ehdlr->fd, strerror(errno));

			goto recover;

		}

	}

	return 0;

recover:

	/* We failed to remove everything. Let's try to get everything put back into

	/* We failed to remove everything. Let's try to put everything back into

	 * the original group. */

	TAILQ_FOREACH(ehdlr, &grp->event_handlers, next) {

		epevent.events = ehdlr->events;

			}

			ret = -errno;

			SPDK_ERRLOG("Failed to add fd to fd group: %s\n", strerror(errno));

			SPDK_ERRLOG("Failed to add fd: %d to fd group: %s\n",

				    ehdlr->fd, strerror(errno));

			goto recover;

		}

	}

	}

	if (parent->parent) {

		/* More than one layer of nesting is not currently supported */

		/* More than one layer of nesting is currently not supported */

		assert(false);

		return -ENOTSUP;

	}

	epevent.data.ptr = ehdlr;

	rc = epoll_ctl(epfd, EPOLL_CTL_ADD, efd, &epevent);

	if (rc < 0) {

		SPDK_ERRLOG("Failed to add fd: %d to fd group(%p): %s\n",

			    efd, fgrp, strerror(errno));

		free(ehdlr);

		return -errno;

	}

	int epfd;

	if (fgrp == NULL || efd < 0) {

		SPDK_ERRLOG("Invalid to remove efd(%d) from fd_group(%p).\n", efd, fgrp);

		SPDK_ERRLOG("Cannot remove fd: %d from fd group(%p)\n", efd, fgrp);

		assert(0);

		return;

	}

	}

	if (ehdlr == NULL) {

		SPDK_ERRLOG("efd(%d) is not existed in fgrp(%p)\n", efd, fgrp);

		SPDK_ERRLOG("fd: %d doesn't exist in fd group(%p)\n", efd, fgrp);

		return;

	}

	rc = epoll_ctl(epfd, EPOLL_CTL_DEL, ehdlr->fd, NULL);

	if (rc < 0) {

		SPDK_ERRLOG("Failed to delete the fd(%d) from the epoll group(%p)\n", efd, fgrp);

		SPDK_ERRLOG("Failed to remove fd: %d from fd group(%p): %s\n",

			    ehdlr->fd, fgrp, strerror(errno));

		return;

	}

spdk_fd_group_destroy(struct spdk_fd_group *fgrp)

{

	if (fgrp == NULL || fgrp->num_fds > 0) {

		SPDK_ERRLOG("Invalid fd_group(%p) to destroy.\n", fgrp);

		if (!fgrp) {

			SPDK_ERRLOG("fd_group doesn't exist.\n");

		} else {

			SPDK_ERRLOG("Cannot delete fd group(%p) as (%d) fds still registered to it.\n",

				    fgrp, fgrp->num_fds);

		}

		assert(0);

		return;

	}

			assert(false);

			return -EINVAL;

		} else {

			SPDK_WARNLOG("Calling spdk_fd_group_wait on a group nested in another group will never find any events\n");

			SPDK_WARNLOG("Calling spdk_fd_group_wait on a group nested in another group will never find any events.\n");

			return 0;

		}

	}

	nfds = epoll_wait(fgrp->epfd, events, totalfds, timeout);

	if (nfds < 0) {

		if (errno != EINTR) {

			SPDK_ERRLOG("fgrp epoll_wait returns with fail. errno is %d\n", errno);

			SPDK_ERRLOG("fd group(%p) epoll_wait failed: %s\n",

				    fgrp, strerror(errno));

		}

		return -errno;