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 <stddef.h>
#include <stdint.h>
 
#include <memory>
#include <string>
#include <type_traits>
#include <utility>
#include <vector>
 
#include "absl/status/status.h"
#include "absl/status/statusor.h"
#include "absl/strings/string_view.h"
#include "absl/types/optional.h"
#include "absl/types/variant.h"
 
#include <grpc/impl/codegen/connectivity_state.h>
#include <grpc/impl/codegen/grpc_types.h>
 
#include "src/core/ext/filters/client_channel/lb_policy/backend_metric_data.h"
#include "src/core/ext/filters/client_channel/subchannel_interface.h"
#include "src/core/lib/channel/channel_args.h"
#include "src/core/lib/debug/trace.h"
#include "src/core/lib/gprpp/debug_location.h"
#include "src/core/lib/gprpp/orphanable.h"
#include "src/core/lib/gprpp/ref_counted.h"
#include "src/core/lib/gprpp/ref_counted_ptr.h"
#include "src/core/lib/iomgr/iomgr_fwd.h"
#include "src/core/lib/iomgr/work_serializer.h"
#include "src/core/lib/resolver/server_address.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:
  class CallState {
   public:
    CallState() = default;
    virtual ~CallState() = default;
 
    virtual void* Alloc(size_t size) = 0;
  };
 
  class MetadataInterface {
   public:
    virtual ~MetadataInterface() = default;
 
    // TODO(ctiller): DO NOT MAKE THIS A PUBLIC API YET
    // This needs some API design to ensure we can add/remove/replace metadata
    // keys... we're deliberately not doing so to save some time whilst
    // cleaning up the internal metadata representation, but we should add
    // something back before making this a public API.
 
    virtual void Add(absl::string_view key, absl::string_view value) = 0;
 
    virtual std::vector<std::pair<std::string, std::string>>
    TestOnlyCopyToVector() = 0;
 
    virtual absl::optional<absl::string_view> Lookup(
        absl::string_view key, std::string* buffer) const = 0;
  };
 
  struct PickArgs {
    absl::string_view path;
    MetadataInterface* initial_metadata;
    CallState* call_state;
  };
 
  class BackendMetricAccessor {
   public:
    virtual ~BackendMetricAccessor() = default;
 
    virtual const BackendMetricData* GetBackendMetricData() = 0;
  };
 
  class SubchannelCallTrackerInterface {
   public:
    virtual ~SubchannelCallTrackerInterface() = default;
 
    virtual void Start() = 0;
 
    struct FinishArgs {
      absl::Status status;
      MetadataInterface* trailing_metadata;
      BackendMetricAccessor* backend_metric_accessor;
    };
    virtual void Finish(FinishArgs args) = 0;
  };
 
  struct PickResult {
    struct Complete {
      RefCountedPtr<SubchannelInterface> subchannel;
 
      std::unique_ptr<SubchannelCallTrackerInterface> subchannel_call_tracker;
 
      explicit Complete(
          RefCountedPtr<SubchannelInterface> sc,
          std::unique_ptr<SubchannelCallTrackerInterface> tracker = nullptr)
          : subchannel(std::move(sc)),
            subchannel_call_tracker(std::move(tracker)) {}
    };
 
    struct Queue {};
 
    struct Fail {
      absl::Status status;
 
      explicit Fail(absl::Status s) : status(s) {}
    };
 
    struct Drop {
      absl::Status status;
 
      explicit Drop(absl::Status s) : status(s) {}
    };
 
    // A pick result must be one of these types.
    // Default to Queue, just to allow default construction.
    absl::variant<Complete, Queue, Fail, Drop> result = Queue();
 
    PickResult() = default;
    // NOLINTNEXTLINE(google-explicit-constructor)
    PickResult(Complete complete) : result(std::move(complete)) {}
    // NOLINTNEXTLINE(google-explicit-constructor)
    PickResult(Queue queue) : result(queue) {}
    // NOLINTNEXTLINE(google-explicit-constructor)
    PickResult(Fail fail) : result(std::move(fail)) {}
    // NOLINTNEXTLINE(google-explicit-constructor)
    PickResult(Drop drop) : result(std::move(drop)) {}
  };
 
  class SubchannelPicker {
   public:
    SubchannelPicker() = default;
    virtual ~SubchannelPicker() = default;
 
    virtual PickResult Pick(PickArgs args) = 0;
  };
 
  // TODO(roth): Once insecure builds go away, add methods for accessing
  // channel creds.  By default, that should strip off the call creds
  // attached to the channel creds, but there should also be a "use at
  // your own risk" option to get the channel creds without stripping
  // off the attached call creds.
  class ChannelControlHelper {
   public:
    ChannelControlHelper() = default;
    virtual ~ChannelControlHelper() = default;
 
    virtual RefCountedPtr<SubchannelInterface> CreateSubchannel(
        ServerAddress address, const grpc_channel_args& args) = 0;
 
    virtual void UpdateState(grpc_connectivity_state state,
                             const absl::Status& status,
                             std::unique_ptr<SubchannelPicker>) = 0;
 
    virtual void RequestReresolution() = 0;
 
    virtual absl::string_view GetAuthority() = 0;
 
    enum TraceSeverity { TRACE_INFO, TRACE_WARNING, TRACE_ERROR };
    virtual void AddTraceEvent(TraceSeverity severity,
                               absl::string_view message) = 0;
  };
 
  class Config : public RefCounted<Config> {
   public:
    ~Config() override = default;
 
    // Returns the load balancing policy name
    virtual const char* name() const = 0;
  };
 
  struct UpdateArgs {
    absl::StatusOr<ServerAddressList> addresses;
    RefCountedPtr<Config> config;
    std::string resolution_note;
 
    // TODO(roth): Before making this a public API, find a better
    // abstraction for representing channel args.
    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) noexcept;
    UpdateArgs& operator=(const UpdateArgs& other);
    UpdateArgs& operator=(UpdateArgs&& other) noexcept;
  };
 
  struct Args {
    std::shared_ptr<WorkSerializer> work_serializer;
    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);
  ~LoadBalancingPolicy() override;
 
  // Not copyable nor movable.
  LoadBalancingPolicy(const LoadBalancingPolicy&) = delete;
  LoadBalancingPolicy& operator=(const LoadBalancingPolicy&) = delete;
 
  virtual const char* name() const = 0;
 
  // TODO(roth): Change this to return some indication as to whether the
  // update has been accepted, so that we can indicate to the resolver
  // whether it should go into backoff to retry the resolution.
  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 work_serializer.
  void Orphan() override;
 
  // A picker that returns PickResult::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() override { parent_.reset(DEBUG_LOCATION, "QueuePicker"); }
 
    PickResult Pick(PickArgs args) override;
 
   private:
    RefCountedPtr<LoadBalancingPolicy> parent_;
    bool exit_idle_called_ = false;
  };
 
  // A picker that returns PickResult::Fail for all picks.
  class TransientFailurePicker : public SubchannelPicker {
   public:
    explicit TransientFailurePicker(absl::Status status) : status_(status) {}
 
    PickResult Pick(PickArgs /*args*/) override {
      return PickResult::Fail(status_);
    }
 
   private:
    absl::Status status_;
  };
 
 protected:
  std::shared_ptr<WorkSerializer> work_serializer() const {
    return work_serializer_;
  }
 
  // 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:
  std::shared_ptr<WorkSerializer> work_serializer_;
  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