class EventEngine

Defined at line 102 of file ../../third_party/grpc-migrating/src/include/grpc/event_engine/event_engine.h

/////////////////////////////////////////////////////////////////////////////

The EventEngine Interface

Overview

--------

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

Blocking EventEngine Callbacks

------------------------------

Doing blocking work in EventEngine callbacks is generally not advisable.

While gRPC's default EventEngine implementations have some capacity to scale

their thread pools to avoid starvation, this is not an instantaneous

process. Further, user-provided EventEngines may not be optimized to handle

excessive blocking work at all.

*Best Practice* : Occasional blocking work may be fine, but we do not

recommend running a mostly blocking workload in EventEngine threads.

Thread-safety guarantees

------------------------

All EventEngine methods are guaranteed to be thread-safe, no external

synchronization is required to call any EventEngine method. Please note that

this does not apply to application callbacks, which may be run concurrently;

application state synchronization must be managed by the application.

/////////////////////////////////////////////////////////////////////////////

Public Methods

absl::StatusOr<std::unique_ptr<Listener>> CreateListener (Listener::AcceptCallback on_accept, absl::AnyInvocable<void (absl::Status)> on_shutdown, const EndpointConfig & config, std::unique_ptr<MemoryAllocatorFactory> memory_allocator_factory)

Factory method to create a network listener / server.

Once a

is created and started, the

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,

will never be called.

If this method returns a Listener, then

will be invoked

exactly once when the Listener is shut down, and only after all

callbacks have finished executing. The status passed to it

will indicate if there was a problem during shutdown.

The provided

is used to create

for Endpoint construction.

ConnectionHandle Connect (OnConnectCallback on_connect, const ResolvedAddress & addr, const EndpointConfig & args, MemoryAllocator memory_allocator, Duration timeout)

Creates a client network connection to a remote network listener.

Even in the event of an error, it is expected that the

callback will be asynchronously executed exactly once by the EventEngine.

A connection attempt can be cancelled using the

method.

Implementation Note: it is important that the

be used

for all read/write buffer allocations in the EventEngine implementation.

This allows gRPC's

system to monitor and control memory

usage with graceful degradation mechanisms. Please see the

API for more information.

bool CancelConnect (ConnectionHandle handle)

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

will not be

called, and

will be destroyed before this method returns.

bool IsWorkerThread ()

TODO(nnoble): consider whether we can remove this method before we

de-experimentalize this API.

absl::StatusOr<std::unique_ptr<DNSResolver>> GetDNSResolver (const DNSResolver::ResolverOptions & options)

Creates and returns an instance of a DNSResolver, optionally configured by

the

struct. This method may return a non-OK status if an error

occurred when creating the DNSResolver. If the caller requests a custom

DNS server, and the EventEngine implementation does not support it, this

must return an error.

void Run (Closure * closure)

Asynchronously executes a task as soon as possible.

passed to

cannot be cancelled. The

will not

be deleted after it has been run, ownership remains with the caller.

Implementations must not execute the closure in the calling thread before

returns. For example, if the caller must release a lock before the

closure can proceed, running the closure immediately would cause a

deadlock.

void Run (absl::AnyInvocable<void ()> closure)

Asynchronously executes a task as soon as possible.

passed to

cannot be cancelled. Unlike the overloaded

alternative, the absl::AnyInvocable version's

will be

deleted by the EventEngine after the closure has been run.

This version of

may be less performant than the

version

in some scenarios. This overload is useful in situations where performance

is not a critical concern.

Implementations must not execute the closure in the calling thread before

returns.

TaskHandle RunAfter (Duration when, Closure * closure)

Synonymous with scheduling an alarm to run after duration

The

will execute when time

arrives unless it has been

cancelled via the

method. If cancelled, the closure will not be

run, nor will it be deleted. Ownership remains with the caller.

Implementations must not execute the closure in the calling thread before

returns.

Implementations may return a

handle if the callback can be

immediately executed, and is therefore not cancellable.

TaskHandle RunAfter (Duration when, absl::AnyInvocable<void ()> closure)

Synonymous with scheduling an alarm to run after duration

The

will execute when time

arrives unless it has been

cancelled via the

method. If cancelled, the closure will not be

run. Unlike the overloaded

alternative, the absl::AnyInvocable

version's

will be deleted by the EventEngine after the closure

has been run, or upon cancellation.

This version of

may be less performant than the

version in some scenarios. This overload is useful in situations where

performance is not a critical concern.

Implementations must not execute the closure in the calling thread before

returns.

bool Cancel (TaskHandle handle)

Request cancellation of a task.

If the associated closure cannot be cancelled for any reason, this

function will return false.

If the associated closure can be cancelled, the associated callback will

never be run, and this method will return true. If the callback type was

an absl::AnyInvocable, it will be destroyed before the method returns.

void ~EventEngine ()

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.

Defined at line 395 of file ../../third_party/grpc-migrating/src/include/grpc/event_engine/event_engine.h