From 630f0be2182dba963e8f8c3363b14027768d4f90 Mon Sep 17 00:00:00 2001 From: Easwar Swaminathan Date: Mon, 14 Oct 2019 20:16:15 +0000 Subject: [PATCH] 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