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

One end of a connection between a gRPC client and server. More...

#include <event_engine.h>

Data Structures

class  ReadArgs
 A struct representing optional arguments that may be provided to an EventEngine Endpoint Read API call. More...
 
class  WriteArgs
 A struct representing optional arguments that may be provided to an EventEngine Endpoint Write API call. More...
 
class  WriteEventSink
 
struct  WriteMetric
 An output WriteMetric consists of a key and a value. More...
 

Public Types

using WriteEvent = ::grpc_event_engine::experimental::internal::WriteEvent
 
using WriteEventCallback = absl::AnyInvocable< void(WriteEvent, absl::Time, std::vector< WriteMetric >) const >
 
using WriteEventSet = std::bitset< static_cast< int >(WriteEvent::kCount)>
 

Public Member Functions

virtual ~Endpoint ()=default
 Shuts down all connections and invokes all pending read or write callbacks with an error status. More...
 
virtual bool Read (absl::AnyInvocable< void(absl::Status)> on_read, SliceBuffer *buffer, ReadArgs args)=0
 Reads data from the Endpoint. More...
 
virtual bool Write (absl::AnyInvocable< void(absl::Status)> on_writable, SliceBuffer *data, WriteArgs args)=0
 Writes data out on the connection. More...
 
virtual const ResolvedAddressGetPeerAddress () const =0
 Returns an address in the format described in DNSResolver. More...
 
virtual const ResolvedAddressGetLocalAddress () const =0
 
virtual std::vector< size_t > AllWriteMetrics ()=0
 Returns the list of write metrics that the endpoint supports. More...
 
virtual std::optional< absl::string_view > GetMetricName (size_t key)=0
 Returns the name of the write metric with the given key. More...
 
virtual std::optional< size_t > GetMetricKey (absl::string_view name)=0
 Returns the key of the write metric with the given name. More...
 
- Public Member Functions inherited from grpc_event_engine::experimental::Extensible
virtual void * QueryExtension (absl::string_view)
 A method which allows users to query whether an implementation supports a specified extension. More...
 

Additional Inherited Members

- Protected Member Functions inherited from grpc_event_engine::experimental::Extensible
 ~Extensible ()=default
 

Detailed Description

One end of a connection between a gRPC client and server.

Endpoints are created when connections are established, and Endpoint operations are gRPC's primary means of communication.

Endpoints must use the provided MemoryAllocator for all data buffer memory allocations. gRPC allows applications to set memory constraints per Channel or Server, and the implementation depends on all dynamic memory allocation being handled by the quota system.

Member Typedef Documentation

◆ WriteEvent

◆ WriteEventCallback

using grpc_event_engine::experimental::EventEngine::Endpoint::WriteEventCallback = absl::AnyInvocable<void( WriteEvent, absl::Time, std::vector<WriteMetric>) const>

◆ WriteEventSet

using grpc_event_engine::experimental::EventEngine::Endpoint::WriteEventSet = std::bitset<static_cast<int>(WriteEvent::kCount)>

Constructor & Destructor Documentation

◆ ~Endpoint()

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

Shuts down all connections and invokes all pending read or write callbacks with an error status.

Member Function Documentation

◆ AllWriteMetrics()

virtual std::vector<size_t> grpc_event_engine::experimental::EventEngine::Endpoint::AllWriteMetrics ( )
pure virtual

Returns the list of write metrics that the endpoint supports.

The keys are used to identify the metrics in the GetMetricName and GetMetricKey APIs. The current value of the metric can be queried by adding a WriteEventSink to the WriteArgs of a Write call.

◆ GetLocalAddress()

virtual const ResolvedAddress& grpc_event_engine::experimental::EventEngine::Endpoint::GetLocalAddress ( ) const
pure virtual

◆ GetMetricKey()

virtual std::optional<size_t> grpc_event_engine::experimental::EventEngine::Endpoint::GetMetricKey ( absl::string_view  name)
pure virtual

Returns the key of the write metric with the given name.

If the name is not found, returns std::nullopt.

◆ GetMetricName()

virtual std::optional<absl::string_view> grpc_event_engine::experimental::EventEngine::Endpoint::GetMetricName ( size_t  key)
pure virtual

Returns the name of the write metric with the given key.

If the key is not found, returns std::nullopt.

◆ GetPeerAddress()

virtual const ResolvedAddress& grpc_event_engine::experimental::EventEngine::Endpoint::GetPeerAddress ( ) const
pure virtual

Returns an address in the format described in DNSResolver.

The returned values are expected to remain valid for the life of the Endpoint.

◆ Read()

virtual bool grpc_event_engine::experimental::EventEngine::Endpoint::Read ( absl::AnyInvocable< void(absl::Status)>  on_read,
SliceBuffer buffer,
ReadArgs  args 
)
pure virtual

Reads data from the Endpoint.

When data is available on the connection, that data is moved into the buffer. If the read succeeds immediately, it returns true and the on_read callback is not executed. Otherwise it returns false and the on_read callback executes asynchronously when the read completes. The caller must ensure that the callback has access to the buffer when it executes. Ownership of the buffer is not transferred. Either an error is passed to the callback (like socket closed), or valid data is available in the buffer, but never both at the same time. Implementations that receive valid data must not throw that data away - that is, if valid data is received on the underlying endpoint, a callback will be made with that data available and an ok status.

There can be at most one outstanding read per Endpoint at any given time. An outstanding read is one in which the on_read callback has not yet been executed for some previous call to Read. If an attempt is made to call Read while a previous read is still outstanding, the EventEngine must abort.

For failed read operations, implementations should pass the appropriate statuses to on_read. For example, callbacks might expect to receive CANCELLED on endpoint shutdown.

◆ Write()

virtual bool grpc_event_engine::experimental::EventEngine::Endpoint::Write ( absl::AnyInvocable< void(absl::Status)>  on_writable,
SliceBuffer data,
WriteArgs  args 
)
pure virtual

Writes data out on the connection.

If the write succeeds immediately, it returns true and the on_writable callback is not executed. Otherwise it returns false and the on_writable callback is called asynchronously when the connection is ready for more data. The Slices within the data buffer may be mutated at will by the Endpoint until on_writable is called. The data SliceBuffer will remain valid after calling Write, but its state is otherwise undefined. All bytes in data must have been written before calling on_writable unless an error has occurred.

There can be at most one outstanding write per Endpoint at any given time. An outstanding write is one in which the on_writable callback has not yet been executed for some previous call to Write. If an attempt is made to call Write while a previous write is still outstanding, the EventEngine must abort.

For failed write operations, implementations should pass the appropriate statuses to on_writable. For example, callbacks might expect to receive CANCELLED on endpoint shutdown.


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