GRPC C++  1.39.1
Data Structures | Public Types | Public Member Functions
grpc_event_engine::experimental::EventEngine Class Referenceabstract

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

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();

Member Typedef Documentation

◆ Callback

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.

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

Constructor & Destructor Documentation

◆ ~EventEngine()

virtual grpc_event_engine::experimental::EventEngine::~EventEngine ( )
virtualdefault

Member Function Documentation

◆ Connect()

virtual absl::Status grpc_event_engine::experimental::EventEngine::Connect ( OnConnectCallback  on_connect,
const ResolvedAddress addr,
const EndpointConfig args,
SliceAllocator  slice_allocator,
absl::Time  deadline 
)
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.

◆ CreateListener()

virtual absl::StatusOr<std::unique_ptr<Listener> > grpc_event_engine::experimental::EventEngine::CreateListener ( Listener::AcceptCallback  on_accept,
Callback  on_shutdown,
const EndpointConfig args,
SliceAllocatorFactory  slice_allocator_factory 
)
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.

◆ GetDNSResolver()

virtual absl::StatusOr<std::unique_ptr<DNSResolver> > grpc_event_engine::experimental::EventEngine::GetDNSResolver ( )
pure virtual

Retrieves an instance of a DNSResolver.

◆ IsWorkerThread()

virtual bool grpc_event_engine::experimental::EventEngine::IsWorkerThread ( )
pure virtual

◆ Run()

virtual TaskHandle grpc_event_engine::experimental::EventEngine::Run ( Callback  fn,
RunOptions  opts 
)
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.

◆ RunAt()

virtual TaskHandle grpc_event_engine::experimental::EventEngine::RunAt ( absl::Time  when,
Callback  fn,
RunOptions  opts 
)
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.

◆ Shutdown()

virtual void grpc_event_engine::experimental::EventEngine::Shutdown ( Callback  on_shutdown_complete)
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.

◆ TryCancel()

virtual void grpc_event_engine::experimental::EventEngine::TryCancel ( TaskHandle  handle)
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:

  1. We cancel the execution before it has run.
  2. The callback has already run.
  3. We can't cancel it because it is "in flight".

In all cases, the cancellation is still considered successful, the callback will be run exactly once from either cancellation or from its activation.


The documentation for this class was generated from the following file: