From 630f0be2182dba963e8f8c3363b14027768d4f90 Mon Sep 17 00:00:00 2001 From: Easwar Swaminathan Date: Mon, 14 Oct 2019 20:16:15 +0000 Subject: [PATCH 1/2] Add more details in ClientConn GoDoc. The newly added lines are mostly stolen from existing Java and C-core documentation. --- clientconn.go | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/clientconn.go b/clientconn.go index c41e7825c68..6156003e7c4 100644 --- a/clientconn.go +++ b/clientconn.go @@ -442,7 +442,19 @@ func (csm *connectivityStateManager) getNotifyChan() <-chan struct{} { return csm.notifyChan } -// ClientConn represents a client connection to an RPC server. +// ClientConn represents a virtual connection to a conceptual endpoint, to +// perform RPCs. +// +// A ClientConn is free to have zero or more actual connections to the endpoint +// based on configuration, load, etc. It is also free to determine which actual +// endpoints to use and may change it every RPC, permitting client-side load +// balancing. +// +// A ClientConn encapsulates a range of functionality including name +// resolution, TCP connection establishment (with retries and backoff) and TLS +// handshakes. It also handles errors on established connections and +// reconnects, or in the case of HTTP/2 GO_AWAY, re-resolves the name and +// reconnects. type ClientConn struct { ctx context.Context cancel context.CancelFunc From 7651f4c869ef107a9aafaf2737abc538affb7e2b Mon Sep 17 00:00:00 2001 From: Easwar Swaminathan Date: Mon, 14 Oct 2019 23:23:08 +0000 Subject: [PATCH 2/2] Review comments. --- clientconn.go | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/clientconn.go b/clientconn.go index 6156003e7c4..463c7768e3b 100644 --- a/clientconn.go +++ b/clientconn.go @@ -452,9 +452,8 @@ func (csm *connectivityStateManager) getNotifyChan() <-chan struct{} { // // A ClientConn encapsulates a range of functionality including name // resolution, TCP connection establishment (with retries and backoff) and TLS -// handshakes. It also handles errors on established connections and -// reconnects, or in the case of HTTP/2 GO_AWAY, re-resolves the name and -// reconnects. +// handshakes. It also handles errors on established connections by +// re-resolving the name and reconnecting. type ClientConn struct { ctx context.Context cancel context.CancelFunc