cleanup: add comments on those core code

connection_unix.go

@@ -127,20 +127,24 @@ func (c *conn) write(buf []byte) (err error) {
 	if outFrame, err = c.codec.Encode(c, buf); err != nil {
 		return
 	}
+	// If there is pending data in outbound buffer, the current data ought to be appended to the outbound buffer
+	// for maintaining the sequence of network packets.
 	if !c.outboundBuffer.IsEmpty() {
 		_, _ = c.outboundBuffer.Write(outFrame)
 		return
 	}
 
 	var n int
 	if n, err = unix.Write(c.fd, outFrame); err != nil {
+		// A temporary error occurs, append the data to outbound buffer, writing it back to client in the next round.
 		if err == unix.EAGAIN {
 			_, _ = c.outboundBuffer.Write(outFrame)
 			err = c.loop.poller.ModReadWrite(c.fd)
 			return
 		}
 		return c.loop.loopCloseConn(c, os.NewSyscallError("write", err))
 	}
+	// Fail to send all data back to client, buffer the leftover data for the next round.
 	if n < len(outFrame) {
 		_, _ = c.outboundBuffer.Write(outFrame[n:])
 		err = c.loop.poller.ModReadWrite(c.fd)

eventloop_unix.go

@@ -145,6 +145,9 @@ func (el *eventloop) loopRead(c *conn) error {
 		out, action := el.eventHandler.React(inFrame, c)
 		if out != nil {
 			el.eventHandler.PreWrite()
+			// Encode data and try to write it back to the client, this attempt is based on a fact:
+			// a client socket waits for the response data after sending request data to the server,
+			// which makes the client socket writable.
 			if err = c.write(out); err != nil {
 				return err
 			}
@@ -196,6 +199,8 @@ func (el *eventloop) loopWrite(c *conn) error {
 		c.outboundBuffer.Shift(n)
 	}
 
+	// All data have been drained, it's no need to monitor the writable events,
+	// remove the writable event from poller to help the future event-loops.
 	if c.outboundBuffer.IsEmpty() {
 		_ = el.poller.ModRead(c.fd)
 	}

loop_linux.go

@@ -27,12 +27,19 @@ func (el *eventloop) handleEvent(fd int, ev uint32) error {
 		// Don't change the ordering of processing EPOLLOUT | EPOLLRDHUP / EPOLLIN unless you're 100%
 		// sure what you're doing!
 		// Re-ordering can easily introduce bugs and bad side-effects, as I found out painfully in the past.
+
+		// We should always check for the EPOLLOUT event first, as we must try to send the leftover data back to
+		// client when any error occurs on a connection.
+		//
+		// Either an EPOLLOUT or EPOLLERR event may be fired when a connection is refused.
+		// In either case loopWrite() should take care of it properly:
+		// 1) writing data back,
+		// 2) closing the connection.
 		if ev&netpoll.OutEvents != 0 {
 			if err := el.loopWrite(c); err != nil {
 				return err
 			}
 		}
-
 		if ev&netpoll.InEvents != 0 {
 			return el.loopRead(c)
 		}

reactor_linux.go

@@ -61,12 +61,19 @@ func (svr *server) activateSubReactor(el *eventloop, lockOSThread bool) {
 			// Don't change the ordering of processing EPOLLOUT | EPOLLRDHUP / EPOLLIN unless you're 100%
 			// sure what you're doing!
 			// Re-ordering can easily introduce bugs and bad side-effects, as I found out painfully in the past.
+
+			// We should always check for the EPOLLOUT event first, as we must try to send the leftover data back to
+			// client when any error occurs on a connection.
+			//
+			// Either an EPOLLOUT or EPOLLERR event may be fired when a connection is refused.
+			// In either case loopWrite() should take care of it properly:
+			// 1) writing data back,
+			// 2) closing the connection.
 			if ev&netpoll.OutEvents != 0 {
 				if err := el.loopWrite(c); err != nil {
 					return err
 				}
 			}
-
 			if ev&netpoll.InEvents != 0 {
 				return el.loopRead(c)
 			}