GRPC Core  9.0.0
lb_policy.h
Go to the documentation of this file.
1 /*
2  *
3  * Copyright 2015 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 #ifndef GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_H
20 #define GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_H
21 
23 
24 #include <functional>
25 #include <iterator>
26 
30 #include "src/core/lib/gprpp/map.h"
37 
38 namespace grpc_core {
39 
41 
71 
79 // TODO(roth): Once we move to EventManager-based polling, remove the
80 // interested_parties() hooks from the API.
81 class LoadBalancingPolicy : public InternallyRefCounted<LoadBalancingPolicy> {
82  public:
83  // Represents backend metrics reported by the backend to the client.
96  std::map<StringView, double, StringLess> request_cost;
100  std::map<StringView, double, StringLess> utilization;
101  };
102 
105  class CallState {
106  public:
107  CallState() = default;
108  virtual ~CallState() = default;
109 
114  virtual void* Alloc(size_t size) = 0;
115 
118  virtual const BackendMetricData* GetBackendMetricData() = 0;
119  };
120 
124  public:
125  class iterator
126  : public std::iterator<std::input_iterator_tag,
127  std::pair<StringView, StringView>, // value_type
128  std::ptrdiff_t, // difference_type
129  std::pair<StringView, StringView>*, // pointer
130  std::pair<StringView, StringView>& // reference
131  > {
132  public:
133  iterator(const MetadataInterface* md, intptr_t handle)
134  : md_(md), handle_(handle) {}
136  handle_ = md_->IteratorHandleNext(handle_);
137  return *this;
138  }
139  bool operator==(iterator other) const {
140  return md_ == other.md_ && handle_ == other.handle_;
141  }
142  bool operator!=(iterator other) const { return !(*this == other); }
143  value_type operator*() const { return md_->IteratorHandleGet(handle_); }
144 
145  private:
146  friend class MetadataInterface;
147  const MetadataInterface* md_;
148  intptr_t handle_;
149  };
150 
151  virtual ~MetadataInterface() = default;
152 
158  virtual void Add(StringView key, StringView value) = 0;
159 
161  virtual iterator begin() const = 0;
162  virtual iterator end() const = 0;
163 
166  virtual iterator erase(iterator it) = 0;
167 
168  protected:
169  intptr_t GetIteratorHandle(const iterator& it) const { return it.handle_; }
170 
171  private:
172  friend class iterator;
173 
174  virtual intptr_t IteratorHandleNext(intptr_t handle) const = 0;
175  virtual std::pair<StringView /*key*/, StringView /*value */>
176  IteratorHandleGet(intptr_t handle) const = 0;
177  };
178 
180  struct PickArgs {
189  };
190 
192  struct PickResult {
193  enum ResultType {
208  };
210 
214 
217  // TODO(roth): Replace this with something similar to grpc::Status,
218  // so that we don't expose grpc_error to this API.
220 
229  std::function<void(grpc_error*, MetadataInterface*, CallState*)>
231  };
232 
248  public:
249  SubchannelPicker() = default;
250  virtual ~SubchannelPicker() = default;
251 
252  virtual PickResult Pick(PickArgs args) = 0;
253  };
254 
257  // TODO(juanlishen): Consider adding a mid-layer subclass that helps handle
258  // things like swapping in pending policy when it's ready. Currently, we are
259  // duplicating the logic in many subclasses.
261  public:
262  ChannelControlHelper() = default;
263  virtual ~ChannelControlHelper() = default;
264 
267  const grpc_channel_args& args) = 0;
268 
271  virtual void UpdateState(grpc_connectivity_state state,
272  std::unique_ptr<SubchannelPicker>) = 0;
273 
275  virtual void RequestReresolution() = 0;
276 
279  virtual void AddTraceEvent(TraceSeverity severity, StringView message) = 0;
280  };
281 
285  class Config : public RefCounted<Config> {
286  public:
287  virtual ~Config() = default;
288 
289  // Returns the load balancing policy name
290  virtual const char* name() const = 0;
291  };
292 
295  struct UpdateArgs {
298  const grpc_channel_args* args = nullptr;
299 
300  // TODO(roth): Remove everything below once channel args is
301  // converted to a copyable and movable C++ object.
302  UpdateArgs() = default;
304  UpdateArgs(const UpdateArgs& other);
305  UpdateArgs(UpdateArgs&& other);
306  UpdateArgs& operator=(const UpdateArgs& other);
307  UpdateArgs& operator=(UpdateArgs&& other);
308  };
309 
311  struct Args {
314  // TODO(roth): Once we have a C++-like interface for combiners, this
315  // API should change to take a smart pointer that does pass ownership
316  // of a reference.
317  Combiner* combiner = nullptr;
321  std::unique_ptr<ChannelControlHelper> channel_control_helper;
323  // TODO(roth): Find a better channel args representation for this API.
324  // TODO(roth): Clarify ownership semantics here -- currently, this
325  // does not take ownership of args, which is the opposite of how we
326  // handle them in UpdateArgs.
327  const grpc_channel_args* args = nullptr;
328  };
329 
330  explicit LoadBalancingPolicy(Args args, intptr_t initial_refcount = 1);
331  virtual ~LoadBalancingPolicy();
332 
333  // Not copyable nor movable.
334  LoadBalancingPolicy(const LoadBalancingPolicy&) = delete;
336 
338  virtual const char* name() const = 0;
339 
343  virtual void UpdateLocked(UpdateArgs) = 0; // NOLINT
344 
348  virtual void ExitIdleLocked() {}
349 
351  virtual void ResetBackoffLocked() = 0;
352 
353  grpc_pollset_set* interested_parties() const { return interested_parties_; }
354 
355  // Note: This must be invoked while holding the combiner.
356  void Orphan() override;
357 
358  // A picker that returns PICK_QUEUE for all picks.
359  // Also calls the parent LB policy's ExitIdleLocked() method when the
360  // first pick is seen.
361  class QueuePicker : public SubchannelPicker {
362  public:
364  : parent_(std::move(parent)) {}
365 
366  ~QueuePicker() { parent_.reset(DEBUG_LOCATION, "QueuePicker"); }
367 
368  PickResult Pick(PickArgs args) override;
369 
370  private:
371  static void CallExitIdle(void* arg, grpc_error* error);
372 
374  bool exit_idle_called_ = false;
375  };
376 
377  // A picker that returns PICK_TRANSIENT_FAILURE for all picks.
379  public:
380  explicit TransientFailurePicker(grpc_error* error) : error_(error) {}
382 
383  PickResult Pick(PickArgs args) override;
384 
385  private:
386  grpc_error* error_;
387  };
388 
389  protected:
390  Combiner* combiner() const { return combiner_; }
391 
392  // Note: LB policies MUST NOT call any method on the helper from their
393  // constructor.
395  return channel_control_helper_.get();
396  }
397 
399  virtual void ShutdownLocked() = 0;
400 
401  private:
403  Combiner* combiner_;
405  grpc_pollset_set* interested_parties_;
407  std::unique_ptr<ChannelControlHelper> channel_control_helper_;
408 };
409 
410 } // namespace grpc_core
411 
412 #endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_H */
Interface for configuration data used by an LB policy implementation.
Definition: lb_policy.h:285
std::map< StringView, double, StringLess > utilization
Application-specific resource utilization metrics.
Definition: lb_policy.h:100
Data passed to the UpdateLocked() method when new addresses and config are available.
Definition: lb_policy.h:295
Interface for accessing metadata.
Definition: lb_policy.h:123
iterator(const MetadataInterface *md, intptr_t handle)
Definition: lb_policy.h:133
CallState * call_state
An interface for accessing call state.
Definition: lb_policy.h:188
Definition: string_view.h:69
RefCountedPtr< Config > config
Definition: lb_policy.h:297
UpdateArgs & operator=(const UpdateArgs &other)
Definition: lb_policy.cc:68
An array of arguments that can be passed around.
Definition: grpc_types.h:132
virtual const BackendMetricData * GetBackendMetricData()=0
Returns the backend metric data returned by the server for the call, or null if no backend metric dat...
The result of picking a subchannel for a call.
Definition: lb_policy.h:192
virtual void UpdateState(grpc_connectivity_state state, std::unique_ptr< SubchannelPicker >)=0
Sets the connectivity state and returns a new picker to be used by the client channel.
virtual iterator begin() const =0
Iteration interface.
LoadBalancingPolicy(Args args, intptr_t initial_refcount=1)
Definition: lb_policy.cc:34
value_type operator*() const
Definition: lb_policy.h:143
TraceSeverity
Adds a trace message associated with the channel.
Definition: lb_policy.h:278
Interface for load balancing policies.
Definition: lb_policy.h:81
Definition: error_internal.h:39
grpc_connectivity_state
Connectivity state of a channel.
Definition: connectivity_state.h:27
virtual void * Alloc(size_t size)=0
Allocates memory associated with the call, which will be automatically freed when the call is complet...
std::unique_ptr< ChannelControlHelper > channel_control_helper
Channel control helper.
Definition: lb_policy.h:321
virtual void UpdateLocked(UpdateArgs)=0
Updates the policy with new data from the resolver.
#define DEBUG_LOCATION
Definition: debug_location.h:41
~TransientFailurePicker() override
Definition: lb_policy.h:381
const grpc_channel_args * args
Definition: lb_policy.h:298
iterator & operator++()
Definition: lb_policy.h:135
bool operator!=(iterator other) const
Definition: lb_policy.h:142
Definition: orphanable.h:77
double cpu_utilization
CPU utilization expressed as a fraction of available CPU resources.
Definition: lb_policy.h:86
Round Robin Policy.
Definition: backend_metric.cc:24
void grpc_channel_args_destroy(grpc_channel_args *a)
Destroy arguments created by grpc_channel_args_copy.
Definition: channel_args.cc:197
const grpc_channel_args * args
Channel args.
Definition: lb_policy.h:327
A subchannel picker is the object used to pick the subchannel to use for a given call.
Definition: lb_policy.h:247
virtual void ExitIdleLocked()
Tries to enter a READY connectivity state.
Definition: lb_policy.h:348
virtual const char * name() const =0
Definition: trace.h:61
Interface for accessing per-call state.
Definition: lb_policy.h:105
std::map< StringView, double, StringLess > request_cost
Application-specific requests cost metrics.
Definition: lb_policy.h:96
PickResult Pick(PickArgs args) override
Definition: lb_policy.cc:129
Definition: combiner.h:33
DebugOnlyTraceFlag grpc_trace_lb_policy_refcount(false, "lb_policy_refcount")
Definition: lb_policy.h:40
QueuePicker(RefCountedPtr< LoadBalancingPolicy > parent)
Definition: lb_policy.h:363
virtual void AddTraceEvent(TraceSeverity severity, StringView message)=0
virtual void ShutdownLocked()=0
Shuts down the policy.
double mem_utilization
Memory utilization expressed as a fraction of available memory resources.
Definition: lb_policy.h:89
TransientFailurePicker(grpc_error *error)
Definition: lb_policy.h:380
ResultType type
Definition: lb_policy.h:209
Definition: ref_counted_ptr.h:35
uint64_t requests_per_second
Total requests per second being served by the backend.
Definition: lb_policy.h:92
virtual void ResetBackoffLocked()=0
Resets connection backoff.
grpc_pollset_set * interested_parties() const
Definition: lb_policy.h:353
std::function< void(grpc_error *, MetadataInterface *, CallState *)> recv_trailing_metadata_ready
Used only if type is PICK_COMPLETE.
Definition: lb_policy.h:230
PickResult Pick(PickArgs args) override
Definition: lb_policy.cc:92
Pick complete.
Definition: lb_policy.h:197
struct grpc_pollset_set grpc_pollset_set
Definition: pollset_set.h:31
virtual void Add(StringView key, StringView value)=0
Adds a key/value pair.
virtual void RequestReresolution()=0
Requests that the resolver re-resolve.
Pick cannot be completed until something changes on the control plane.
Definition: lb_policy.h:201
Args used to instantiate an LB policy.
Definition: lb_policy.h:311
Combiner * combiner
The combiner under which all LB policy calls will be run.
Definition: lb_policy.h:317
Arguments used when picking a subchannel for a call.
Definition: lb_policy.h:180
A proxy object implemented by the client channel and used by the LB policy to communicate with the ch...
Definition: lb_policy.h:260
#define GRPC_ERROR_NONE
The following "special" errors can be propagated without allocating memory.
Definition: error.h:125
RefCountedPtr< SubchannelInterface > subchannel
Used only if type is PICK_COMPLETE.
Definition: lb_policy.h:213
Definition: ref_counted.h:248
ServerAddressList addresses
Definition: lb_policy.h:296
bool operator==(iterator other) const
Definition: lb_policy.h:139
virtual RefCountedPtr< SubchannelInterface > CreateSubchannel(const grpc_channel_args &args)=0
Creates a new subchannel with the specified channel args.
virtual ~LoadBalancingPolicy()
Definition: lb_policy.cc:40
virtual PickResult Pick(PickArgs args)=0
#define GRPC_ERROR_UNREF(err)
Definition: error.h:186
virtual const char * name() const =0
Returns the name of the LB policy.
intptr_t GetIteratorHandle(const iterator &it) const
Definition: lb_policy.h:169
void Orphan() override
Definition: lb_policy.cc:45
~QueuePicker()
Definition: lb_policy.h:366
Combiner * combiner() const
Definition: lb_policy.h:390
MetadataInterface * initial_metadata
Initial metadata associated with the picking call.
Definition: lb_policy.h:185
Pick failed.
Definition: lb_policy.h:207
virtual iterator erase(iterator it)=0
Removes the element pointed to by it.
grpc_error * error
Used only if type is PICK_FAILED.
Definition: lb_policy.h:219
ChannelControlHelper * channel_control_helper() const
Definition: lb_policy.h:394
LoadBalancingPolicy & operator=(const LoadBalancingPolicy &)=delete
~UpdateArgs()
Definition: lb_policy.h:303
ResultType
Definition: lb_policy.h:193