GRPC C++  1.39.1
event_engine.h
Go to the documentation of this file.
1 // Copyright 2021 The gRPC Authors
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 #ifndef GRPC_EVENT_ENGINE_EVENT_ENGINE_H
15 #define GRPC_EVENT_ENGINE_EVENT_ENGINE_H
16 
18 
19 #include <functional>
20 #include <vector>
21 
22 #include "absl/status/status.h"
23 #include "absl/status/statusor.h"
24 #include "absl/time/time.h"
25 
27 #include "grpc/event_engine/port.h"
29 
30 // TODO(hork): Define the Endpoint::Write metrics collection system
31 namespace grpc_event_engine {
32 namespace experimental {
33 
74 class EventEngine {
75  public:
80  using Callback = std::function<void(absl::Status)>;
82  struct TaskHandle {
83  intptr_t key;
84  };
93  public:
94  static constexpr socklen_t MAX_SIZE_BYTES = 128;
95 
96  ResolvedAddress(const sockaddr* address, socklen_t size);
97  ResolvedAddress() = default;
98  ResolvedAddress(const ResolvedAddress&) = default;
99  const struct sockaddr* address() const;
100  socklen_t size() const;
101 
102  private:
103  char address_[MAX_SIZE_BYTES];
104  socklen_t size_ = 0;
105  };
106 
115  class Endpoint {
116  public:
119  virtual ~Endpoint() = default;
132  virtual void Read(Callback on_read, SliceBuffer* buffer,
133  absl::Time deadline) = 0;
145  virtual void Write(Callback on_writable, SliceBuffer* data,
146  absl::Time deadline) = 0;
150  virtual const ResolvedAddress* GetPeerAddress() const = 0;
151  virtual const ResolvedAddress* GetLocalAddress() const = 0;
152  };
153 
161  std::function<void(absl::StatusOr<std::unique_ptr<Endpoint>>)>;
162 
165  class Listener {
166  public:
168  using AcceptCallback = std::function<void(std::unique_ptr<Endpoint>)>;
169  virtual ~Listener() = default;
175  virtual absl::StatusOr<int> Bind(const ResolvedAddress& addr) = 0;
176  virtual absl::Status Start() = 0;
177  };
178 
197  virtual absl::StatusOr<std::unique_ptr<Listener>> CreateListener(
198  Listener::AcceptCallback on_accept, Callback on_shutdown,
199  const EndpointConfig& args,
200  SliceAllocatorFactory slice_allocator_factory) = 0;
215  const ResolvedAddress& addr,
216  const EndpointConfig& args,
217  SliceAllocator slice_allocator,
218  absl::Time deadline) = 0;
219 
221  class DNSResolver {
222  public:
225  intptr_t key;
226  };
228  struct SRVRecord {
229  std::string host;
230  int port = 0;
231  int priority = 0;
232  int weight = 0;
233  };
237  std::function<void(absl::StatusOr<std::vector<ResolvedAddress>>)>;
240  std::function<void(absl::StatusOr<std::vector<SRVRecord>>)>;
242  using LookupTXTCallback = std::function<void(absl::StatusOr<std::string>)>;
243 
244  virtual ~DNSResolver() = default;
245 
257  absl::string_view address,
258  absl::string_view default_port,
259  absl::Time deadline) = 0;
265  absl::string_view name,
266  absl::Time deadline) = 0;
272  absl::string_view name,
273  absl::Time deadline) = 0;
275  virtual void TryCancelLookup(LookupTaskHandle handle) = 0;
276  };
277 
278  virtual ~EventEngine() = default;
279 
280  // TODO(nnoble): consider whether we can remove this method before we
281  // de-experimentalize this API.
282  virtual bool IsWorkerThread() = 0;
283 
284  // TODO(hork): define return status codes
286  virtual absl::StatusOr<std::unique_ptr<DNSResolver>> GetDNSResolver() = 0;
287 
289  struct RunOptions {};
295  virtual TaskHandle Run(Callback fn, RunOptions opts) = 0;
301  virtual TaskHandle RunAt(absl::Time when, Callback fn, RunOptions opts) = 0;
314  virtual void TryCancel(TaskHandle handle) = 0;
324  virtual void Shutdown(Callback on_shutdown_complete) = 0;
325 };
326 
327 // TODO(hork): finalize the API and document it. We need to firm up the story
328 // around user-provided EventEngines.
329 std::shared_ptr<EventEngine> DefaultEventEngineFactory();
330 
331 } // namespace experimental
332 } // namespace grpc_event_engine
333 
334 #endif // GRPC_EVENT_ENGINE_EVENT_ENGINE_H
A set of parameters used to configure an endpoint, either when initiating a new connection on the cli...
Definition: endpoint_config.h:35
The DNSResolver that provides asynchronous resolution.
Definition: event_engine.h:221
std::function< void(absl::StatusOr< std::vector< SRVRecord > >)> LookupSRVCallback
Called with a collection of SRV records.
Definition: event_engine.h:240
virtual LookupTaskHandle LookupHostname(LookupHostnameCallback on_resolve, absl::string_view address, absl::string_view default_port, absl::Time deadline)=0
Asynchronously resolve an address.
virtual LookupTaskHandle LookupTXT(LookupTXTCallback on_resolve, absl::string_view name, absl::Time deadline)=0
Asynchronously perform a TXT record lookup.
virtual LookupTaskHandle LookupSRV(LookupSRVCallback on_resolve, absl::string_view name, absl::Time deadline)=0
Asynchronously perform an SRV record lookup.
std::function< void(absl::StatusOr< std::string >)> LookupTXTCallback
Called with the result of a TXT record lookup.
Definition: event_engine.h:242
std::function< void(absl::StatusOr< std::vector< ResolvedAddress > >)> LookupHostnameCallback
Called with the collection of sockaddrs that were resolved from a given target address.
Definition: event_engine.h:237
virtual void TryCancelLookup(LookupTaskHandle handle)=0
Cancel an asynchronous lookup operation.
An Endpoint represents one end of a connection between a gRPC client and server.
Definition: event_engine.h:115
virtual void Write(Callback on_writable, SliceBuffer *data, absl::Time deadline)=0
Write data out on the connection.
virtual const ResolvedAddress * GetPeerAddress() const =0
These methods return an address in the format described in DNSResolver.
virtual const ResolvedAddress * GetLocalAddress() const =0
virtual void Read(Callback on_read, SliceBuffer *buffer, absl::Time deadline)=0
Read data from the Endpoint.
virtual ~Endpoint()=default
The Endpoint destructor is responsible for shutting down all connections and invoking all pending rea...
An EventEngine Listener listens for incoming connection requests from gRPC clients and initiates requ...
Definition: event_engine.h:165
virtual absl::StatusOr< int > Bind(const ResolvedAddress &addr)=0
Bind an address/port to this Listener.
std::function< void(std::unique_ptr< Endpoint >)> AcceptCallback
Called when the listener has accepted a new client connection.
Definition: event_engine.h:168
A thin wrapper around a platform-specific sockaddr type.
Definition: event_engine.h:92
static constexpr socklen_t MAX_SIZE_BYTES
Definition: event_engine.h:94
ResolvedAddress(const sockaddr *address, socklen_t size)
The EventEngine encapsulates all platform-specific behaviors related to low level network I/O,...
Definition: event_engine.h:74
virtual void Shutdown(Callback on_shutdown_complete)=0
Immediately run all callbacks with status indicating the shutdown.
virtual TaskHandle Run(Callback fn, RunOptions opts)=0
Run a callback as soon as possible.
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.
virtual void TryCancel(TaskHandle handle)=0
Immediately tries to cancel a callback.
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.
virtual TaskHandle RunAt(absl::Time when, Callback fn, RunOptions opts)=0
Synonymous with scheduling an alarm to run at time when.
std::function< void(absl::StatusOr< std::unique_ptr< Endpoint > >)> OnConnectCallback
Called when a new connection is established.
Definition: event_engine.h:161
virtual absl::StatusOr< std::unique_ptr< DNSResolver > > GetDNSResolver()=0
Retrieves an instance of a DNSResolver.
std::function< void(absl::Status)> Callback
A basic callable function.
Definition: event_engine.h:80
Definition: slice_allocator.h:38
Definition: slice_allocator.h:32
::google::protobuf::util::Status Status
Definition: config_protobuf.h:91
std::shared_ptr< EventEngine > DefaultEventEngineFactory()
Definition: endpoint_config.h:24
A task handle for DNS Resolution requests.
Definition: event_engine.h:224
A DNS SRV record type.
Definition: event_engine.h:228
Intended for future expansion of Task run functionality.
Definition: event_engine.h:289
A callback handle, used to cancel a callback.
Definition: event_engine.h:82
intptr_t key
Definition: event_engine.h:83