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'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 GetDefaultEventEngine( grpc_core::SourceLocation location = grpc_core::SourceLocation());