UDT Reference: Functions

epoll

The epoll method can be used to effectively poll the IO events for a large number of sockets. It includes the following APIs.

#ifndef WIN32
   typedef int SYSSOCKET;
#else
   typedef SOCKET SYSSOCKET;
#endif
int epoll_create();
int epoll_add_usock(const int eid, const UDTSOCKET usock, const int* events = NULL);
int epoll_add_ssock(const int eid, const UDTSOCKET ssock, const int* events = NULL);
int epoll_remove_usock(const int eid, const UDTSOCKET usock);
int epoll_remove_ssock(const int eid, const UDTSOCKET ssock);
int epoll_wait(const int eid, std::set<UDTSOCKET>* readfds, std::set<UDTSOCKET>* writefds, int64_t msTimeOut, std::set<SYSSOCKET>* lrfds = NULL, std::set<SYSSOCKET>* wrfds = NULL);
int epoll_release(const int eid);
Parameters
eid
[in] The epoll ID allocated by epoll_create and used by subsequent epoll functions.
usock
[in] the UDT socket ID to be added to or removed from the epoll.
ssock
[in] the system socket ID to be added to or removed from the epoll.
events
[in] events to be watched.
readfds
[out] Optional pointer to a set of UDT sockets that are ready to read.
writefds
[out] Optional pointer to a set of UDT sockets that are ready to write, or are broken.
msTimeOut
[in] The time that this epoll should wait for the status change in the input groups, in milliseconds.
lrfds
[out] Optional pointer to a set of system sockets that are ready to read.
lwfds
[out] Optional pointer to a set of system sockets that are ready to write, or are broken.
Return Value

If successful, epoll_create returns a new epoll ID, epoll_wait returns the total number of UDT sockets and system sockets ready for IO, and the other three functions return 0. On error, all functions return negative error values. The error can be one of the following.

Error Name Error Code Comment
EINVPARAM 5003 Invalid parameters.
EINVSOCK 5004 Invalid socket.
EINVPOLLID 5013 EPoll ID is invalid.
Description

The epoll functions provides a highly scalable and efficient way to wait for UDT sockets IO events. It should be used instead of select and selectEx when the application needs to wait for a very large number of sockets. In addition, epoll also offers to wait on system sockets at the same time, which can be convenient when an application uses both UDT and TCP/UDP.

Applications should use epoll_create to create an epoll ID and use epoll_add_usock/ssock and epoll_remove_usock/ssock to add/remove sockets. If a socket is already in the epoll set, it will be ignored if being added again. Adding invalid or closed sockets will cause error. However, they will simply be ignored without any error returned when being removed.

Multiple epoll entities can be created and there is no upper limits as long as system resource allows. There is also no hard limit on the number of UDT sockets. The number system descriptors supported by UDT::epoll are platform dependent.

For system sockets on Linux, developers may choose to watch individual events from EPOLLIN (read), EPOLLOUT (write), and EPOLLERR (exceptions). When using epoll_remove_ssock, if the socket is waiting on multiple events, only those specified in events are removed. The events can be a combination (with "|" operation) of any of the following values.

enum EPOLLOpt
{
    UDT_EPOLL_IN = 0x1,
    UDT_EPOLL_OUT = 0x4,
    UDT_EPOLL_ERR = 0x8
};

For all other situations, the parameter events is ignored and all events will be watched.

Note that exceptions are categorized as write events, so when the application choose to write to this socket, it will detect the exception.

Finally, for epoll_wait, negative timeout value will make the function to wait until an event happens. If the timeout value is 0, then the function returns immediately with any sockets associated an IO event. If timeout occurs before any event happens, the function returns 0.

See Also

select, selectEx