[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.

-->
pull/32364/head
AJ Heller 2 years ago committed by GitHub
parent ea4204bb51
commit 054f3c62e5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
  1. 26
      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());

Loading…
Cancel
Save