google.golang.org/grpc@v1.62.1/resolver/manual/manual.go (about)

     1  /*
     2   *
     3   * Copyright 2017 gRPC authors.
     4   *
     5   * Licensed under the Apache License, Version 2.0 (the "License");
     6   * you may not use this file except in compliance with the License.
     7   * You may obtain a copy of the License at
     8   *
     9   *     http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   *
    17   */
    18  
    19  // Package manual defines a resolver that can be used to manually send resolved
    20  // addresses to ClientConn.
    21  package manual
    22  
    23  import (
    24  	"sync"
    25  
    26  	"google.golang.org/grpc/resolver"
    27  )
    28  
    29  // NewBuilderWithScheme creates a new manual resolver builder with the given
    30  // scheme. Every instance of the manual resolver may only ever be used with a
    31  // single grpc.ClientConn. Otherwise, bad things will happen.
    32  func NewBuilderWithScheme(scheme string) *Resolver {
    33  	return &Resolver{
    34  		BuildCallback:       func(resolver.Target, resolver.ClientConn, resolver.BuildOptions) {},
    35  		UpdateStateCallback: func(error) {},
    36  		ResolveNowCallback:  func(resolver.ResolveNowOptions) {},
    37  		CloseCallback:       func() {},
    38  		scheme:              scheme,
    39  	}
    40  }
    41  
    42  // Resolver is also a resolver builder.
    43  // It's build() function always returns itself.
    44  type Resolver struct {
    45  	// BuildCallback is called when the Build method is called.  Must not be
    46  	// nil.  Must not be changed after the resolver may be built.
    47  	BuildCallback func(resolver.Target, resolver.ClientConn, resolver.BuildOptions)
    48  	// UpdateStateCallback is called when the UpdateState method is called on
    49  	// the resolver.  The value passed as argument to this callback is the value
    50  	// returned by the resolver.ClientConn.  Must not be nil.  Must not be
    51  	// changed after the resolver may be built.
    52  	UpdateStateCallback func(err error)
    53  	// ResolveNowCallback is called when the ResolveNow method is called on the
    54  	// resolver.  Must not be nil.  Must not be changed after the resolver may
    55  	// be built.
    56  	ResolveNowCallback func(resolver.ResolveNowOptions)
    57  	// CloseCallback is called when the Close method is called.  Must not be
    58  	// nil.  Must not be changed after the resolver may be built.
    59  	CloseCallback func()
    60  	scheme        string
    61  
    62  	// Fields actually belong to the resolver.
    63  	// Guards access to below fields.
    64  	mu sync.Mutex
    65  	CC resolver.ClientConn
    66  	// Storing the most recent state update makes this resolver resilient to
    67  	// restarts, which is possible with channel idleness.
    68  	lastSeenState *resolver.State
    69  }
    70  
    71  // InitialState adds initial state to the resolver so that UpdateState doesn't
    72  // need to be explicitly called after Dial.
    73  func (r *Resolver) InitialState(s resolver.State) {
    74  	r.lastSeenState = &s
    75  }
    76  
    77  // Build returns itself for Resolver, because it's both a builder and a resolver.
    78  func (r *Resolver) Build(target resolver.Target, cc resolver.ClientConn, opts resolver.BuildOptions) (resolver.Resolver, error) {
    79  	r.BuildCallback(target, cc, opts)
    80  	r.mu.Lock()
    81  	defer r.mu.Unlock()
    82  	r.CC = cc
    83  	if r.lastSeenState != nil {
    84  		err := r.CC.UpdateState(*r.lastSeenState)
    85  		go r.UpdateStateCallback(err)
    86  	}
    87  	return r, nil
    88  }
    89  
    90  // Scheme returns the manual resolver's scheme.
    91  func (r *Resolver) Scheme() string {
    92  	return r.scheme
    93  }
    94  
    95  // ResolveNow is a noop for Resolver.
    96  func (r *Resolver) ResolveNow(o resolver.ResolveNowOptions) {
    97  	r.ResolveNowCallback(o)
    98  }
    99  
   100  // Close is a noop for Resolver.
   101  func (r *Resolver) Close() {
   102  	r.CloseCallback()
   103  }
   104  
   105  // UpdateState calls CC.UpdateState.
   106  func (r *Resolver) UpdateState(s resolver.State) {
   107  	r.mu.Lock()
   108  	defer r.mu.Unlock()
   109  	var err error
   110  	if r.CC == nil {
   111  		panic("cannot update state as grpc.Dial with resolver has not been called")
   112  	}
   113  	err = r.CC.UpdateState(s)
   114  	r.lastSeenState = &s
   115  	r.UpdateStateCallback(err)
   116  }
   117  
   118  // ReportError calls CC.ReportError.
   119  func (r *Resolver) ReportError(err error) {
   120  	r.mu.Lock()
   121  	defer r.mu.Unlock()
   122  	if r.CC == nil {
   123  		panic("cannot report error as grpc.Dial with resolver has not been called")
   124  	}
   125  	r.CC.ReportError(err)
   126  }