package grpc

Import Path
	google.golang.org/api/transport/grpc (on go.dev)

Dependency Relation
	imports 16 packages, and imported by 8 packages

Involved Source Files

	   d➜ dial.go
		Package grpc supports network connections to GRPC servers.
		This package is not intended for use by end developers. Use the
		google.golang.org/api/option package to configure API clients.

	      pool.go
Package-Level Type Names (total 6, in which 1 are exported)

	/* sort exporteds by: alphabet | popularity */
	 type ConnPool = internal.ConnPool (interface)
		ConnPool is a pool of grpc.ClientConns.


	/* 5 unexporteds ... *//* 5 unexporteds: */
	 type connPoolOption (struct)

		Fields (only one, which is exported)
			ConnPool ConnPool
		Methods (total 6, all are exported)
			( T) Apply(s *internal.DialSettings)
			( T) Close() error
				Close closes every ClientConn in the pool.

				The error returned by Close may be a single error or multiple errors.

			( T) Conn() *grpc.ClientConn
				Conn returns a ClientConn from the pool.

				Conns aren't returned to the pool.

			( T) Invoke(ctx context.Context, method string, args interface{}, reply interface{}, opts ...grpc.CallOption) error
				Invoke performs a unary RPC and returns after the response is received
				into reply.

			( T) NewStream(ctx context.Context, desc *grpc.StreamDesc, method string, opts ...grpc.CallOption) (grpc.ClientStream, error)
				NewStream begins a streaming RPC.

			( T) Num() int
				Num returns the number of connections in the pool.

				It will always return the same value.

		Implements (at least 4, all are exported)
			 T : google.golang.org/api/internal.ConnPool
			 T : google.golang.org/api/option.ClientOption
			 T : google.golang.org/grpc.ClientConnInterface
			 T : io.Closer

	 type grpcTokenSource (struct)
		grpcTokenSource supplies PerRPCCredentials from an oauth.TokenSource.

		Fields (total 3, in which 1 are exported)
			TokenSource oauth.TokenSource
			/* 2 unexporteds ... *//* 2 unexporteds: */
			quotaProject string
				Additional metadata attached as headers.

			requestReason string
		Methods (total 3, all are exported)
			( T) GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error)
				GetRequestMetadata gets the request metadata as a map from a grpcTokenSource.

			( T) RequireTransportSecurity() bool
				RequireTransportSecurity indicates whether the credentials requires transport security.

			( T) Token() (*oauth2.Token, error)
				Token returns a token or an error.
				Token must be safe for concurrent use by multiple goroutines.
				The returned Token must not be modified.

		Implements (at least 2, both are exported)
			 T : google.golang.org/grpc/credentials.PerRPCCredentials
			 T : golang.org/x/oauth2.TokenSource

	 type multiError ([]T)
		multiError represents errors from multiple conns in the group.

		TODO: figure out how and whether this is useful to export. End users should
		not be depending on the transport/grpc package directly, so there might need
		to be some service-specific multi-error type.

		Methods (only one, which is exported)
			( T) Error() string
		Implements (at least one exported)
			 T : error

	 type roundRobinConnPool (struct)

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			conns []*grpc.ClientConn
			idx uint32
				// access via sync/atomic

		Methods (total 5, all are exported)
			(*T) Close() error
			(*T) Conn() *grpc.ClientConn
			(*T) Invoke(ctx context.Context, method string, args interface{}, reply interface{}, opts ...grpc.CallOption) error
			(*T) NewStream(ctx context.Context, desc *grpc.StreamDesc, method string, opts ...grpc.CallOption) (grpc.ClientStream, error)
			(*T) Num() int
		Implements (at least 3, all are exported)
			*T : google.golang.org/api/internal.ConnPool
			*T : google.golang.org/grpc.ClientConnInterface
			*T : io.Closer

	 type singleConnPool (struct)
		singleConnPool is a special case for a single connection.

		Fields (total 23, in which 1 are exported)
			ClientConn *grpc.ClientConn
			/* 22 unexporteds ... *//* 22 unexporteds: */
			ClientConn.authority string
			ClientConn.balancerBuildOpts balancer.BuildOptions
			ClientConn.balancerWrapper *grpc.ccBalancerWrapper
			ClientConn.blockingpicker *grpc.pickerWrapper
			ClientConn.cancel context.CancelFunc
			ClientConn.channelzID int64
				// channelz unique identification number

			ClientConn.conns map[*grpc.addrConn]struct{}
			ClientConn.csMgr *grpc.connectivityStateManager
			ClientConn.ctx context.Context
			ClientConn.curBalancerName string
			ClientConn.czData *grpc.channelzData
			ClientConn.dopts grpc.dialOptions
			ClientConn.firstResolveEvent *grpcsync.Event
			ClientConn.lastConnectionError error
			ClientConn.lceMu sync.Mutex
				// protects lastConnectionError

			ClientConn.mkp keepalive.ClientParameters
				Keepalive parameter can be updated if a GoAway is received.

			ClientConn.mu sync.RWMutex
			ClientConn.parsedTarget resolver.Target
			ClientConn.resolverWrapper *grpc.ccResolverWrapper
			ClientConn.retryThrottler atomic.Value
			ClientConn.sc *grpc.ServiceConfig
			ClientConn.target string
		Methods (total 29, in which 10 are exported)
			( T) Close() error
				Close tears down the ClientConn and all underlying connections.

			(*T) Conn() *grpc.ClientConn
			( T) GetMethodConfig(method string) grpc.MethodConfig
				GetMethodConfig gets the method config of the input method.
				If there's an exact match for input method (i.e. /service/method), we return
				the corresponding MethodConfig.
				If there isn't an exact match for the input method, we look for the service's default
				config under the service (i.e /service/) and then for the default for all services (empty string).

				If there is a default MethodConfig for the service, we return it.
				Otherwise, we return an empty MethodConfig.

			( T) GetState() connectivity.State
				GetState returns the connectivity.State of ClientConn.
				This is an EXPERIMENTAL API.

			( T) Invoke(ctx context.Context, method string, args, reply interface{}, opts ...grpc.CallOption) error
				Invoke sends the RPC request on the wire and returns after response is
				received.  This is typically called by generated code.

				All errors returned by Invoke are compatible with the status package.

			( T) NewStream(ctx context.Context, desc *grpc.StreamDesc, method string, opts ...grpc.CallOption) (grpc.ClientStream, error)
				NewStream creates a new Stream for the client side. This is typically
				called by generated code. ctx is used for the lifetime of the stream.

				To ensure resources are not leaked due to the stream returned, one of the following
				actions must be performed:

				     1. Call Close on the ClientConn.
				     2. Cancel the context provided.
				     3. Call RecvMsg until a non-nil error is returned. A protobuf-generated
				        client-streaming RPC, for instance, might use the helper function
				        CloseAndRecv (note that CloseSend does not Recv, therefore is not
				        guaranteed to release all resources).
				     4. Receive a non-nil, non-io.EOF error from Header or SendMsg.

				If none of the above happen, a goroutine and a context will be leaked, and grpc
				will not call the optionally-configured stats handler with a stats.End message.

			(*T) Num() int
			( T) ResetConnectBackoff()
				ResetConnectBackoff wakes up all subchannels in transient failure and causes
				them to attempt another connection immediately.  It also resets the backoff
				times used for subsequent attempts regardless of the current state.

				In general, this function should not be used.  Typical service or network
				outages result in a reasonable client reconnection strategy by default.
				However, if a previously unavailable network becomes available, this may be
				used to trigger an immediate reconnect.

				This API is EXPERIMENTAL.

			( T) Target() string
				Target returns the target string of the ClientConn.
				This is an EXPERIMENTAL API.

			( T) WaitForStateChange(ctx context.Context, sourceState connectivity.State) bool
				WaitForStateChange waits until the connectivity.State of ClientConn changes from sourceState or
				ctx expires. A true value is returned in former case and false in latter.
				This is an EXPERIMENTAL API.

			/* 19 unexporteds ... *//* 19 unexporteds: */
			( T) applyServiceConfigAndBalancer(sc *grpc.ServiceConfig, addrs []resolver.Address)
			( T) channelzMetric() *channelz.ChannelInternalMetric
			( T) connectionError() error
			( T) getResolver(scheme string) resolver.Builder
			( T) getTransport(ctx context.Context, failfast bool, method string) (transport.ClientTransport, func(balancer.DoneInfo), error)
			( T) handleSubConnStateChange(sc balancer.SubConn, s connectivity.State, err error)
			( T) healthCheckConfig() *grpc.healthCheckConfig
			( T) incrCallsFailed()
			( T) incrCallsStarted()
			( T) incrCallsSucceeded()
			( T) maybeApplyDefaultServiceConfig(addrs []resolver.Address)
			( T) newAddrConn(addrs []resolver.Address, opts balancer.NewSubConnOptions) (*grpc.addrConn, error)
				newAddrConn creates an addrConn for addrs and adds it to cc.conns.

				Caller needs to make sure len(addrs) > 0.

			( T) removeAddrConn(ac *grpc.addrConn, err error)
				removeAddrConn removes the addrConn in the subConn from clientConn.
				It also tears down the ac with the given error.

			( T) resolveNow(o resolver.ResolveNowOptions)
			( T) scWatcher()
			( T) switchBalancer(name string)
				switchBalancer starts the switching from current balancer to the balancer
				with the given name.

				It will NOT send the current address list to the new balancer. If needed,
				caller of this function should send address list to the new balancer after
				this function returns.

				Caller must hold cc.mu.

			( T) updateConnectionError(err error)
			( T) updateResolverState(s resolver.State, err error) error
			( T) waitForResolvedAddrs(ctx context.Context) error
				waitForResolvedAddrs blocks until the resolver has provided addresses or the
				context expires.  Returns nil unless the context expires first; otherwise
				returns a status error based on the context.

		Implements (at least 3, all are exported)
			*T : google.golang.org/api/internal.ConnPool
			 T : google.golang.org/grpc.ClientConnInterface
			 T : io.Closer


Package-Level Functions (total 10, in which 4 are exported)

	 func Dial(ctx context.Context, opts ...option.ClientOption) (*grpc.ClientConn, error)
		Dial returns a GRPC connection for use communicating with a Google cloud
		service, configured with the given ClientOptions.

	 func DialInsecure(ctx context.Context, opts ...option.ClientOption) (*grpc.ClientConn, error)
		DialInsecure returns an insecure GRPC connection for use communicating
		with fake or mock Google cloud service implementations, such as emulators.
		The connection is configured with the given ClientOptions.

	 func DialPool(ctx context.Context, opts ...option.ClientOption) (ConnPool, error)
		DialPool returns a pool of GRPC connections for the given service.
		This differs from the connection pooling implementation used by Dial, which uses a custom GRPC load balancer.
		DialPool should be used instead of Dial when a pool is used by default or a different custom GRPC load balancer is needed.
		The context and options are shared between each Conn in the pool.
		The pool size is configured using the WithGRPCConnectionPool option.

		This API is subject to change as we further refine requirements. It will go away if gRPC stubs accept an interface instead of the concrete ClientConn type. See https://github.com/grpc/grpc-go/issues/1287.

	 func WithConnPool(p ConnPool) option.ClientOption
		WithConnPool returns a ClientOption that specifies the ConnPool
		connection to use as the basis of communications.

		This is only to be used by Google client libraries internally, for example
		when creating a longrunning API client that shares the same connection pool
		as a service client.

	/* 6 unexporteds ... *//* 6 unexporteds: */
	 func addOCStatsHandler(opts []grpc.DialOption, settings *internal.DialSettings) []grpc.DialOption
	 func dial(ctx context.Context, insecure bool, o *internal.DialSettings) (*grpc.ClientConn, error)
	 func generateDefaultMtlsEndpoint(defaultEndpoint string) string
		generateDefaultMtlsEndpoint attempts to derive the mTLS version of the
		defaultEndpoint via regex, and returns defaultEndpoint if unsuccessful.

		We need to applying the following 2 transformations:
		1. pubsub.googleapis.com to pubsub.mtls.googleapis.com
		2. pubsub.sandbox.googleapis.com to pubsub.mtls.sandbox.googleapis.com

		TODO(cbro): In the future, the mTLS endpoint will be read from Service Config
		and passed in as defaultMtlsEndpoint instead of generated from defaultEndpoint,
		and this function will be removed.

	 func isDirectPathEnabled(endpoint string) bool
	 func isTokenSourceDirectPathCompatible(ts oauth2.TokenSource) bool
	 func processAndValidateOpts(opts []option.ClientOption) (*internal.DialSettings, error)
Package-Level Variables (total 2, neither is exported)

	/* 2 unexporteds ... *//* 2 unexporteds: */
	  var appengineDialerHook (context.Context) grpc.DialOption
		Set at init time by dial_appengine.go. If nil, we're not on App Engine.

	  var timeoutDialerOption grpc.DialOption
		Set at init time by dial_socketopt.go. If nil, socketopt is not supported.

The pages are generated with Golds v0.3.2-preview. (GOOS=darwin GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.