lb_policy.h

Go to the documentation of this file.

/*
 *
 * Copyright 2015 gRPC authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */
 
#ifndef GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_H
#define GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_H
 
#include <grpc/support/port_platform.h>
 
#include <functional>
#include <iterator>
 
#include "src/core/ext/filters/client_channel/server_address.h"
#include "src/core/ext/filters/client_channel/service_config.h"
#include "src/core/ext/filters/client_channel/subchannel_interface.h"
#include "src/core/lib/gprpp/map.h"
#include "src/core/lib/gprpp/orphanable.h"
#include "src/core/lib/gprpp/ref_counted_ptr.h"
#include "src/core/lib/gprpp/string_view.h"
#include "src/core/lib/iomgr/combiner.h"
#include "src/core/lib/iomgr/polling_entity.h"
#include "src/core/lib/transport/connectivity_state.h"
 
namespace grpc_core {
 
extern DebugOnlyTraceFlag grpc_trace_lb_policy_refcount;
 
 
// TODO(roth): Once we move to EventManager-based polling, remove the
// interested_parties() hooks from the API.
class LoadBalancingPolicy : public InternallyRefCounted<LoadBalancingPolicy> {
 public:
  // Represents backend metrics reported by the backend to the client.
  struct BackendMetricData {
    double cpu_utilization;
    double mem_utilization;
    uint64_t requests_per_second;
    std::map<StringView, double, StringLess> request_cost;
    std::map<StringView, double, StringLess> utilization;
  };
 
  class CallState {
   public:
    CallState() = default;
    virtual ~CallState() = default;
 
    virtual void* Alloc(size_t size) = 0;
 
    virtual const BackendMetricData* GetBackendMetricData() = 0;
  };
 
  class MetadataInterface {
   public:
    class iterator
        : public std::iterator<std::input_iterator_tag,
                               std::pair<StringView, StringView>,  // value_type
                               std::ptrdiff_t,  // difference_type
                               std::pair<StringView, StringView>*,  // pointer
                               std::pair<StringView, StringView>&   // reference
                               > {
     public:
      iterator(const MetadataInterface* md, intptr_t handle)
          : md_(md), handle_(handle) {}
      iterator& operator++() {
        handle_ = md_->IteratorHandleNext(handle_);
        return *this;
      }
      bool operator==(iterator other) const {
        return md_ == other.md_ && handle_ == other.handle_;
      }
      bool operator!=(iterator other) const { return !(*this == other); }
      value_type operator*() const { return md_->IteratorHandleGet(handle_); }
 
     private:
      friend class MetadataInterface;
      const MetadataInterface* md_;
      intptr_t handle_;
    };
 
    virtual ~MetadataInterface() = default;
 
    virtual void Add(StringView key, StringView value) = 0;
 
    virtual iterator begin() const = 0;
    virtual iterator end() const = 0;
 
    virtual iterator erase(iterator it) = 0;
 
   protected:
    intptr_t GetIteratorHandle(const iterator& it) const { return it.handle_; }
 
   private:
    friend class iterator;
 
    virtual intptr_t IteratorHandleNext(intptr_t handle) const = 0;
    virtual std::pair<StringView /*key*/, StringView /*value */>
    IteratorHandleGet(intptr_t handle) const = 0;
  };
 
  struct PickArgs {
    MetadataInterface* initial_metadata;
    CallState* call_state;
  };
 
  struct PickResult {
    enum ResultType {
      PICK_COMPLETE,
      PICK_QUEUE,
      PICK_FAILED,
    };
    ResultType type;
 
    RefCountedPtr<SubchannelInterface> subchannel;
 
    // TODO(roth): Replace this with something similar to grpc::Status,
    // so that we don't expose grpc_error to this API.
    grpc_error* error = GRPC_ERROR_NONE;
 
    std::function<void(grpc_error*, MetadataInterface*, CallState*)>
        recv_trailing_metadata_ready;
  };
 
  class SubchannelPicker {
   public:
    SubchannelPicker() = default;
    virtual ~SubchannelPicker() = default;
 
    virtual PickResult Pick(PickArgs args) = 0;
  };
 
  // TODO(juanlishen): Consider adding a mid-layer subclass that helps handle
  // things like swapping in pending policy when it's ready. Currently, we are
  // duplicating the logic in many subclasses.
  class ChannelControlHelper {
   public:
    ChannelControlHelper() = default;
    virtual ~ChannelControlHelper() = default;
 
    virtual RefCountedPtr<SubchannelInterface> CreateSubchannel(
        const grpc_channel_args& args) = 0;
 
    virtual void UpdateState(grpc_connectivity_state state,
                             std::unique_ptr<SubchannelPicker>) = 0;
 
    virtual void RequestReresolution() = 0;
 
    enum TraceSeverity { TRACE_INFO, TRACE_WARNING, TRACE_ERROR };
    virtual void AddTraceEvent(TraceSeverity severity, StringView message) = 0;
  };
 
  class Config : public RefCounted<Config> {
   public:
    virtual ~Config() = default;
 
    // Returns the load balancing policy name
    virtual const char* name() const = 0;
  };
 
  struct UpdateArgs {
    ServerAddressList addresses;
    RefCountedPtr<Config> config;
    const grpc_channel_args* args = nullptr;
 
    // TODO(roth): Remove everything below once channel args is
    // converted to a copyable and movable C++ object.
    UpdateArgs() = default;
    ~UpdateArgs() { grpc_channel_args_destroy(args); }
    UpdateArgs(const UpdateArgs& other);
    UpdateArgs(UpdateArgs&& other);
    UpdateArgs& operator=(const UpdateArgs& other);
    UpdateArgs& operator=(UpdateArgs&& other);
  };
 
  struct Args {
    // TODO(roth): Once we have a C++-like interface for combiners, this
    // API should change to take a smart pointer that does pass ownership
    // of a reference.
    Combiner* combiner = nullptr;
    std::unique_ptr<ChannelControlHelper> channel_control_helper;
    // TODO(roth): Find a better channel args representation for this API.
    // TODO(roth): Clarify ownership semantics here -- currently, this
    // does not take ownership of args, which is the opposite of how we
    // handle them in UpdateArgs.
    const grpc_channel_args* args = nullptr;
  };
 
  explicit LoadBalancingPolicy(Args args, intptr_t initial_refcount = 1);
  virtual ~LoadBalancingPolicy();
 
  // Not copyable nor movable.
  LoadBalancingPolicy(const LoadBalancingPolicy&) = delete;
  LoadBalancingPolicy& operator=(const LoadBalancingPolicy&) = delete;
 
  virtual const char* name() const = 0;
 
  virtual void UpdateLocked(UpdateArgs) = 0;  // NOLINT
 
  virtual void ExitIdleLocked() {}
 
  virtual void ResetBackoffLocked() = 0;
 
  grpc_pollset_set* interested_parties() const { return interested_parties_; }
 
  // Note: This must be invoked while holding the combiner.
  void Orphan() override;
 
  // A picker that returns PICK_QUEUE for all picks.
  // Also calls the parent LB policy's ExitIdleLocked() method when the
  // first pick is seen.
  class QueuePicker : public SubchannelPicker {
   public:
    explicit QueuePicker(RefCountedPtr<LoadBalancingPolicy> parent)
        : parent_(std::move(parent)) {}
 
    ~QueuePicker() { parent_.reset(DEBUG_LOCATION, "QueuePicker"); }
 
    PickResult Pick(PickArgs args) override;
 
   private:
    static void CallExitIdle(void* arg, grpc_error* error);
 
    RefCountedPtr<LoadBalancingPolicy> parent_;
    bool exit_idle_called_ = false;
  };
 
  // A picker that returns PICK_TRANSIENT_FAILURE for all picks.
  class TransientFailurePicker : public SubchannelPicker {
   public:
    explicit TransientFailurePicker(grpc_error* error) : error_(error) {}
    ~TransientFailurePicker() override { GRPC_ERROR_UNREF(error_); }
 
    PickResult Pick(PickArgs args) override;
 
   private:
    grpc_error* error_;
  };
 
 protected:
  Combiner* combiner() const { return combiner_; }
 
  // Note: LB policies MUST NOT call any method on the helper from their
  // constructor.
  ChannelControlHelper* channel_control_helper() const {
    return channel_control_helper_.get();
  }
 
  virtual void ShutdownLocked() = 0;
 
 private:
  Combiner* combiner_;
  grpc_pollset_set* interested_parties_;
  std::unique_ptr<ChannelControlHelper> channel_control_helper_;
};
 
}  // namespace grpc_core
 
#endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_H */