From 054f3c62e5a9408f7b66922bb6c3026c3cb8ee96 Mon Sep 17 00:00:00 2001
From: AJ Heller <hork@google.com>
Date: Mon, 13 Feb 2023 10:46:00 -0800
Subject: [PATCH] [EventEngine] Elaborate on GetDefaultEventEngine intended
 usage (#32358)

Based on a discussion with @yashykt , I outlined the intended use of
`GetDefaultEventEngine`, with a bit of explanation around why we chose
to make it work the way it does.

<!--

If you know who should review your pull request, please assign it to
that
person, otherwise the pull request would get assigned randomly.

If your pull request is for a specific language, please add the
appropriate
lang label.

-->
---
 .../lib/event_engine/default_event_engine.h   | 26 +++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

diff --git a/src/core/lib/event_engine/default_event_engine.h b/src/core/lib/event_engine/default_event_engine.h
index 341b75a2fcc..0601915e1c0 100644
--- a/src/core/lib/event_engine/default_event_engine.h
+++ b/src/core/lib/event_engine/default_event_engine.h
@@ -35,8 +35,30 @@ namespace experimental {
 
 /// Access the shared global EventEngine instance.
 ///
-/// The concept of a global EventEngine may go away in a post-iomgr world.
-/// Strongly consider whether you could use \a CreateEventEngine instead.
+/// GetDefaultEventEngine is a lazy thing: either a shared global EventEngine
+/// instance exists and will be returned, or that shared global instance will be
+/// created and returned. The returned shared_ptr<EventEngine>'s life is
+/// determined by the shared_ptr, and therefore EventEngines may be created and
+/// destroyed multiple times through the life of your gRPC process, there is no
+/// guarantee of one persistent global instance like in iomgr.
+///
+/// Why would we do this? To begin with, users may provide their own EventEngine
+/// instances on channel or server creation; if they do that, there is some
+/// chance that a default EventEngine instance will not have to be created, and
+/// applications will not have to pay the (probably small) price of
+/// instantiating an engine they do not own. The other major consideration is
+/// that gRPC shutdown is likely going away. Without a well-defined point at
+/// which a persistent global EventEngine instance can safely be shut down, we
+/// risk undefined behavior and various documented breakages if the engine is
+/// not shut down cleanly before the process exits. Therefore, allowing the
+/// EventEngine lifetimes to be determined by the scopes in which they are
+/// needed is a fine solution.
+///
+/// If you're writing code that needs an EventEngine, prefer 1) getting the
+/// EventEngine from somewhere it is already cached - preconditioned
+/// ChannelArgs, or the channel stack for example - or 2) if not otherwise
+/// available, call \a GetDefaultEventEngine and save that shared_ptr to ensure
+/// the Engine's lifetime is at least as long as you need it to be.
 std::shared_ptr<EventEngine> GetDefaultEventEngine(
     grpc_core::SourceLocation location = grpc_core::SourceLocation());