Mod: add remark for tcp reading

conn.go

@@ -235,6 +235,7 @@ func (t *gettyTCPConn) read(p []byte) (int, error) {
 		length      int
 	)
 
+	// set read timeout deadline
 	if t.compress == CompressNone && t.rTimeout > 0 {
 		// Optimization: update read deadline only if more than 25%
 		// of the last read deadline exceeded.
@@ -242,6 +243,7 @@ func (t *gettyTCPConn) read(p []byte) (int, error) {
 		currentTime = time.Now()
 		if currentTime.Sub(t.rLastDeadline) > (t.rTimeout >> 2) {
 			if err = t.conn.SetReadDeadline(currentTime.Add(t.rTimeout)); err != nil {
+				// just a timeout error
 				return 0, perrors.WithStack(err)
 			}
 			t.rLastDeadline = currentTime

getty.go

@@ -24,9 +24,17 @@ type NewSessionCallback func(Session) error
 
 // Reader is used to unmarshal a complete pkg from buffer
 type Reader interface {
-	// Parse tcp/udp/websocket pkg from buffer and if possible return a complete pkg
-	// If length of buf is not long enough, u should return {nil,0, nil}
-	// The second return value is the length of the pkg.
+	// Parse tcp/udp/websocket pkg from buffer and if possible return a complete pkg.
+	// When receiving a tcp network streaming segment, there are 4 cases as following:
+	// case 1: a error found in the streaming segment;
+	// case 2: can not unmarshal a pkg from the streaming segment;
+	// case 3: just unmarshal a pkg from the streaming segment;
+	// case 4: unmarshal more than one pkg from the streaming segment;
+	//
+	// The return value is (nil, 0, error) as case 1.
+	// The return value is (nil, 0, nil) as case 2.
+	// The return value is (pkg, pkgLen, nil) as case 3.
+	// The handleTcpPackage may invoke func Read many times as case 4.
 	Read(Session, []byte) (interface{}, int, error)
 }
 

session.go

@@ -623,6 +623,7 @@ func (s *session) handleTCPPackage() error {
 			if err == nil && s.maxMsgLen > 0 && pkgLen > int(s.maxMsgLen) {
 				err = perrors.Errorf("pkgLen %d > session max message len %d", pkgLen, s.maxMsgLen)
 			}
+			// handle case 1
 			if err != nil {
 				log.Warnf("%s, [session.handleTCPPackage] = len{%d}, error:%+v",
 					s.sessionToken(), pkgLen, err)
@@ -631,12 +632,15 @@ func (s *session) handleTCPPackage() error {
 				exit = true
 				break
 			}
+			// handle case 2
 			if pkg == nil {
 				break
 			}
+			// handle case 3
 			s.UpdateActive()
 			s.rQ <- pkg
 			pktBuf.Next(pkgLen)
+			// continue to handle case 4
 		}
 		if exit {
 			break