#include <event_engine.h>
Classes | |
| class | Closure |
| struct | ConnectionHandle |
| class | DNSResolver |
| Provides asynchronous resolution. More... | |
| class | Endpoint |
| class | Listener |
| class | ResolvedAddress |
| struct | TaskHandle |
Public Types | |
| using | Duration = std::chrono::duration< int64_t, std::nano > |
| using | OnConnectCallback = std::function< void(absl::StatusOr< std::unique_ptr< Endpoint > >)> |
Public Member Functions | |
| virtual bool | Cancel (TaskHandle handle)=0 |
| virtual bool | CancelConnect (ConnectionHandle handle)=0 |
| virtual ConnectionHandle | Connect (OnConnectCallback on_connect, const ResolvedAddress &addr, const EndpointConfig &args, MemoryAllocator memory_allocator, Duration timeout)=0 |
| virtual absl::StatusOr< std::unique_ptr< Listener > > | CreateListener (Listener::AcceptCallback on_accept, std::function< void(absl::Status)> on_shutdown, const EndpointConfig &config, std::unique_ptr< MemoryAllocatorFactory > memory_allocator_factory)=0 |
| virtual std::unique_ptr< DNSResolver > | GetDNSResolver (const DNSResolver::ResolverOptions &options)=0 |
| virtual bool | IsWorkerThread ()=0 |
| virtual void | Run (Closure *closure)=0 |
| virtual void | Run (std::function< void()> closure)=0 |
| virtual TaskHandle | RunAfter (Duration when, Closure *closure)=0 |
| virtual TaskHandle | RunAfter (Duration when, std::function< void()> closure)=0 |
| virtual | ~EventEngine ()=default |
Detailed Description
The EventEngine encapsulates all platform-specific behaviors related to low level network I/O, timers, asynchronous execution, and DNS resolution.
This interface allows developers to provide their own event management and network stacks. Motivating uses cases for supporting custom EventEngines include the ability to hook into external event loops, and using different EventEngine instances for each channel to better insulate network I/O and callback processing from other channels.
A default cross-platform EventEngine instance is provided by gRPC.
LIFESPAN AND OWNERSHIP
gRPC takes shared ownership of EventEngines via std::shared_ptrs to ensure that the engines remain available until they are no longer needed. Depending on the use case, engines may live until gRPC is shut down.
EXAMPLE USAGE (Not yet implemented)
Custom EventEngines can be specified per channel, and allow configuration for both clients and servers. To set a custom EventEngine for a client channel, you can do something like the following:
ChannelArguments args; std::shared_ptr<EventEngine> engine = std::make_shared<MyEngine>(...); args.SetEventEngine(engine); MyAppClient client(grpc::CreateCustomChannel( "localhost:50051", grpc::InsecureChannelCredentials(), args));
A gRPC server can use a custom EventEngine by calling the ServerBuilder::SetEventEngine method:
ServerBuilder builder; std::shared_ptr<EventEngine> engine = std::make_shared<MyEngine>(...); builder.SetEventEngine(engine); std::unique_ptr<Server> server(builder.BuildAndStart()); server->Wait();
Definition at line 74 of file event_engine.h.
Member Typedef Documentation
◆ Duration
| using grpc_event_engine::experimental::EventEngine::Duration = std::chrono::duration<int64_t, std::nano> |
A duration between two events.
Throughout the EventEngine API durations are used to express how long until an action should be performed.
Definition at line 80 of file event_engine.h.
◆ OnConnectCallback
| using grpc_event_engine::experimental::EventEngine::OnConnectCallback = std::function<void(absl::StatusOr<std::unique_ptr<Endpoint> >)> |
Called when a new connection is established.
If the connection attempt was not successful, implementations should pass the appropriate statuses to this callback. For example, callbacks might expect to receive DEADLINE_EXCEEDED statuses when appropriate, or CANCELLED statuses on EventEngine shutdown.
Definition at line 224 of file event_engine.h.
Constructor & Destructor Documentation
◆ ~EventEngine()
|
virtualdefault |
At time of destruction, the EventEngine must have no active responsibilities. EventEngine users (applications) are responsible for cancelling all tasks and DNS lookups, shutting down listeners and endpoints, prior to EventEngine destruction. If there are any outstanding tasks, any running listeners, etc. at time of EventEngine destruction, that is an invalid use of the API, and it will result in undefined behavior.
Member Function Documentation
◆ Cancel()
|
pure virtual |
Request cancellation of a task.
If the associated closure has already been scheduled to run, it will not be cancelled, and this function will return false.
If the associated callback has not been scheduled to run, it will be cancelled, and the associated std::function or Closure* will not be executed. In this case, Cancel will return true.
Implementation note: closures should be destroyed in a timely manner after execution or cancelliation (milliseconds), since any state bound to the closure may need to be destroyed for things to progress (e.g., if a closure holds a ref to some ref-counted object).
Implemented in grpc_event_engine::experimental::PosixOracleEventEngine, grpc_event_engine::experimental::IomgrEventEngine, and grpc_event_engine::experimental::FuzzingEventEngine.
◆ CancelConnect()
|
pure virtual |
Request cancellation of a connection attempt.
If the associated connection has already been completed, it will not be cancelled, and this method will return false.
If the associated connection has not been completed, it will be cancelled, and this method will return true. The OnConnectCallback will not be called.
Implemented in grpc_event_engine::experimental::PosixOracleEventEngine, grpc_event_engine::experimental::IomgrEventEngine, and grpc_event_engine::experimental::FuzzingEventEngine.
◆ Connect()
|
pure virtual |
Creates a client network connection to a remote network listener.
Even in the event of an error, it is expected that the on_connect callback will be asynchronously executed exactly once by the EventEngine. A connection attempt can be cancelled using the CancelConnect method.
Implementation Note: it is important that the memory_allocator be used for all read/write buffer allocations in the EventEngine implementation. This allows gRPC's ResourceQuota system to monitor and control memory usage with graceful degradation mechanisms. Please see the MemoryAllocator API for more information.
Implemented in grpc_event_engine::experimental::IomgrEventEngine, and grpc_event_engine::experimental::FuzzingEventEngine.
◆ CreateListener()
|
pure virtual |
Factory method to create a network listener / server.
Once a Listener is created and started, the on_accept callback will be called once asynchronously for each established connection. This method may return a non-OK status immediately if an error was encountered in any synchronous steps required to create the Listener. In this case, on_shutdown will never be called.
If this method returns a Listener, then on_shutdown will be invoked exactly once, when the Listener is shut down. The status passed to it will indicate if there was a problem during shutdown.
The provided MemoryAllocatorFactory is used to create MemoryAllocators for Endpoint construction.
Implemented in grpc_event_engine::experimental::IomgrEventEngine, grpc_event_engine::experimental::FuzzingEventEngine, and grpc_event_engine::experimental::PosixOracleEventEngine.
◆ GetDNSResolver()
|
pure virtual |
Creates and returns an instance of a DNSResolver, optionally configured by the options struct.
◆ IsWorkerThread()
|
pure virtual |
◆ Run() [1/2]
|
pure virtual |
Asynchronously executes a task as soon as possible.
Closures scheduled with Run cannot be cancelled. The closure will not be deleted after it has been run, ownership remains with the caller.
Implemented in grpc_event_engine::experimental::IomgrEventEngine, grpc_event_engine::experimental::FuzzingEventEngine, and grpc_event_engine::experimental::PosixOracleEventEngine.
◆ Run() [2/2]
|
pure virtual |
Asynchronously executes a task as soon as possible.
Closures scheduled with Run cannot be cancelled. Unlike the overloaded Closure alternative, the std::function version's closure will be deleted by the EventEngine after the closure has been run.
This version of Run may be less performant than the Closure version in some scenarios. This overload is useful in situations where performance is not a critical concern.
Implemented in grpc_event_engine::experimental::PosixOracleEventEngine, grpc_event_engine::experimental::IomgrEventEngine, and grpc_event_engine::experimental::FuzzingEventEngine.
◆ RunAfter() [1/2]
|
pure virtual |
Synonymous with scheduling an alarm to run after duration when.
The closure will execute when time when arrives unless it has been cancelled via the Cancel method. If cancelled, the closure will not be run, nor will it be deleted. Ownership remains with the caller.
Implemented in grpc_event_engine::experimental::IomgrEventEngine, and grpc_event_engine::experimental::FuzzingEventEngine.
◆ RunAfter() [2/2]
|
pure virtual |
Synonymous with scheduling an alarm to run after duration when.
The closure will execute when time when arrives unless it has been cancelled via the Cancel method. If cancelled, the closure will not be run. Unilke the overloaded Closure alternative, the std::function version's closure will be deleted by the EventEngine after the closure has been run, or upon cancellation.
This version of RunAfter may be less performant than the Closure version in some scenarios. This overload is useful in situations where performance is not a critical concern.
Implemented in grpc_event_engine::experimental::IomgrEventEngine, and grpc_event_engine::experimental::FuzzingEventEngine.
The documentation for this class was generated from the following file: