grpc 1.45.0 → 1.53.0

data/src/core/lib/iomgr/event_engine_shims/tcp_client.h

@@ -0,0 +1,44 @@
+// Copyright 2022 The 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_SRC_CORE_LIB_IOMGR_EVENT_ENGINE_SHIMS_TCP_CLIENT_H
+#define GRPC_SRC_CORE_LIB_IOMGR_EVENT_ENGINE_SHIMS_TCP_CLIENT_H
+#include <grpc/support/port_platform.h>
+
+#include <grpc/event_engine/event_engine.h>
+
+#include "src/core/lib/iomgr/endpoint.h"
+#include "src/core/lib/iomgr/resolved_address.h"
+
+namespace grpc_event_engine {
+namespace experimental {
+
+/// Attempts to use event engine to connect to the specified remote address and
+/// invokes the on_connect callback asynchronously upon connection
+/// establishment, failure or timeout. It returns a 64 bit connection handle
+/// which can later be used to cancel an in progress connection attempt.
+int64_t event_engine_tcp_client_connect(grpc_closure* on_connect,
+                                        grpc_endpoint** endpoint,
+                                        const EndpointConfig& config,
+                                        const grpc_resolved_address* addr,
+                                        grpc_core::Timestamp deadline);
+
+/// Attempts to cancel an in progress connection attempt represented by the
+/// passed in connection handle. It returns true if the cancellation attempt
+/// succeeded. Otherwise it returns false.
+bool event_engine_tcp_client_cancel_connect(int64_t connection_handle);
+
+}  // namespace experimental
+}  // namespace grpc_event_engine
+
+#endif  // GRPC_SRC_CORE_LIB_IOMGR_EVENT_ENGINE_SHIMS_TCP_CLIENT_H

data/src/core/lib/iomgr/exec_ctx.cc

@@ -1,31 +1,33 @@
-/*
- *
- * 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.
- *
- */
+//
+//
+// 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/iomgr/exec_ctx.h"
 
+#include "absl/strings/str_format.h"
+
 #include <grpc/support/log.h>
 #include <grpc/support/sync.h>
 
+#include "src/core/lib/gprpp/crash.h"
 #include "src/core/lib/iomgr/combiner.h"
 #include "src/core/lib/iomgr/error.h"
-#include "src/core/lib/profiling/timers.h"
 
 static void exec_ctx_run(grpc_closure* closure) {
 #ifndef NDEBUG
@@ -37,18 +39,10 @@ static void exec_ctx_run(grpc_closure* closure) {
             closure->line_initiated);
   }
 #endif
-#ifdef GRPC_ERROR_IS_ABSEIL_STATUS
   grpc_error_handle error =
       grpc_core::internal::StatusMoveFromHeapPtr(closure->error_data.error);
   closure->error_data.error = 0;
   closure->cb(closure->cb_arg, std::move(error));
-#else
-  grpc_error_handle error =
-      reinterpret_cast<grpc_error_handle>(closure->error_data.error);
-  closure->error_data.error = 0;
-  closure->cb(closure->cb_arg, error);
-  GRPC_ERROR_UNREF(error);
-#endif
 #ifndef NDEBUG
   if (grpc_trace_closure.enabled()) {
     gpr_log(GPR_DEBUG, "closure %p finished", closure);
@@ -62,13 +56,12 @@ static void exec_ctx_sched(grpc_closure* closure) {
 
 namespace grpc_core {
 
-GPR_THREAD_LOCAL(ExecCtx*) ExecCtx::exec_ctx_;
-GPR_THREAD_LOCAL(ApplicationCallbackExecCtx*)
-ApplicationCallbackExecCtx::callback_exec_ctx_;
+thread_local ExecCtx* ExecCtx::exec_ctx_;
+thread_local ApplicationCallbackExecCtx*
+    ApplicationCallbackExecCtx::callback_exec_ctx_;
 
 bool ExecCtx::Flush() {
   bool did_something = false;
-  GPR_TIMER_SCOPE("grpc_exec_ctx_flush", 0);
   for (;;) {
     if (!grpc_closure_list_empty(closure_list_)) {
       grpc_closure* c = closure_list_.head;
@@ -87,30 +80,20 @@ bool ExecCtx::Flush() {
   return did_something;
 }
 
-Timestamp ExecCtx::Now() {
-  if (!now_is_valid_) {
-    now_ = Timestamp::FromTimespecRoundDown(gpr_now(GPR_CLOCK_MONOTONIC));
-    now_is_valid_ = true;
-  }
-  return now_;
-}
-
 void ExecCtx::Run(const DebugLocation& location, grpc_closure* closure,
                   grpc_error_handle error) {
   (void)location;
   if (closure == nullptr) {
-    GRPC_ERROR_UNREF(error);
     return;
   }
 #ifndef NDEBUG
   if (closure->scheduled) {
-    gpr_log(GPR_ERROR,
-            "Closure already scheduled. (closure: %p, created: [%s:%d], "
-            "previously scheduled at: [%s: %d], newly scheduled at [%s: %d]",
-            closure, closure->file_created, closure->line_created,
-            closure->file_initiated, closure->line_initiated, location.file(),
-            location.line());
-    abort();
+    Crash(absl::StrFormat(
+        "Closure already scheduled. (closure: %p, created: [%s:%d], "
+        "previously scheduled at: [%s: %d], newly scheduled at [%s: %d]",
+        closure, closure->file_created, closure->line_created,
+        closure->file_initiated, closure->line_initiated, location.file(),
+        location.line()));
   }
   closure->scheduled = true;
   closure->file_initiated = location.file();
@@ -118,11 +101,7 @@ void ExecCtx::Run(const DebugLocation& location, grpc_closure* closure,
   closure->run = false;
   GPR_ASSERT(closure->cb != nullptr);
 #endif
-#ifdef GRPC_ERROR_IS_ABSEIL_STATUS
   closure->error_data.error = internal::StatusAllocHeapPtr(error);
-#else
-  closure->error_data.error = reinterpret_cast<intptr_t>(error);
-#endif
   exec_ctx_sched(closure);
 }
 
@@ -133,12 +112,11 @@ void ExecCtx::RunList(const DebugLocation& location, grpc_closure_list* list) {
     grpc_closure* next = c->next_data.next;
 #ifndef NDEBUG
     if (c->scheduled) {
-      gpr_log(GPR_ERROR,
-              "Closure already scheduled. (closure: %p, created: [%s:%d], "
-              "previously scheduled at: [%s: %d], newly scheduled at [%s:%d]",
-              c, c->file_created, c->line_created, c->file_initiated,
-              c->line_initiated, location.file(), location.line());
-      abort();
+      Crash(absl::StrFormat(
+          "Closure already scheduled. (closure: %p, created: [%s:%d], "
+          "previously scheduled at: [%s: %d], newly scheduled at [%s:%d]",
+          c, c->file_created, c->line_created, c->file_initiated,
+          c->line_initiated, location.file(), location.line()));
     }
     c->scheduled = true;
     c->file_initiated = location.file();

data/src/core/lib/iomgr/exec_ctx.h

@@ -1,109 +1,109 @@
-/*
- *
- * 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_IOMGR_EXEC_CTX_H
-#define GRPC_CORE_LIB_IOMGR_EXEC_CTX_H
+//
+//
+// 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_SRC_CORE_LIB_IOMGR_EXEC_CTX_H
+#define GRPC_SRC_CORE_LIB_IOMGR_EXEC_CTX_H
 
 #include <grpc/support/port_platform.h>
 
 #include <limits>
 
-#include <grpc/impl/codegen/gpr_types.h>
-#include <grpc/impl/codegen/grpc_types.h>
+#include <grpc/impl/grpc_types.h>
 #include <grpc/support/atm.h>
 #include <grpc/support/cpu.h>
 #include <grpc/support/log.h>
+#include <grpc/support/time.h>
 
 #include "src/core/lib/gpr/time_precise.h"
-#include "src/core/lib/gpr/tls.h"
+#include "src/core/lib/gprpp/crash.h"
 #include "src/core/lib/gprpp/debug_location.h"
 #include "src/core/lib/gprpp/fork.h"
 #include "src/core/lib/gprpp/time.h"
 #include "src/core/lib/iomgr/closure.h"
 
-/** A combiner represents a list of work to be executed later.
-    Forward declared here to avoid a circular dependency with combiner.h. */
+/// A combiner represents a list of work to be executed later.
+/// Forward declared here to avoid a circular dependency with combiner.h.
 typedef struct grpc_combiner grpc_combiner;
 
-/* This exec_ctx is ready to return: either pre-populated, or cached as soon as
-   the finish_check returns true */
+// This exec_ctx is ready to return: either pre-populated, or cached as soon as
+// the finish_check returns true
 #define GRPC_EXEC_CTX_FLAG_IS_FINISHED 1
-/* The exec_ctx's thread is (potentially) owned by a call or channel: care
-   should be given to not delete said call/channel from this exec_ctx */
+// The exec_ctx's thread is (potentially) owned by a call or channel: care
+// should be given to not delete said call/channel from this exec_ctx
 #define GRPC_EXEC_CTX_FLAG_THREAD_RESOURCE_LOOP 2
-/* This exec ctx was initialized by an internal thread, and should not
-   be counted by fork handlers */
+// This exec ctx was initialized by an internal thread, and should not
+// be counted by fork handlers
 #define GRPC_EXEC_CTX_FLAG_IS_INTERNAL_THREAD 4
 
-/* This application callback exec ctx was initialized by an internal thread, and
-   should not be counted by fork handlers */
+// This application callback exec ctx was initialized by an internal thread, and
+// should not be counted by fork handlers
 #define GRPC_APP_CALLBACK_EXEC_CTX_FLAG_IS_INTERNAL_THREAD 1
 
 namespace grpc_core {
 class Combiner;
-/** Execution context.
- *  A bag of data that collects information along a callstack.
- *  It is created on the stack at core entry points (public API or iomgr), and
- *  stored internally as a thread-local variable.
- *
- *  Generally, to create an exec_ctx instance, add the following line at the top
- *  of the public API entry point or at the start of a thread's work function :
- *
- *  ExecCtx exec_ctx;
- *
- *  Access the created ExecCtx instance using :
- *  ExecCtx::Get()
- *
- *  Specific responsibilities (this may grow in the future):
- *  - track a list of core work that needs to be delayed until the base of the
- *    call stack (this provides a convenient mechanism to run callbacks
- *    without worrying about locking issues)
- *  - provide a decision maker (via IsReadyToFinish) that provides a
- *    signal as to whether a borrowed thread should continue to do work or
- *    should actively try to finish up and get this thread back to its owner
- *
- *  CONVENTIONS:
- *  - Instance of this must ALWAYS be constructed on the stack, never
- *    heap allocated.
- *  - Do not pass exec_ctx as a parameter to a function. Always access it using
- *    ExecCtx::Get().
- *  - NOTE: In the future, the convention is likely to change to allow only one
- *          ExecCtx on a thread's stack at the same time. The TODO below
- *          discusses this plan in more detail.
- *
- * TODO(yashykt): Only allow one "active" ExecCtx on a thread at the same time.
- *                Stage 1: If a new one is created on the stack, it should just
- *                pass-through to the underlying ExecCtx deeper in the thread's
- *                stack.
- *                Stage 2: Assert if a 2nd one is ever created on the stack
- *                since that implies a core re-entry outside of application
- *                callbacks.
- */
+/// Execution context.
+/// A bag of data that collects information along a callstack.
+/// It is created on the stack at core entry points (public API or iomgr), and
+/// stored internally as a thread-local variable.
+///
+/// Generally, to create an exec_ctx instance, add the following line at the top
+/// of the public API entry point or at the start of a thread's work function :
+///
+/// ExecCtx exec_ctx;
+///
+/// Access the created ExecCtx instance using :
+/// ExecCtx::Get()
+///
+/// Specific responsibilities (this may grow in the future):
+/// - track a list of core work that needs to be delayed until the base of the
+///   call stack (this provides a convenient mechanism to run callbacks
+///   without worrying about locking issues)
+/// - provide a decision maker (via IsReadyToFinish) that provides a
+///   signal as to whether a borrowed thread should continue to do work or
+///   should actively try to finish up and get this thread back to its owner
+///
+/// CONVENTIONS:
+/// - Instance of this must ALWAYS be constructed on the stack, never
+///   heap allocated.
+/// - Do not pass exec_ctx as a parameter to a function. Always access it using
+///   ExecCtx::Get().
+/// - NOTE: In the future, the convention is likely to change to allow only one
+///         ExecCtx on a thread's stack at the same time. The TODO below
+///         discusses this plan in more detail.
+///
+/// TODO(yashykt): Only allow one "active" ExecCtx on a thread at the same time.
+///               Stage 1: If a new one is created on the stack, it should just
+///               pass-through to the underlying ExecCtx deeper in the thread's
+///               stack.
+///               Stage 2: Assert if a 2nd one is ever created on the stack
+///               since that implies a core re-entry outside of application
+///               callbacks.
+///
 class ExecCtx {
  public:
-  /** Default Constructor */
+  /// Default Constructor
 
   ExecCtx() : flags_(GRPC_EXEC_CTX_FLAG_IS_FINISHED) {
     Fork::IncExecCtxCount();
     Set(this);
   }
 
-  /** Parameterised Constructor */
+  /// Parameterised Constructor
   explicit ExecCtx(uintptr_t fl) : flags_(fl) {
     if (!(GRPC_EXEC_CTX_FLAG_IS_INTERNAL_THREAD & flags_)) {
       Fork::IncExecCtxCount();
@@ -111,7 +111,7 @@ class ExecCtx {
     Set(this);
   }
 
-  /** Destructor */
+  /// Destructor
   virtual ~ExecCtx() {
     flags_ |= GRPC_EXEC_CTX_FLAG_IS_FINISHED;
     Flush();
@@ -121,7 +121,7 @@ class ExecCtx {
     }
   }
 
-  /** Disallow copy and assignment operators */
+  /// Disallow copy and assignment operators
   ExecCtx(const ExecCtx&) = delete;
   ExecCtx& operator=(const ExecCtx&) = delete;
 
@@ -133,37 +133,37 @@ class ExecCtx {
   }
 
   struct CombinerData {
-    /* currently active combiner: updated only via combiner.c */
+    // currently active combiner: updated only via combiner.c
     Combiner* active_combiner;
-    /* last active combiner in the active combiner list */
+    // last active combiner in the active combiner list
     Combiner* last_combiner;
   };
 
-  /** Only to be used by grpc-combiner code */
+  /// Only to be used by grpc-combiner code
   CombinerData* combiner_data() { return &combiner_data_; }
 
-  /** Return pointer to grpc_closure_list */
+  /// Return pointer to grpc_closure_list
   grpc_closure_list* closure_list() { return &closure_list_; }
 
-  /** Return flags */
+  /// Return flags
   uintptr_t flags() { return flags_; }
 
-  /** Checks if there is work to be done */
+  /// Checks if there is work to be done
   bool HasWork() {
     return combiner_data_.active_combiner != nullptr ||
            !grpc_closure_list_empty(closure_list_);
   }
 
-  /** Flush any work that has been enqueued onto this grpc_exec_ctx.
-   *  Caller must guarantee that no interfering locks are held.
-   *  Returns true if work was performed, false otherwise.
-   */
+  /// Flush any work that has been enqueued onto this grpc_exec_ctx.
+  /// Caller must guarantee that no interfering locks are held.
+  /// Returns true if work was performed, false otherwise.
+  ///
   bool Flush();
 
-  /** Returns true if we'd like to leave this execution context as soon as
-   *  possible: useful for deciding whether to do something more or not
-   *  depending on outside context.
-   */
+  /// Returns true if we'd like to leave this execution context as soon as
+  /// possible: useful for deciding whether to do something more or not
+  /// depending on outside context.
+  ///
   bool IsReadyToFinish() {
     if ((flags_ & GRPC_EXEC_CTX_FLAG_IS_FINISHED) == 0) {
       if (CheckReadyToFinish()) {
@@ -176,50 +176,33 @@ class ExecCtx {
     }
   }
 
-  /** Returns the stored current time relative to start if valid,
-   *  otherwise refreshes the stored time, sets it valid and returns the new
-   *  value.
-   */
-  Timestamp Now();
-
-  /** Invalidates the stored time value. A new time value will be set on calling
-   *  Now().
-   */
-  void InvalidateNow() { now_is_valid_ = false; }
-
-  /** To be used only by shutdown code in iomgr */
+  Timestamp Now() { return Timestamp::Now(); }
+  void InvalidateNow() { time_cache_.InvalidateCache(); }
   void SetNowIomgrShutdown() {
-    now_ = Timestamp::InfFuture();
-    now_is_valid_ = true;
+    // We get to do a test only set now on this path just because iomgr
+    // is getting removed and no point adding more interfaces for it.
+    time_cache_.TestOnlySetNow(Timestamp::InfFuture());
   }
+  void TestOnlySetNow(Timestamp now) { time_cache_.TestOnlySetNow(now); }
 
-  /** To be used only for testing.
-   *  Sets the now value.
-   */
-  void TestOnlySetNow(Timestamp new_val) {
-    now_ = new_val;
-    now_is_valid_ = true;
-  }
-
-  /** Gets pointer to current exec_ctx. */
+  /// Gets pointer to current exec_ctx.
   static ExecCtx* Get() { return exec_ctx_; }
 
-  static void Set(ExecCtx* exec_ctx) { exec_ctx_ = exec_ctx; }
-
   static void Run(const DebugLocation& location, grpc_closure* closure,
                   grpc_error_handle error);
 
   static void RunList(const DebugLocation& location, grpc_closure_list* list);
 
  protected:
-  /** Check if ready to finish. */
+  /// Check if ready to finish.
   virtual bool CheckReadyToFinish() { return false; }
 
-  /** Disallow delete on ExecCtx. */
+  /// Disallow delete on ExecCtx.
   static void operator delete(void* /* p */) { abort(); }
 
  private:
-  /** Set exec_ctx_ to exec_ctx. */
+  /// Set exec_ctx_ to exec_ctx.
+  static void Set(ExecCtx* exec_ctx) { exec_ctx_ = exec_ctx; }
 
   grpc_closure_list closure_list_ = GRPC_CLOSURE_LIST_INIT;
   CombinerData combiner_data_ = {nullptr, nullptr};
@@ -227,66 +210,64 @@ class ExecCtx {
 
   unsigned starting_cpu_ = std::numeric_limits<unsigned>::max();
 
-  bool now_is_valid_ = false;
-  Timestamp now_;
-
-  static GPR_THREAD_LOCAL(ExecCtx*) exec_ctx_;
+  ScopedTimeCache time_cache_;
+  static thread_local ExecCtx* exec_ctx_;
   ExecCtx* last_exec_ctx_ = Get();
 };
 
-/** Application-callback execution context.
- *  A bag of data that collects information along a callstack.
- *  It is created on the stack at core entry points, and stored internally
- *  as a thread-local variable.
- *
- *  There are three key differences between this structure and ExecCtx:
- *    1. ApplicationCallbackExecCtx builds a list of application-level
- *       callbacks, but ExecCtx builds a list of internal callbacks to invoke.
- *    2. ApplicationCallbackExecCtx invokes its callbacks only at destruction;
- *       there is no explicit Flush method.
- *    3. If more than one ApplicationCallbackExecCtx is created on the thread's
- *       stack, only the one closest to the base of the stack is actually
- *       active and this is the only one that enqueues application callbacks.
- *       (Unlike ExecCtx, it is not feasible to prevent multiple of these on the
- *       stack since the executing application callback may itself enter core.
- *       However, the new one created will just pass callbacks through to the
- *       base one and those will not be executed until the return to the
- *       destructor of the base one, preventing unlimited stack growth.)
- *
- *  This structure exists because application callbacks may themselves cause a
- *  core re-entry (e.g., through a public API call) and if that call in turn
- *  causes another application-callback, there could be arbitrarily growing
- *  stacks of core re-entries. Instead, any application callbacks instead should
- *  not be invoked until other core work is done and other application callbacks
- *  have completed. To accomplish this, any application callback should be
- *  enqueued using ApplicationCallbackExecCtx::Enqueue .
- *
- *  CONVENTIONS:
- *  - Instances of this must ALWAYS be constructed on the stack, never
- *    heap allocated.
- *  - Instances of this are generally constructed before ExecCtx when needed.
- *    The only exception is for ExecCtx's that are explicitly flushed and
- *    that survive beyond the scope of the function that can cause application
- *    callbacks to be invoked (e.g., in the timer thread).
- *
- *  Generally, core entry points that may trigger application-level callbacks
- *  will have the following declarations:
- *
- *  ApplicationCallbackExecCtx callback_exec_ctx;
- *  ExecCtx exec_ctx;
- *
- *  This ordering is important to make sure that the ApplicationCallbackExecCtx
- *  is destroyed after the ExecCtx (to prevent the re-entry problem described
- *  above, as well as making sure that ExecCtx core callbacks are invoked first)
- *
- */
+/// Application-callback execution context.
+/// A bag of data that collects information along a callstack.
+/// It is created on the stack at core entry points, and stored internally
+/// as a thread-local variable.
+///
+/// There are three key differences between this structure and ExecCtx:
+///   1. ApplicationCallbackExecCtx builds a list of application-level
+///      callbacks, but ExecCtx builds a list of internal callbacks to invoke.
+///   2. ApplicationCallbackExecCtx invokes its callbacks only at destruction;
+///      there is no explicit Flush method.
+///   3. If more than one ApplicationCallbackExecCtx is created on the thread's
+///      stack, only the one closest to the base of the stack is actually
+///      active and this is the only one that enqueues application callbacks.
+///      (Unlike ExecCtx, it is not feasible to prevent multiple of these on the
+///      stack since the executing application callback may itself enter core.
+///      However, the new one created will just pass callbacks through to the
+///      base one and those will not be executed until the return to the
+///      destructor of the base one, preventing unlimited stack growth.)
+///
+/// This structure exists because application callbacks may themselves cause a
+/// core re-entry (e.g., through a public API call) and if that call in turn
+/// causes another application-callback, there could be arbitrarily growing
+/// stacks of core re-entries. Instead, any application callbacks instead should
+/// not be invoked until other core work is done and other application callbacks
+/// have completed. To accomplish this, any application callback should be
+/// enqueued using ApplicationCallbackExecCtx::Enqueue .
+///
+/// CONVENTIONS:
+/// - Instances of this must ALWAYS be constructed on the stack, never
+///   heap allocated.
+/// - Instances of this are generally constructed before ExecCtx when needed.
+///   The only exception is for ExecCtx's that are explicitly flushed and
+///   that survive beyond the scope of the function that can cause application
+///   callbacks to be invoked (e.g., in the timer thread).
+///
+/// Generally, core entry points that may trigger application-level callbacks
+/// will have the following declarations:
+///
+/// ApplicationCallbackExecCtx callback_exec_ctx;
+/// ExecCtx exec_ctx;
+///
+/// This ordering is important to make sure that the ApplicationCallbackExecCtx
+/// is destroyed after the ExecCtx (to prevent the re-entry problem described
+/// above, as well as making sure that ExecCtx core callbacks are invoked first)
+///
+///
 
 class ApplicationCallbackExecCtx {
  public:
-  /** Default Constructor */
+  /// Default Constructor
   ApplicationCallbackExecCtx() { Set(this, flags_); }
 
-  /** Parameterised Constructor */
+  /// Parameterised Constructor
   explicit ApplicationCallbackExecCtx(uintptr_t fl) : flags_(fl) {
     Set(this, flags_);
   }
@@ -339,21 +320,15 @@ class ApplicationCallbackExecCtx {
     ctx->tail_ = functor;
   }
 
-  /** Global initialization for ApplicationCallbackExecCtx. Called by init. */
-  static void GlobalInit(void) {}
-
-  /** Global shutdown for ApplicationCallbackExecCtx. Called by init. */
-  static void GlobalShutdown(void) {}
-
   static bool Available() { return Get() != nullptr; }
 
  private:
   uintptr_t flags_{0u};
   grpc_completion_queue_functor* head_{nullptr};
   grpc_completion_queue_functor* tail_{nullptr};
-  static GPR_THREAD_LOCAL(ApplicationCallbackExecCtx*) callback_exec_ctx_;
+  static thread_local ApplicationCallbackExecCtx* callback_exec_ctx_;
 };
 
 }  // namespace grpc_core
 
-#endif /* GRPC_CORE_LIB_IOMGR_EXEC_CTX_H */
+#endif  // GRPC_SRC_CORE_LIB_IOMGR_EXEC_CTX_H