From cf6d4d5ab7af69753510e9ae717025aa31deb359 Mon Sep 17 00:00:00 2001
From: Easwar Swaminathan <easwars@google.com>
Date: Wed, 9 Mar 2022 07:51:20 -0800
Subject: [PATCH] grpc: document ClientConn fields (#5227)

---
 clientconn.go | 55 +++++++++++++++++++++++++++++----------------------
 1 file changed, 31 insertions(+), 24 deletions(-)

diff --git a/clientconn.go b/clientconn.go
index 10f67edecde..c084a9013e4 100644
--- a/clientconn.go
+++ b/clientconn.go
@@ -461,34 +461,41 @@ var _ ClientConnInterface = (*ClientConn)(nil)
 // handshakes. It also handles errors on established connections by
 // re-resolving the name and reconnecting.
 type ClientConn struct {
-	ctx    context.Context
-	cancel context.CancelFunc
-
-	target       string
-	parsedTarget resolver.Target
-	authority    string
-	dopts        dialOptions
-	csMgr        *connectivityStateManager
-
-	balancerBuildOpts balancer.BuildOptions
-	blockingpicker    *pickerWrapper
-
+	ctx    context.Context    // Initialized using the background context at dial time.
+	cancel context.CancelFunc // Cancelled on close.
+
+	// The following are initialized at dial time, and are read-only after that.
+	target            string                // User's dial target.
+	parsedTarget      resolver.Target       // See parseTargetAndFindResolver().
+	authority         string                // See determineAuthority().
+	dopts             dialOptions           // Default and user specified dial options.
+	balancerBuildOpts balancer.BuildOptions // TODO: delete once we move to the gracefulswitch balancer.
+	channelzID        *channelz.Identifier  // Channelz identifier for the channel.
+
+	// The following provide their own synchronization, and therefore don't
+	// require cc.mu to be held to access them.
+	csMgr              *connectivityStateManager
+	blockingpicker     *pickerWrapper
 	safeConfigSelector iresolver.SafeConfigSelector
+	czData             *channelzData
+	retryThrottler     atomic.Value // Updated from service config.
 
-	mu              sync.RWMutex
-	resolverWrapper *ccResolverWrapper
-	sc              *ServiceConfig
-	conns           map[*addrConn]struct{}
-	// Keepalive parameter can be updated if a GoAway is received.
-	mkp             keepalive.ClientParameters
-	curBalancerName string
-	balancerWrapper *ccBalancerWrapper
-	retryThrottler  atomic.Value
-
+	// firstResolveEvent is used to track whether the name resolver sent us at
+	// least one update. RPCs block on this event.
 	firstResolveEvent *grpcsync.Event
+	// TODO: Add a goodResolveEvent to track whether the name resolver sent us a
+	// good update. This will be used to determine if a balancer is configured on
+	// the channel instead of checking for `cc.balancerWrapper != nil`.
 
-	channelzID *channelz.Identifier
-	czData     *channelzData
+	// mu protects the following fields.
+	// TODO: split mu so the same mutex isn't used for everything.
+	mu              sync.RWMutex
+	resolverWrapper *ccResolverWrapper         // Initialized in Dial; cleared in Close.
+	sc              *ServiceConfig             // Latest service config received from the resolver.
+	conns           map[*addrConn]struct{}     // Set to nil on close.
+	mkp             keepalive.ClientParameters // May be updated upon receipt of a GoAway.
+	curBalancerName string                     // TODO: delete as part of https://github.com/grpc/grpc-go/issues/5229.
+	balancerWrapper *ccBalancerWrapper         // TODO: Use gracefulswitch balancer to be able to initialize this once and never rewrite.
 
 	lceMu               sync.Mutex // protects lastConnectionError
 	lastConnectionError error