grpc 1.42.0 → 1.49.1

data/src/core/lib/promise/detail/promise_factory.h

@@ -0,0 +1,187 @@
+// Copyright 2021 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_LIB_PROMISE_DETAIL_PROMISE_FACTORY_H
+#define GRPC_CORE_LIB_PROMISE_DETAIL_PROMISE_FACTORY_H
+
+#include <grpc/support/port_platform.h>
+
+#include <utility>
+
+#include "absl/meta/type_traits.h"
+
+#include "src/core/lib/promise/detail/promise_like.h"
+
+// PromiseFactory is an adaptor class.
+//
+// Where a Promise is a thing that's polled periodically, a PromiseFactory
+// creates a Promise. Within this Promise/Activity framework, PromiseFactory's
+// then provide the edges for computation -- invoked at state transition
+// boundaries to provide the new steady state.
+//
+// A PromiseFactory formally is f(A) -> Promise<T> for some types A & T.
+// This get a bit awkward and inapproprate to write however, and so the type
+// contained herein can adapt various kinds of callable into the correct form.
+// Of course a callable of a single argument returning a Promise will see an
+// identity translation. One taking no arguments and returning a Promise
+// similarly.
+//
+// A Promise passed to a PromiseFactory will yield a PromiseFactory that
+// returns just that Promise.
+//
+// Generalizing slightly, a callable taking a single argument A and returning a
+// Poll<T> will yield a PromiseFactory that captures it's argument A and
+// returns a Poll<T>.
+//
+// Since various consumers of PromiseFactory run either repeatedly through an
+// overarching Promises lifetime, or just once, and we can optimize just once
+// by moving the contents of the PromiseFactory, two factory methods are
+// provided: Once, that can be called just once, and Repeated, that can (wait
+// for it) be called Repeatedly.
+
+namespace grpc_core {
+namespace promise_detail {
+
+// Helper trait: given a T, and T x, is calling x() legal?
+template <typename T, typename Ignored = void>
+struct IsVoidCallable {
+  static constexpr bool value = false;
+};
+template <typename F>
+struct IsVoidCallable<F, absl::void_t<decltype(std::declval<F>()())>> {
+  static constexpr bool value = true;
+};
+
+// Given F(A,B,C,...), what's the return type?
+template <typename T, typename Ignored = void>
+struct ResultOfT;
+
+template <typename F, typename... Args>
+struct ResultOfT<F(Args...),
+                 absl::void_t<decltype(std::declval<RemoveCVRef<F>>()(
+                     std::declval<Args>()...))>> {
+  using T = decltype(std::declval<RemoveCVRef<F>>()(std::declval<Args>()...));
+};
+
+template <typename T>
+using ResultOf = typename ResultOfT<T>::T;
+
+// Captures the promise functor and the argument passed.
+// Provides the interface of a promise.
+template <typename F, typename Arg>
+class Curried {
+ public:
+  Curried(F&& f, Arg&& arg)
+      : f_(std::forward<F>(f)), arg_(std::forward<Arg>(arg)) {}
+  Curried(const F& f, Arg&& arg) : f_(f), arg_(std::forward<Arg>(arg)) {}
+  using Result = decltype(std::declval<F>()(std::declval<Arg>()));
+  Result operator()() { return f_(std::move(arg_)); }
+
+ private:
+  GPR_NO_UNIQUE_ADDRESS F f_;
+  GPR_NO_UNIQUE_ADDRESS Arg arg_;
+};
+
+// Promote a callable(A) -> T | Poll<T> to a PromiseFactory(A) -> Promise<T> by
+// capturing A.
+template <typename A, typename F>
+absl::enable_if_t<!IsVoidCallable<ResultOf<F(A)>>::value,
+                  PromiseLike<Curried<RemoveCVRef<F>, A>>>
+PromiseFactoryImpl(F&& f, A&& arg) {
+  return Curried<RemoveCVRef<F>, A>(std::forward<F>(f), std::forward<A>(arg));
+}
+
+// Promote a callable() -> T|Poll<T> to a PromiseFactory(A) -> Promise<T>
+// by dropping the argument passed to the factory.
+template <typename A, typename F>
+absl::enable_if_t<!IsVoidCallable<ResultOf<F()>>::value,
+                  PromiseLike<RemoveCVRef<F>>>
+PromiseFactoryImpl(F f, A&&) {
+  return PromiseLike<F>(std::move(f));
+}
+
+// Promote a callable() -> T|Poll<T> to a PromiseFactory() -> Promise<T>
+template <typename F>
+absl::enable_if_t<!IsVoidCallable<ResultOf<F()>>::value,
+                  PromiseLike<RemoveCVRef<F>>>
+PromiseFactoryImpl(F f) {
+  return PromiseLike<F>(std::move(f));
+}
+
+// Given a callable(A) -> Promise<T>, name it a PromiseFactory and use it.
+template <typename A, typename F>
+absl::enable_if_t<IsVoidCallable<ResultOf<F(A)>>::value,
+                  PromiseLike<decltype(std::declval<F>()(std::declval<A>()))>>
+PromiseFactoryImpl(F&& f, A&& arg) {
+  return f(std::forward<A>(arg));
+}
+
+// Given a callable() -> Promise<T>, promote it to a
+// PromiseFactory(A) -> Promise<T> by dropping the first argument.
+template <typename A, typename F>
+absl::enable_if_t<IsVoidCallable<ResultOf<F()>>::value,
+                  PromiseLike<decltype(std::declval<F>()())>>
+PromiseFactoryImpl(F&& f, A&&) {
+  return f();
+}
+
+// Given a callable() -> Promise<T>, name it a PromiseFactory and use it.
+template <typename F>
+absl::enable_if_t<IsVoidCallable<ResultOf<F()>>::value,
+                  PromiseLike<decltype(std::declval<F>()())>>
+PromiseFactoryImpl(F&& f) {
+  return f();
+};
+
+template <typename A, typename F>
+class PromiseFactory {
+ private:
+  GPR_NO_UNIQUE_ADDRESS F f_;
+
+ public:
+  using Arg = A;
+  using Promise =
+      decltype(PromiseFactoryImpl(std::move(f_), std::declval<A>()));
+
+  explicit PromiseFactory(F f) : f_(std::move(f)) {}
+
+  Promise Once(Arg&& a) {
+    return PromiseFactoryImpl(std::move(f_), std::forward<Arg>(a));
+  }
+
+  Promise Repeated(Arg&& a) const {
+    return PromiseFactoryImpl(f_, std::forward<Arg>(a));
+  }
+};
+
+template <typename F>
+class PromiseFactory<void, F> {
+ private:
+  GPR_NO_UNIQUE_ADDRESS F f_;
+
+ public:
+  using Arg = void;
+  using Promise = decltype(PromiseFactoryImpl(std::move(f_)));
+
+  explicit PromiseFactory(F f) : f_(std::move(f)) {}
+
+  Promise Once() { return PromiseFactoryImpl(std::move(f_)); }
+
+  Promise Repeated() const { return PromiseFactoryImpl(f_); }
+};
+
+}  // namespace promise_detail
+}  // namespace grpc_core
+
+#endif  // GRPC_CORE_LIB_PROMISE_DETAIL_PROMISE_FACTORY_H

data/src/core/lib/promise/detail/promise_like.h

@@ -0,0 +1,85 @@
+// Copyright 2021 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_LIB_PROMISE_DETAIL_PROMISE_LIKE_H
+#define GRPC_CORE_LIB_PROMISE_DETAIL_PROMISE_LIKE_H
+
+#include <grpc/support/port_platform.h>
+
+#include <utility>
+
+#include "absl/meta/type_traits.h"
+
+#include "src/core/lib/promise/poll.h"
+
+// A Promise is a callable object that returns Poll<T> for some T.
+// Often when we're writing code that uses promises, we end up wanting to also
+// deal with code that completes instantaneously - that is, it returns some T
+// where T is not Poll.
+// PromiseLike wraps any callable that takes no parameters and implements the
+// Promise interface. For things that already return Poll, this wrapping does
+// nothing. For things that do not return Poll, we wrap the return type in Poll.
+// This allows us to write things like:
+//   Seq(
+//     [] { return 42; },
+//     ...)
+// in preference to things like:
+//   Seq(
+//     [] { return Poll<int>(42); },
+//     ...)
+// or:
+//   Seq(
+//     [] -> Poll<int> { return 42; },
+//     ...)
+// leading to slightly more concise code and eliminating some rules that in
+// practice people find hard to deal with.
+
+namespace grpc_core {
+namespace promise_detail {
+
+template <typename T>
+struct PollWrapper {
+  static Poll<T> Wrap(T&& x) { return Poll<T>(std::forward<T>(x)); }
+};
+
+template <typename T>
+struct PollWrapper<Poll<T>> {
+  static Poll<T> Wrap(Poll<T>&& x) { return std::forward<Poll<T>>(x); }
+};
+
+template <typename T>
+auto WrapInPoll(T&& x) -> decltype(PollWrapper<T>::Wrap(std::forward<T>(x))) {
+  return PollWrapper<T>::Wrap(std::forward<T>(x));
+}
+
+template <typename F>
+class PromiseLike {
+ private:
+  GPR_NO_UNIQUE_ADDRESS F f_;
+
+ public:
+  // NOLINTNEXTLINE - internal detail that drastically simplifies calling code.
+  PromiseLike(F&& f) : f_(std::forward<F>(f)) {}
+  auto operator()() -> decltype(WrapInPoll(f_())) { return WrapInPoll(f_()); }
+  using Result = typename PollTraits<decltype(WrapInPoll(f_()))>::Type;
+};
+
+// T -> T, const T& -> T
+template <typename T>
+using RemoveCVRef = absl::remove_cv_t<absl::remove_reference_t<T>>;
+
+}  // namespace promise_detail
+}  // namespace grpc_core
+
+#endif  // GRPC_CORE_LIB_PROMISE_DETAIL_PROMISE_LIKE_H

data/src/core/lib/promise/detail/status.h

@@ -0,0 +1,50 @@
+// Copyright 2021 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_LIB_PROMISE_DETAIL_STATUS_H
+#define GRPC_CORE_LIB_PROMISE_DETAIL_STATUS_H
+
+#include <grpc/support/port_platform.h>
+
+#include <utility>
+
+#include "absl/status/status.h"
+#include "absl/status/statusor.h"
+
+// Helpers for dealing with absl::Status/StatusOr generically
+
+namespace grpc_core {
+namespace promise_detail {
+
+// Convert with a move the input status to an absl::Status.
+template <typename T>
+absl::Status IntoStatus(absl::StatusOr<T>* status) {
+  return std::move(status->status());
+}
+
+// Convert with a move the input status to an absl::Status.
+inline absl::Status IntoStatus(absl::Status* status) {
+  return std::move(*status);
+}
+
+}  // namespace promise_detail
+
+// Return true if the status represented by the argument is ok, false if not.
+// By implementing this function for other, non-absl::Status types, those types
+// can participate in TrySeq as result types that affect control flow.
+inline bool IsStatusOk(const absl::Status& status) { return status.ok(); }
+
+}  // namespace grpc_core
+
+#endif  // GRPC_CORE_LIB_PROMISE_DETAIL_STATUS_H

data/src/core/lib/promise/exec_ctx_wakeup_scheduler.h

@@ -0,0 +1,48 @@
+// Copyright 2021 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_LIB_PROMISE_EXEC_CTX_WAKEUP_SCHEDULER_H
+#define GRPC_CORE_LIB_PROMISE_EXEC_CTX_WAKEUP_SCHEDULER_H
+
+#include <grpc/support/port_platform.h>
+
+#include "src/core/lib/gprpp/debug_location.h"
+#include "src/core/lib/iomgr/closure.h"
+#include "src/core/lib/iomgr/error.h"
+#include "src/core/lib/iomgr/exec_ctx.h"
+
+namespace grpc_core {
+
+// A callback scheduler for activities that works by scheduling callbacks on the
+// exec ctx.
+class ExecCtxWakeupScheduler {
+ public:
+  template <typename ActivityType>
+  void ScheduleWakeup(ActivityType* activity) {
+    GRPC_CLOSURE_INIT(
+        &closure_,
+        [](void* arg, grpc_error_handle) {
+          static_cast<ActivityType*>(arg)->RunScheduledWakeup();
+        },
+        activity, grpc_schedule_on_exec_ctx);
+    ExecCtx::Run(DEBUG_LOCATION, &closure_, GRPC_ERROR_NONE);
+  }
+
+ private:
+  grpc_closure closure_;
+};
+
+}  // namespace grpc_core
+
+#endif  // GRPC_CORE_LIB_PROMISE_EXEC_CTX_WAKEUP_SCHEDULER_H

data/src/core/lib/promise/intra_activity_waiter.h

@@ -0,0 +1,49 @@
+// Copyright 2021 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_LIB_PROMISE_INTRA_ACTIVITY_WAITER_H
+#define GRPC_CORE_LIB_PROMISE_INTRA_ACTIVITY_WAITER_H
+
+#include <grpc/support/port_platform.h>
+
+#include "src/core/lib/promise/activity.h"
+#include "src/core/lib/promise/poll.h"
+
+namespace grpc_core {
+
+// Helper type to track wakeups between objects in the same activity.
+// Can be fairly fast as no ref counting or locking needs to occur.
+class IntraActivityWaiter {
+ public:
+  // Register for wakeup, return Pending(). If state is not ready to proceed,
+  // Promises should bottom out here.
+  Pending pending() {
+    waiting_ = true;
+    return Pending();
+  }
+  // Wake the activity
+  void Wake() {
+    if (waiting_) {
+      waiting_ = false;
+      Activity::current()->ForceImmediateRepoll();
+    }
+  }
+
+ private:
+  bool waiting_ = false;
+};
+
+}  // namespace grpc_core
+
+#endif  // GRPC_CORE_LIB_PROMISE_INTRA_ACTIVITY_WAITER_H

data/src/core/lib/promise/latch.h

@@ -0,0 +1,103 @@
+// Copyright 2021 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_LIB_PROMISE_LATCH_H
+#define GRPC_CORE_LIB_PROMISE_LATCH_H
+
+#include <grpc/support/port_platform.h>
+
+#include <grpc/support/log.h>
+
+#include "src/core/lib/promise/intra_activity_waiter.h"
+#include "src/core/lib/promise/poll.h"
+
+namespace grpc_core {
+
+// Latch provides a single set waitable object.
+// Initially the Latch is unset.
+// It can be waited upon by the Wait method, which produces a Promise that
+// resolves when the Latch is Set to a value of type T.
+template <typename T>
+class Latch {
+ public:
+  // This is the type of the promise returned by Wait.
+  class WaitPromise {
+   public:
+    Poll<T*> operator()() const {
+      if (latch_->has_value_) {
+        return &latch_->value_;
+      } else {
+        return latch_->waiter_.pending();
+      }
+    }
+
+   private:
+    friend class Latch;
+    explicit WaitPromise(Latch* latch) : latch_(latch) {}
+    Latch* latch_;
+  };
+
+  Latch() = default;
+  Latch(const Latch&) = delete;
+  Latch& operator=(const Latch&) = delete;
+  Latch(Latch&& other) noexcept
+      : value_(std::move(other.value_)), has_value_(other.has_value_) {
+#ifndef NDEBUG
+    GPR_DEBUG_ASSERT(!other.has_had_waiters_);
+#endif
+  }
+  Latch& operator=(Latch&& other) noexcept {
+#ifndef NDEBUG
+    GPR_DEBUG_ASSERT(!other.has_had_waiters_);
+#endif
+    value_ = std::move(other.value_);
+    has_value_ = other.has_value_;
+    return *this;
+  }
+
+  // Produce a promise to wait for a value from this latch.
+  WaitPromise Wait() {
+#ifndef NDEBUG
+    has_had_waiters_ = true;
+#endif
+    return WaitPromise(this);
+  }
+
+  // Set the value of the latch. Can only be called once.
+  void Set(T value) {
+    GPR_DEBUG_ASSERT(!has_value_);
+    value_ = std::move(value);
+    has_value_ = true;
+    waiter_.Wake();
+  }
+
+ private:
+  // The value stored (if has_value_ is true), otherwise some random value, we
+  // don't care.
+  // Why not absl::optional<>? Writing things this way lets us compress
+  // has_value_ with waiter_ and leads to some significant memory savings for
+  // some scenarios.
+  GPR_NO_UNIQUE_ADDRESS T value_;
+  // True if we have a value set, false otherwise.
+  bool has_value_ = false;
+#ifndef NDEBUG
+  // Has this latch ever had waiters.
+  bool has_had_waiters_ = false;
+#endif
+  IntraActivityWaiter waiter_;
+};
+
+}  // namespace grpc_core
+
+#endif  // GRPC_CORE_LIB_PROMISE_LATCH_H

data/src/core/lib/promise/loop.h

@@ -0,0 +1,136 @@
+// Copyright 2021 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_LIB_PROMISE_LOOP_H
+#define GRPC_CORE_LIB_PROMISE_LOOP_H
+
+#include <grpc/support/port_platform.h>
+
+#include <new>
+#include <type_traits>
+#include <utility>
+
+#include "absl/status/status.h"
+#include "absl/status/statusor.h"
+#include "absl/types/variant.h"
+
+#include "src/core/lib/promise/detail/promise_factory.h"
+#include "src/core/lib/promise/poll.h"
+
+namespace grpc_core {
+
+// Special type - signals to loop to take another iteration, instead of
+// finishing
+struct Continue {};
+
+// Result of polling a loop promise - either Continue looping, or return a value
+// T
+template <typename T>
+using LoopCtl = absl::variant<Continue, T>;
+
+namespace promise_detail {
+
+template <typename T>
+struct LoopTraits;
+
+template <typename T>
+struct LoopTraits<LoopCtl<T>> {
+  using Result = T;
+  static LoopCtl<T> ToLoopCtl(LoopCtl<T> value) { return value; }
+};
+
+template <typename T>
+struct LoopTraits<absl::StatusOr<LoopCtl<T>>> {
+  using Result = absl::StatusOr<T>;
+  static LoopCtl<Result> ToLoopCtl(absl::StatusOr<LoopCtl<T>> value) {
+    if (!value.ok()) return value.status();
+    const auto& inner = *value;
+    if (absl::holds_alternative<Continue>(inner)) return Continue{};
+    return absl::get<T>(inner);
+  }
+};
+
+template <>
+struct LoopTraits<absl::StatusOr<LoopCtl<absl::Status>>> {
+  using Result = absl::Status;
+  static LoopCtl<Result> ToLoopCtl(
+      absl::StatusOr<LoopCtl<absl::Status>> value) {
+    if (!value.ok()) return value.status();
+    const auto& inner = *value;
+    if (absl::holds_alternative<Continue>(inner)) return Continue{};
+    return absl::get<absl::Status>(inner);
+  }
+};
+
+template <typename F>
+class Loop {
+ private:
+  using Factory = promise_detail::PromiseFactory<void, F>;
+  using PromiseType = decltype(std::declval<Factory>().Repeated());
+  using PromiseResult = typename PromiseType::Result;
+
+ public:
+  using Result = typename LoopTraits<PromiseResult>::Result;
+
+  explicit Loop(F f) : factory_(std::move(f)), promise_(factory_.Repeated()) {}
+  ~Loop() { promise_.~PromiseType(); }
+
+  Loop(Loop&& loop) noexcept
+      : factory_(std::move(loop.factory_)),
+        promise_(std::move(loop.promise_)) {}
+
+  Loop(const Loop& loop) = delete;
+  Loop& operator=(const Loop& loop) = delete;
+
+  Poll<Result> operator()() {
+    while (true) {
+      // Poll the inner promise.
+      auto promise_result = promise_();
+      // If it returns a value:
+      if (auto* p = absl::get_if<kPollReadyIdx>(&promise_result)) {
+        //  - then if it's Continue, destroy the promise and recreate a new one
+        //  from our factory.
+        auto lc = LoopTraits<PromiseResult>::ToLoopCtl(*p);
+        if (absl::holds_alternative<Continue>(lc)) {
+          promise_.~PromiseType();
+          new (&promise_) PromiseType(factory_.Repeated());
+          continue;
+        }
+        //  - otherwise there's our result... return it out.
+        return absl::get<Result>(lc);
+      } else {
+        // Otherwise the inner promise was pending, so we are pending.
+        return Pending();
+      }
+    }
+  }
+
+ private:
+  GPR_NO_UNIQUE_ADDRESS Factory factory_;
+  GPR_NO_UNIQUE_ADDRESS union { GPR_NO_UNIQUE_ADDRESS PromiseType promise_; };
+};
+
+}  // namespace promise_detail
+
+// Looping combinator.
+// Expects F returns LoopCtl<T> - if it's Continue, then run the loop again -
+// otherwise yield the returned value as the result of the loop.
+template <typename F>
+promise_detail::Loop<F> Loop(F f) {
+  return promise_detail::Loop<F>(std::move(f));
+}
+
+}  // namespace grpc_core
+
+#endif  // GRPC_CORE_LIB_PROMISE_LOOP_H