1 // Copyright 2021 The gRPC Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef GRPC_SRC_CORE_LIB_EVENT_ENGINE_DEFAULT_EVENT_ENGINE_H 16 #define GRPC_SRC_CORE_LIB_EVENT_ENGINE_DEFAULT_EVENT_ENGINE_H 17 18 #include <grpc/event_engine/event_engine.h> 19 #include <grpc/support/port_platform.h> 20 21 #include <memory> 22 23 #include "src/core/config/core_configuration.h" 24 #include "src/core/util/debug_location.h" 25 26 namespace grpc_event_engine { 27 namespace experimental { 28 29 /// Access the shared global EventEngine instance. 30 /// 31 /// GetDefaultEventEngine is a lazy thing: either a shared global EventEngine 32 /// instance exists and will be returned, or that shared global instance will be 33 /// created and returned. The returned shared_ptr<EventEngine>'s life is 34 /// determined by the shared_ptr, and therefore EventEngines may be created and 35 /// destroyed multiple times through the life of your gRPC process, there is no 36 /// guarantee of one persistent global instance like in iomgr. 37 /// 38 /// Why would we do this? To begin with, users may provide their own EventEngine 39 /// instances on channel or server creation; if they do that, there is some 40 /// chance that a default EventEngine instance will not have to be created, and 41 /// applications will not have to pay the (probably small) price of 42 /// instantiating an engine they do not own. The other major consideration is 43 /// that gRPC shutdown is likely going away. Without a well-defined point at 44 /// which a persistent global EventEngine instance can safely be shut down, we 45 /// risk undefined behavior and various documented breakages if the engine is 46 /// not shut down cleanly before the process exits. Therefore, allowing the 47 /// EventEngine lifetimes to be determined by the scopes in which they are 48 /// needed is a fine solution. 49 /// 50 /// If you're writing code that needs an EventEngine, prefer 1) getting the 51 /// EventEngine from somewhere it is already cached - preconditioned 52 /// ChannelArgs, or the channel stack for example - or 2) if not otherwise 53 /// available, call \a GetDefaultEventEngine and save that shared_ptr to ensure 54 /// the Engine's lifetime is at least as long as you need it to be. 55 std::shared_ptr<EventEngine> GetDefaultEventEngine( 56 grpc_core::SourceLocation location = grpc_core::SourceLocation()); 57 58 /// On ingress, ensure that an EventEngine exists in channel args via 59 /// preconditioning. 60 void RegisterEventEngineChannelArgPreconditioning( 61 grpc_core::CoreConfiguration::Builder* builder); 62 63 } // namespace experimental 64 } // namespace grpc_event_engine 65 66 #endif // GRPC_SRC_CORE_LIB_EVENT_ENGINE_DEFAULT_EVENT_ENGINE_H 67