grpc 1.47.0 → 1.48.0.pre1

data/src/core/lib/event_engine/iomgr_engine/timer.cc

@@ -0,0 +1,312 @@
+/*
+ *
+ * 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.
+ *
+ */
+
+#include <grpc/support/port_platform.h>
+
+#include "src/core/lib/event_engine/iomgr_engine/timer.h"
+
+#include <algorithm>
+#include <atomic>
+#include <limits>
+#include <type_traits>
+#include <utility>
+
+#include <grpc/support/cpu.h>
+
+#include "src/core/lib/event_engine/iomgr_engine/timer_heap.h"
+#include "src/core/lib/gpr/useful.h"
+#include "src/core/lib/gprpp/time.h"
+
+namespace grpc_event_engine {
+namespace iomgr_engine {
+
+static const size_t kInvalidHeapIndex = std::numeric_limits<size_t>::max();
+static const double kAddDeadlineScale = 0.33;
+static const double kMinQueueWindowDuration = 0.01;
+static const double kMaxQueueWindowDuration = 1.0;
+
+grpc_core::Timestamp TimerList::Shard::ComputeMinDeadline() {
+  return heap.is_empty()
+             ? queue_deadline_cap + grpc_core::Duration::Epsilon()
+             : grpc_core::Timestamp::FromMillisecondsAfterProcessEpoch(
+                   heap.Top()->deadline);
+}
+
+TimerList::Shard::Shard() : stats(1.0 / kAddDeadlineScale, 0.1, 0.5) {}
+
+TimerList::TimerList(TimerListHost* host)
+    : host_(host),
+      num_shards_(grpc_core::Clamp(2 * gpr_cpu_num_cores(), 1u, 32u)),
+      min_timer_(host_->Now().milliseconds_after_process_epoch()),
+      shards_(new Shard[num_shards_]),
+      shard_queue_(new Shard*[num_shards_]) {
+  for (size_t i = 0; i < num_shards_; i++) {
+    Shard& shard = shards_[i];
+    shard.queue_deadline_cap =
+        grpc_core::Timestamp::FromMillisecondsAfterProcessEpoch(
+            min_timer_.load(std::memory_order_relaxed));
+    shard.shard_queue_index = i;
+    shard.list.next = shard.list.prev = &shard.list;
+    shard.min_deadline = shard.ComputeMinDeadline();
+    shard_queue_[i] = &shard;
+  }
+}
+
+namespace {
+/* returns true if the first element in the list */
+void ListJoin(Timer* head, Timer* timer) {
+  timer->next = head;
+  timer->prev = head->prev;
+  timer->next->prev = timer->prev->next = timer;
+}
+
+void ListRemove(Timer* timer) {
+  timer->next->prev = timer->prev;
+  timer->prev->next = timer->next;
+}
+}  // namespace
+
+void TimerList::SwapAdjacentShardsInQueue(uint32_t first_shard_queue_index) {
+  Shard* temp;
+  temp = shard_queue_[first_shard_queue_index];
+  shard_queue_[first_shard_queue_index] =
+      shard_queue_[first_shard_queue_index + 1];
+  shard_queue_[first_shard_queue_index + 1] = temp;
+  shard_queue_[first_shard_queue_index]->shard_queue_index =
+      first_shard_queue_index;
+  shard_queue_[first_shard_queue_index + 1]->shard_queue_index =
+      first_shard_queue_index + 1;
+}
+
+void TimerList::NoteDeadlineChange(Shard* shard) {
+  while (shard->shard_queue_index > 0 &&
+         shard->min_deadline <
+             shard_queue_[shard->shard_queue_index - 1]->min_deadline) {
+    SwapAdjacentShardsInQueue(shard->shard_queue_index - 1);
+  }
+  while (shard->shard_queue_index < num_shards_ - 1 &&
+         shard->min_deadline >
+             shard_queue_[shard->shard_queue_index + 1]->min_deadline) {
+    SwapAdjacentShardsInQueue(shard->shard_queue_index);
+  }
+}
+
+void TimerList::TimerInit(Timer* timer, grpc_core::Timestamp deadline,
+                          experimental::EventEngine::Closure* closure) {
+  bool is_first_timer = false;
+  Shard* shard = &shards_[grpc_core::HashPointer(timer, num_shards_)];
+  timer->closure = closure;
+  timer->deadline = deadline.milliseconds_after_process_epoch();
+
+#ifndef NDEBUG
+  timer->hash_table_next = nullptr;
+#endif
+
+  {
+    grpc_core::MutexLock lock(&shard->mu);
+    timer->pending = true;
+    grpc_core::Timestamp now = host_->Now();
+    if (deadline <= now) {
+      deadline = now;
+    }
+
+    shard->stats.AddSample((deadline - now).millis() / 1000.0);
+
+    if (deadline < shard->queue_deadline_cap) {
+      is_first_timer = shard->heap.Add(timer);
+    } else {
+      timer->heap_index = kInvalidHeapIndex;
+      ListJoin(&shard->list, timer);
+    }
+  }
+
+  /* Deadline may have decreased, we need to adjust the main queue.  Note
+     that there is a potential racy unlocked region here.  There could be a
+     reordering of multiple TimerInit calls, at this point, but the < test
+     below should ensure that we err on the side of caution.  There could
+     also be a race with TimerCheck, which might beat us to the lock.  In
+     that case, it is possible that the timer that we added will have already
+     run by the time we hold the lock, but that too is a safe error.
+     Finally, it's possible that the TimerCheck that intervened failed to
+     trigger the new timer because the min_deadline hadn't yet been reduced.
+     In that case, the timer will simply have to wait for the next
+     TimerCheck. */
+  if (is_first_timer) {
+    grpc_core::MutexLock lock(&mu_);
+    if (deadline < shard->min_deadline) {
+      grpc_core::Timestamp old_min_deadline = shard_queue_[0]->min_deadline;
+      shard->min_deadline = deadline;
+      NoteDeadlineChange(shard);
+      if (shard->shard_queue_index == 0 && deadline < old_min_deadline) {
+        min_timer_.store(deadline.milliseconds_after_process_epoch(),
+                         std::memory_order_relaxed);
+        host_->Kick();
+      }
+    }
+  }
+}
+
+bool TimerList::TimerCancel(Timer* timer) {
+  Shard* shard = &shards_[grpc_core::HashPointer(timer, num_shards_)];
+  grpc_core::MutexLock lock(&shard->mu);
+
+  if (timer->pending) {
+    timer->pending = false;
+    if (timer->heap_index == kInvalidHeapIndex) {
+      ListRemove(timer);
+    } else {
+      shard->heap.Remove(timer);
+    }
+    return true;
+  }
+
+  return false;
+}
+
+/* Rebalances the timer shard by computing a new 'queue_deadline_cap' and moving
+   all relevant timers in shard->list (i.e timers with deadlines earlier than
+   'queue_deadline_cap') into into shard->heap.
+   Returns 'true' if shard->heap has at least ONE element */
+bool TimerList::Shard::RefillHeap(grpc_core::Timestamp now) {
+  /* Compute the new queue window width and bound by the limits: */
+  double computed_deadline_delta = stats.UpdateAverage() * kAddDeadlineScale;
+  double deadline_delta =
+      grpc_core::Clamp(computed_deadline_delta, kMinQueueWindowDuration,
+                       kMaxQueueWindowDuration);
+  Timer *timer, *next;
+
+  /* Compute the new cap and put all timers under it into the queue: */
+  queue_deadline_cap = std::max(now, queue_deadline_cap) +
+                       grpc_core::Duration::FromSecondsAsDouble(deadline_delta);
+
+  for (timer = list.next; timer != &list; timer = next) {
+    next = timer->next;
+    auto timer_deadline =
+        grpc_core::Timestamp::FromMillisecondsAfterProcessEpoch(
+            timer->deadline);
+
+    if (timer_deadline < queue_deadline_cap) {
+      ListRemove(timer);
+      heap.Add(timer);
+    }
+  }
+  return !heap.is_empty();
+}
+
+/* This pops the next non-cancelled timer with deadline <= now from the
+   queue, or returns NULL if there isn't one. */
+Timer* TimerList::Shard::PopOne(grpc_core::Timestamp now) {
+  Timer* timer;
+  for (;;) {
+    if (heap.is_empty()) {
+      if (now < queue_deadline_cap) return nullptr;
+      if (!RefillHeap(now)) return nullptr;
+    }
+    timer = heap.Top();
+    auto timer_deadline =
+        grpc_core::Timestamp::FromMillisecondsAfterProcessEpoch(
+            timer->deadline);
+    if (timer_deadline > now) return nullptr;
+    timer->pending = false;
+    heap.Pop();
+    return timer;
+  }
+}
+
+void TimerList::Shard::PopTimers(
+    grpc_core::Timestamp now, grpc_core::Timestamp* new_min_deadline,
+    std::vector<experimental::EventEngine::Closure*>* out) {
+  grpc_core::MutexLock lock(&mu);
+  while (Timer* timer = PopOne(now)) {
+    out->push_back(timer->closure);
+  }
+  *new_min_deadline = ComputeMinDeadline();
+}
+
+std::vector<experimental::EventEngine::Closure*> TimerList::FindExpiredTimers(
+    grpc_core::Timestamp now, grpc_core::Timestamp* next) {
+  grpc_core::Timestamp min_timer =
+      grpc_core::Timestamp::FromMillisecondsAfterProcessEpoch(
+          min_timer_.load(std::memory_order_relaxed));
+
+  std::vector<experimental::EventEngine::Closure*> done;
+  if (now < min_timer) {
+    if (next != nullptr) *next = std::min(*next, min_timer);
+    return done;
+  }
+
+  grpc_core::MutexLock lock(&mu_);
+
+  while (shard_queue_[0]->min_deadline < now ||
+         (now != grpc_core::Timestamp::InfFuture() &&
+          shard_queue_[0]->min_deadline == now)) {
+    grpc_core::Timestamp new_min_deadline;
+
+    /* For efficiency, we pop as many available timers as we can from the
+       shard.  This may violate perfect timer deadline ordering, but that
+       shouldn't be a big deal because we don't make ordering guarantees. */
+    shard_queue_[0]->PopTimers(now, &new_min_deadline, &done);
+
+    /* An TimerInit() on the shard could intervene here, adding a new
+       timer that is earlier than new_min_deadline.  However,
+       TimerInit() will block on the mutex before it can call
+       set_min_deadline, so this one will complete first and then the Addtimer
+       will reduce the min_deadline (perhaps unnecessarily). */
+    shard_queue_[0]->min_deadline = new_min_deadline;
+    NoteDeadlineChange(shard_queue_[0]);
+  }
+
+  if (next) {
+    *next = std::min(*next, shard_queue_[0]->min_deadline);
+  }
+
+  min_timer_.store(
+      shard_queue_[0]->min_deadline.milliseconds_after_process_epoch(),
+      std::memory_order_relaxed);
+
+  return done;
+}
+
+absl::optional<std::vector<experimental::EventEngine::Closure*>>
+TimerList::TimerCheck(grpc_core::Timestamp* next) {
+  // prelude
+  grpc_core::Timestamp now = host_->Now();
+
+  /* fetch from a thread-local first: this avoids contention on a globally
+     mutable cacheline in the common case */
+  grpc_core::Timestamp min_timer =
+      grpc_core::Timestamp::FromMillisecondsAfterProcessEpoch(
+          min_timer_.load(std::memory_order_relaxed));
+
+  if (now < min_timer) {
+    if (next != nullptr) {
+      *next = std::min(*next, min_timer);
+    }
+    return std::vector<experimental::EventEngine::Closure*>();
+  }
+
+  if (!checker_mu_.TryLock()) return absl::nullopt;
+  std::vector<experimental::EventEngine::Closure*> run =
+      FindExpiredTimers(now, next);
+  checker_mu_.Unlock();
+
+  return std::move(run);
+}
+
+}  // namespace iomgr_engine
+}  // namespace grpc_event_engine

data/src/core/lib/event_engine/iomgr_engine/timer.h

@@ -0,0 +1,193 @@
+/*
+ *
+ * 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_LIB_EVENT_ENGINE_IOMGR_ENGINE_TIMER_H
+#define GRPC_CORE_LIB_EVENT_ENGINE_IOMGR_ENGINE_TIMER_H
+
+#include <grpc/support/port_platform.h>
+
+#include <stddef.h>
+
+#include <atomic>
+#include <cstdint>
+#include <memory>
+#include <vector>
+
+#include "absl/base/thread_annotations.h"
+#include "absl/types/optional.h"
+
+#include <grpc/event_engine/event_engine.h>
+
+#include "src/core/lib/event_engine/iomgr_engine/time_averaged_stats.h"
+#include "src/core/lib/event_engine/iomgr_engine/timer_heap.h"
+#include "src/core/lib/gprpp/sync.h"
+#include "src/core/lib/gprpp/time.h"
+
+namespace grpc_event_engine {
+namespace iomgr_engine {
+
+struct Timer {
+  int64_t deadline;
+  // kInvalidHeapIndex if not in heap.
+  size_t heap_index;
+  bool pending;
+  struct Timer* next;
+  struct Timer* prev;
+  experimental::EventEngine::Closure* closure;
+#ifndef NDEBUG
+  struct Timer* hash_table_next;
+#endif
+
+  grpc_event_engine::experimental::EventEngine::TaskHandle task_handle;
+};
+
+// Dependency injection: allow tests and/or TimerManager to inject
+// their own implementations of Now, Kick.
+class TimerListHost {
+ public:
+  // Return the current timestamp.
+  // Abstracted so that tests can be run deterministically.
+  virtual grpc_core::Timestamp Now() = 0;
+  // Wake up a thread to check for timers.
+  virtual void Kick() = 0;
+
+ protected:
+  ~TimerListHost() = default;
+};
+
+class TimerList {
+ public:
+  explicit TimerList(TimerListHost* host);
+
+  TimerList(const TimerList&) = delete;
+  TimerList& operator=(const TimerList&) = delete;
+
+  /* Initialize *timer. When expired or canceled, closure will be called with
+   error set to indicate if it expired (GRPC_ERROR_NONE) or was canceled
+   (GRPC_ERROR_CANCELLED). *closure is guaranteed to be called exactly once, and
+   application code should check the error to determine how it was invoked. The
+   application callback is also responsible for maintaining information about
+   when to free up any user-level state. Behavior is undefined for a deadline of
+   grpc_core::Timestamp::InfFuture(). */
+  void TimerInit(Timer* timer, grpc_core::Timestamp deadline,
+                 experimental::EventEngine::Closure* closure);
+
+  /* Note that there is no timer destroy function. This is because the
+     timer is a one-time occurrence with a guarantee that the callback will
+     be called exactly once, either at expiration or cancellation. Thus, all
+     the internal timer event management state is destroyed just before
+     that callback is invoked. If the user has additional state associated with
+     the timer, the user is responsible for determining when it is safe to
+     destroy that state. */
+
+  /* Cancel an *timer.
+     There are three cases:
+     1. We normally cancel the timer
+     2. The timer has already run
+     3. We can't cancel the timer because it is "in flight".
+
+     In all of these cases, the cancellation is still considered successful.
+     They are essentially distinguished in that the timer_cb will be run
+     exactly once from either the cancellation (with error GRPC_ERROR_CANCELLED)
+     or from the activation (with error GRPC_ERROR_NONE).
+
+     Note carefully that the callback function MAY occur in the same callstack
+     as grpc_timer_cancel. It's expected that most timers will be cancelled
+     (their primary use is to implement deadlines), and so this code is
+     optimized such that cancellation costs as little as possible. Making
+     callbacks run inline matches this aim.
+
+     Requires: cancel() must happen after init() on a given timer */
+  bool TimerCancel(Timer* timer) GRPC_MUST_USE_RESULT;
+
+  /* iomgr internal api for dealing with timers */
+
+  /* Check for timers to be run, and return them.
+     Return nullopt if timers could not be checked due to contention with
+     another thread checking.
+     Return a vector of closures that *must* be run otherwise.
+     If next is non-null, TRY to update *next with the next running timer
+     IF that timer occurs before *next current value.
+     *next is never guaranteed to be updated on any given execution; however,
+     with high probability at least one thread in the system will see an update
+     at any time slice. */
+  absl::optional<std::vector<experimental::EventEngine::Closure*>> TimerCheck(
+      grpc_core::Timestamp* next);
+
+ private:
+  /* A "timer shard". Contains a 'heap' and a 'list' of timers. All timers with
+   * deadlines earlier than 'queue_deadline_cap' are maintained in the heap and
+   * others are maintained in the list (unordered). This helps to keep the
+   * number of elements in the heap low.
+   *
+   * The 'queue_deadline_cap' gets recomputed periodically based on the timer
+   * stats maintained in 'stats' and the relevant timers are then moved from the
+   * 'list' to 'heap'.
+   */
+  struct Shard {
+    Shard();
+
+    grpc_core::Timestamp ComputeMinDeadline() ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu);
+    bool RefillHeap(grpc_core::Timestamp now) ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu);
+    Timer* PopOne(grpc_core::Timestamp now) ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu);
+    void PopTimers(grpc_core::Timestamp now,
+                   grpc_core::Timestamp* new_min_deadline,
+                   std::vector<experimental::EventEngine::Closure*>* out)
+        ABSL_LOCKS_EXCLUDED(mu);
+
+    grpc_core::Mutex mu;
+    TimeAveragedStats stats ABSL_GUARDED_BY(mu);
+    /* All and only timers with deadlines < this will be in the heap. */
+    grpc_core::Timestamp queue_deadline_cap ABSL_GUARDED_BY(mu);
+    /* The deadline of the next timer due in this shard. */
+    grpc_core::Timestamp min_deadline ABSL_GUARDED_BY(&TimerList::mu_);
+    /* Index of this timer_shard in the g_shard_queue. */
+    uint32_t shard_queue_index ABSL_GUARDED_BY(&TimerList::mu_);
+    /* This holds all timers with deadlines < queue_deadline_cap. Timers in this
+       list have the top bit of their deadline set to 0. */
+    TimerHeap heap ABSL_GUARDED_BY(mu);
+    /* This holds timers whose deadline is >= queue_deadline_cap. */
+    Timer list ABSL_GUARDED_BY(mu);
+  };
+
+  void SwapAdjacentShardsInQueue(uint32_t first_shard_queue_index)
+      ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_);
+  void NoteDeadlineChange(Shard* shard) ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_);
+  std::vector<experimental::EventEngine::Closure*> FindExpiredTimers(
+      grpc_core::Timestamp now, grpc_core::Timestamp* next);
+
+  TimerListHost* const host_;
+  const size_t num_shards_;
+  grpc_core::Mutex mu_;
+  /* The deadline of the next timer due across all timer shards */
+  std::atomic<uint64_t> min_timer_;
+  /* Allow only one FindExpiredTimers at once (used as a TryLock, protects no
+   * fields but ensures limits on concurrency) */
+  grpc_core::Mutex checker_mu_;
+  /* Array of timer shards. Whenever a timer (Timer *) is added, its address
+   * is hashed to select the timer shard to add the timer to */
+  const std::unique_ptr<Shard[]> shards_;
+  /* Maintains a sorted list of timer shards (sorted by their min_deadline, i.e
+   * the deadline of the next timer in each shard). */
+  const std::unique_ptr<Shard*[]> shard_queue_ ABSL_GUARDED_BY(mu_);
+};
+
+}  // namespace iomgr_engine
+}  // namespace grpc_event_engine
+
+#endif /* GRPC_CORE_LIB_EVENT_ENGINE_IOMGR_ENGINE_TIMER_H */

data/src/core/lib/event_engine/iomgr_engine/timer_heap.cc

@@ -0,0 +1,107 @@
+/*
+ *
+ * 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.
+ *
+ */
+
+#include <grpc/support/port_platform.h>
+
+#include "src/core/lib/event_engine/iomgr_engine/timer_heap.h"
+
+#include <stdint.h>
+
+#include <algorithm>
+
+#include "src/core/lib/event_engine/iomgr_engine/timer.h"
+
+namespace grpc_event_engine {
+namespace iomgr_engine {
+
+/* Adjusts a heap so as to move a hole at position i closer to the root,
+   until a suitable position is found for element t. Then, copies t into that
+   position. This functor is called each time immediately after modifying a
+   value in the underlying container, with the offset of the modified element as
+   its argument. */
+void TimerHeap::AdjustUpwards(size_t i, Timer* t) {
+  while (i > 0) {
+    size_t parent = (i - 1) / 2;
+    if (timers_[parent]->deadline <= t->deadline) break;
+    timers_[i] = timers_[parent];
+    timers_[i]->heap_index = i;
+    i = parent;
+  }
+  timers_[i] = t;
+  t->heap_index = i;
+}
+
+/* Adjusts a heap so as to move a hole at position i farther away from the root,
+   until a suitable position is found for element t.  Then, copies t into that
+   position. */
+void TimerHeap::AdjustDownwards(size_t i, Timer* t) {
+  for (;;) {
+    size_t left_child = 1 + 2 * i;
+    if (left_child >= timers_.size()) break;
+    size_t right_child = left_child + 1;
+    size_t next_i =
+        right_child < timers_.size() &&
+                timers_[left_child]->deadline > timers_[right_child]->deadline
+            ? right_child
+            : left_child;
+    if (t->deadline <= timers_[next_i]->deadline) break;
+    timers_[i] = timers_[next_i];
+    timers_[i]->heap_index = i;
+    i = next_i;
+  }
+  timers_[i] = t;
+  t->heap_index = i;
+}
+
+void TimerHeap::NoteChangedPriority(Timer* timer) {
+  uint32_t i = timer->heap_index;
+  uint32_t parent = static_cast<uint32_t>((static_cast<int>(i) - 1) / 2);
+  if (timers_[parent]->deadline > timer->deadline) {
+    AdjustUpwards(i, timer);
+  } else {
+    AdjustDownwards(i, timer);
+  }
+}
+
+bool TimerHeap::Add(Timer* timer) {
+  timer->heap_index = timers_.size();
+  timers_.push_back(timer);
+  AdjustUpwards(timer->heap_index, timer);
+  return timer->heap_index == 0;
+}
+
+void TimerHeap::Remove(Timer* timer) {
+  uint32_t i = timer->heap_index;
+  if (i == timers_.size() - 1) {
+    timers_.pop_back();
+    return;
+  }
+  timers_[i] = timers_[timers_.size() - 1];
+  timers_[i]->heap_index = i;
+  timers_.pop_back();
+  NoteChangedPriority(timers_[i]);
+}
+
+bool TimerHeap::is_empty() { return timers_.empty(); }
+
+Timer* TimerHeap::Top() { return timers_[0]; }
+
+void TimerHeap::Pop() { Remove(Top()); }
+
+}  // namespace iomgr_engine
+}  // namespace grpc_event_engine

data/src/core/lib/event_engine/iomgr_engine/timer_heap.h

@@ -0,0 +1,56 @@
+/*
+ *
+ * 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_LIB_EVENT_ENGINE_IOMGR_ENGINE_TIMER_HEAP_H
+#define GRPC_CORE_LIB_EVENT_ENGINE_IOMGR_ENGINE_TIMER_HEAP_H
+
+#include <grpc/support/port_platform.h>
+
+#include <cstddef>
+#include <vector>
+
+namespace grpc_event_engine {
+namespace iomgr_engine {
+
+struct Timer;
+
+class TimerHeap {
+ public:
+  /* return true if the new timer is the first timer in the heap */
+  bool Add(Timer* timer);
+
+  void Remove(Timer* timer);
+  Timer* Top();
+  void Pop();
+
+  bool is_empty();
+
+  const std::vector<Timer*>& TestOnlyGetTimers() const { return timers_; }
+
+ private:
+  void AdjustUpwards(size_t i, Timer* t);
+  void AdjustDownwards(size_t i, Timer* t);
+  void NoteChangedPriority(Timer* timer);
+
+  std::vector<Timer*> timers_;
+};
+
+}  // namespace iomgr_engine
+}  // namespace grpc_event_engine
+
+#endif /* GRPC_CORE_LIB_EVENT_ENGINE_IOMGR_ENGINE_TIMER_HEAP_H */