This is an automated email from the ASF dual-hosted git repository.
acanary pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new 654fbe6 Commenting EventIO methods (#6712)
654fbe6 is described below
commit 654fbe6a6794be4ab060666ed909dcbebeee82ec
Author: a-a-ron <acan...@verizonmedia.com>
AuthorDate: Fri May 1 11:12:06 2020 -0500
Commenting EventIO methods (#6712)
* Commenting EventIO methods
---
iocore/net/P_UnixNet.h | 61 ++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 49 insertions(+), 12 deletions(-)
diff --git a/iocore/net/P_UnixNet.h b/iocore/net/P_UnixNet.h
index 800be6b..8399196 100644
--- a/iocore/net/P_UnixNet.h
+++ b/iocore/net/P_UnixNet.h
@@ -79,33 +79,55 @@ class NetEvent;
class UnixUDPConnection;
struct DNSConnection;
struct NetAccept;
+
+/// Unified API for setting and clearing kernel and epoll events.
struct EventIO {
- int fd = -1;
+ int fd = -1; ///< file descriptor, often a system port
#if TS_USE_KQUEUE || TS_USE_EPOLL && !defined(USE_EDGE_TRIGGER) || TS_USE_PORT
- int events = 0;
+ int events = 0; ///< a bit mask of enabled events
#endif
- EventLoop event_loop = nullptr;
- bool syscall = true;
- int type = 0;
+ EventLoop event_loop = nullptr; ///< the assigned event loop
+ bool syscall = true; ///< if false, disable all functionality
(for QUIC)
+ int type = 0; ///< class identifier of union data.
union {
Continuation *c;
NetEvent *ne;
DNSConnection *dnscon;
NetAccept *na;
UnixUDPConnection *uc;
- } data;
+ } data; ///< a kind of continuation
+
int start(EventLoop l, DNSConnection *vc, int events);
int start(EventLoop l, NetAccept *vc, int events);
int start(EventLoop l, NetEvent *ne, int events);
int start(EventLoop l, UnixUDPConnection *vc, int events);
+ /** Setup a continuation to be called when a file descriptor is available
for read or write.
+ @param l the event loop
+ @param fd file descriptor (or port)
+ @param c the continuation to call
+ @param events a mask of flags (for details `man epoll_ctl`)
+ @return int the number of events created, -1 is error
+ */
int start(EventLoop l, int fd, Continuation *c, int events);
- // Change the existing events by adding modify(EVENTIO_READ)
- // or removing modify(-EVENTIO_READ), for level triggered I/O
+
+ /** Alter the events that will trigger the continuation, for level triggered
I/O.
+ @param events add with positive mask(+EVENTIO_READ), or remove with
negative mask (-EVENTIO_READ)
+ @return int the number of events created, -1 is error
+ */
int modify(int events);
- // Refresh the existing events (i.e. KQUEUE EV_CLEAR), for edge triggered I/O
+
+ /** Refresh the existing events (i.e. KQUEUE EV_CLEAR), for edge triggered
I/O
+ @param events mask of events
+ @return int the number of events created, -1 is error
+ */
int refresh(int events);
+
+ /// Remove the kernal or epoll event. Returns 0 on success.
int stop();
+
+ /// Remove the epoll event and close the connection. Returns 0 on success.
int close();
+
EventIO() { data.c = nullptr; }
};
@@ -506,9 +528,15 @@ check_transient_accept_error(int res)
}
}
-//
-// Disable a NetEvent
-//
+/** Disable reading on the NetEvent @a ne.
+ @param nh Nethandler that owns @a ne.
+ @param ne The @c NetEvent to modify.
+
+ - If write is already disable, also disable the inactivity timeout.
+ - clear read enabled flag.
+ - Remove the @c epoll READ flag.
+ - Take @a ne out of the read ready list.
+*/
static inline void
read_disable(NetHandler *nh, NetEvent *ne)
{
@@ -521,6 +549,15 @@ read_disable(NetHandler *nh, NetEvent *ne)
ne->ep.modify(-EVENTIO_READ);
}
+/** Disable writing on the NetEvent @a ne.
+ @param nh Nethandler that owns @a ne.
+ @param ne The @c NetEvent to modify.
+
+ - If read is already disable, also disable the inactivity timeout.
+ - clear write enabled flag.
+ - Remove the @c epoll WRITE flag.
+ - Take @a ne out of the write ready list.
+*/
static inline void
write_disable(NetHandler *nh, NetEvent *ne)
{
