GRPC C++
1.39.1
|
The EventEngine encapsulates all platform-specific behaviors related to low level network I/O, timers, asynchronous execution, and DNS resolution. More...
#include <event_engine.h>
Data Structures | |
class | DNSResolver |
The DNSResolver that provides asynchronous resolution. More... | |
class | Endpoint |
An Endpoint represents one end of a connection between a gRPC client and server. More... | |
class | Listener |
An EventEngine Listener listens for incoming connection requests from gRPC clients and initiates request processing once connections are established. More... | |
class | ResolvedAddress |
A thin wrapper around a platform-specific sockaddr type. More... | |
struct | RunOptions |
Intended for future expansion of Task run functionality. More... | |
struct | TaskHandle |
A callback handle, used to cancel a callback. More... | |
Public Types | |
using | Callback = std::function< void(absl::Status)> |
A basic callable function. More... | |
using | OnConnectCallback = std::function< void(absl::StatusOr< std::unique_ptr< Endpoint > >)> |
Called when a new connection is established. More... | |
Public Member Functions | |
virtual absl::StatusOr< std::unique_ptr< Listener > > | CreateListener (Listener::AcceptCallback on_accept, Callback on_shutdown, const EndpointConfig &args, SliceAllocatorFactory slice_allocator_factory)=0 |
Factory method to create a network listener / server. More... | |
virtual absl::Status | Connect (OnConnectCallback on_connect, const ResolvedAddress &addr, const EndpointConfig &args, SliceAllocator slice_allocator, absl::Time deadline)=0 |
Creates a client network connection to a remote network listener. More... | |
virtual | ~EventEngine ()=default |
virtual bool | IsWorkerThread ()=0 |
virtual absl::StatusOr< std::unique_ptr< DNSResolver > > | GetDNSResolver ()=0 |
Retrieves an instance of a DNSResolver. More... | |
virtual TaskHandle | Run (Callback fn, RunOptions opts)=0 |
Run a callback as soon as possible. More... | |
virtual TaskHandle | RunAt (absl::Time when, Callback fn, RunOptions opts)=0 |
Synonymous with scheduling an alarm to run at time when. More... | |
virtual void | TryCancel (TaskHandle handle)=0 |
Immediately tries to cancel a callback. More... | |
virtual void | Shutdown (Callback on_shutdown_complete)=0 |
Immediately run all callbacks with status indicating the shutdown. More... | |
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();
using grpc_event_engine::experimental::EventEngine::Callback = std::function<void(absl::Status)> |
A basic callable function.
The first argument to all callbacks is an absl::Status indicating the status of the operation associated with this callback. Each EventEngine method that takes a callback parameter, defines the expected sets and meanings of statuses for that use case.
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.
|
virtualdefault |
|
pure virtual |
Creates a client network connection to a remote network listener.
Connect may return an error status immediately if there was a failure in the synchronous part of establishing a connection. In that event, the on_connect callback will not have been executed. Otherwise, it is expected that the on_connect callback will be asynchronously executed exactly once by the EventEngine.
Implementation Note: it is important that the slice_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 SliceAllocator API for more information.
|
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. Note that unlike other callbacks, there is no status code parameter since the callback will only be called in healthy scenarios where connections can be accepted.
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 SliceAllocatorFactory is used to create SliceAllocators for Endpoint construction.
|
pure virtual |
Retrieves an instance of a DNSResolver.
|
pure virtual |
|
pure virtual |
Run a callback as soon as possible.
The fn callback's status argument is used to indicate whether it was executed normally. For example, the status may be CANCELLED if TryCancel was called, or if the EventEngine is being shut down.
|
pure virtual |
Synonymous with scheduling an alarm to run at time when.
The callback fn will execute when either when time when arrives (receiving status OK), or when the fn is cancelled (reveiving status CANCELLED). The callback is guaranteed to be called exactly once.
|
pure virtual |
Immediately run all callbacks with status indicating the shutdown.
Every EventEngine is expected to shut down exactly once. No new callbacks/tasks should be scheduled after shutdown has begun, no new connections should be created.
If the on_shutdown_complete callback is given a non-OK status, errors are expected to be unrecoverable. For example, an implementation could warn callers about leaks if memory cannot be freed within a certain timeframe.
|
pure virtual |
Immediately tries to cancel a callback.
Note that this is a "best effort" cancellation. No guarantee is made that the callback will be cancelled, the call could be in any stage.
There are three scenarios in which we may cancel a scheduled function:
In all cases, the cancellation is still considered successful, the callback will be run exactly once from either cancellation or from its activation.