1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
// Copyright 2022 gRPC Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
#ifndef GRPC_SRC_CORE_LIB_EVENT_ENGINE_POSIX_H
#define GRPC_SRC_CORE_LIB_EVENT_ENGINE_POSIX_H
#include <grpc/support/port_platform.h>
#include <memory>
#include "absl/functional/any_invocable.h"
#include "absl/status/status.h"
#include "absl/status/statusor.h"
#include <grpc/event_engine/endpoint_config.h>
#include <grpc/event_engine/event_engine.h>
#include <grpc/event_engine/memory_allocator.h>
#include <grpc/event_engine/slice_buffer.h>
namespace grpc_event_engine {
namespace experimental {
/// This defines an interface that posix specific EventEngines endpoints
/// may implement to support additional file descriptor related functionality.
class PosixEndpointWithFdSupport : public EventEngine::Endpoint {
public:
/// Returns the file descriptor associated with the posix endpoint.
virtual int GetWrappedFd() = 0;
/// Returns if the Endpoint supports tracking events from errmsg queues on
/// posix systems.
virtual bool CanTrackErrors() = 0;
/// Shutdown the endpoint. This function call should trigger execution of
/// any pending endpoint Read/Write callbacks with appropriate error
/// absl::Status. After this function call any subsequent endpoint
/// Read/Write operations until endpoint deletion should fail with an
/// appropriate absl::Status.
///
/// \a on_release_fd - If specifed, the callback is invoked when the
/// endpoint is destroyed/deleted. The underlying file descriptor is
/// released instead of being closed. The callback will get the released
/// file descriptor as its argument if the release operation is successful.
/// Otherwise it would get an appropriate error status as its argument.
virtual void Shutdown(absl::AnyInvocable<void(absl::StatusOr<int> release_fd)>
on_release_fd) = 0;
};
/// Defines an interface that posix EventEngine listeners may implement to
/// support additional file descriptor related functionality.
class PosixListenerWithFdSupport : public EventEngine::Listener {
public:
/// Called when a posix listener bind operation completes. A single bind
/// operation may trigger creation of multiple listener fds. This callback
/// should be invoked once on each newly created and bound fd. If the
/// corresponding bind operation fails for a particular fd, this callback
/// must be invoked with a absl::FailedPreConditionError status.
///
/// \a listener_fd - The listening socket fd that was bound to the specified
/// address.
using OnPosixBindNewFdCallback =
absl::AnyInvocable<void(absl::StatusOr<int> listener_fd)>;
/// Bind an address/port to this Listener.
///
/// It is expected that multiple addresses/ports can be bound to this
/// Listener before Listener::Start has been called. Returns either the
/// bound port or an appropriate error status.
/// \a addr - The address to listen for incoming connections.
/// \a on_bind_new_fd The callback is invoked once for each newly bound
/// listener fd that may be created by this Bind operation.
virtual absl::StatusOr<int> BindWithFd(
const EventEngine::ResolvedAddress& addr,
OnPosixBindNewFdCallback on_bind_new_fd) = 0;
/// Handle an externally accepted client connection. It must return an
/// appropriate error status in case of failure.
///
/// This may be invoked to process a new client connection accepted by an
/// external listening fd.
/// \a listener_fd - The external listening socket fd that accepted the new
/// client connection.
/// \a fd - The socket file descriptor representing the new client
/// connection.
/// \a pending_data - If specified, it holds any pending data that may have
/// already been read over the externally accepted client connection.
/// Otherwise, it is assumed that no data has been read over the new client
/// connection.
virtual absl::Status HandleExternalConnection(int listener_fd, int fd,
SliceBuffer* pending_data) = 0;
/// Shutdown/stop listening on all bind Fds.
virtual void ShutdownListeningFds() = 0;
};
/// Defines an interface that posix EventEngines may implement to
/// support additional file descriptor related functionality.
class PosixEventEngineWithFdSupport : public EventEngine {
public:
/// Creates a posix specific EventEngine::Endpoint from an fd which is already
/// assumed to be connected to a remote peer. \a fd - The connected socket
/// file descriptor. \a config - Additional configuration to applied to the
/// endpoint. \a memory_allocator - The endpoint may use the provided memory
/// allocator to track memory allocations.
virtual std::unique_ptr<PosixEndpointWithFdSupport> CreatePosixEndpointFromFd(
int fd, const EndpointConfig& config,
MemoryAllocator memory_allocator) = 0;
/// Called when the posix listener has accepted a new client connection.
/// \a listener_fd - The listening socket fd that accepted the new client
/// connection.
/// \a endpoint - The EventEngine endpoint to handle data exchange over the
/// new client connection.
/// \a is_external - A boolean indicating whether the new client connection
/// is accepted by an external listener_fd or by a listener_fd that is
/// managed by the EventEngine listener.
/// \a memory_allocator - The callback may use the provided memory
/// allocator to handle memory allocation operations.
/// \a pending_data - If specified, it holds any pending data that may have
/// already been read over the new client connection. Otherwise, it is
/// assumed that no data has been read over the new client connection.
using PosixAcceptCallback = absl::AnyInvocable<void(
int listener_fd, std::unique_ptr<EventEngine::Endpoint> endpoint,
bool is_external, MemoryAllocator memory_allocator,
SliceBuffer* pending_data)>;
/// Factory method to create a posix specific network listener / server with
/// fd support.
///
/// Once a \a Listener is created and started, the \a on_accept 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,
/// \a on_shutdown will never be called.
///
/// If this method returns a Listener, then \a 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 \a MemoryAllocatorFactory is used to create \a
/// MemoryAllocators for Endpoint construction.
virtual absl::StatusOr<std::unique_ptr<PosixListenerWithFdSupport>>
CreatePosixListener(
PosixAcceptCallback on_accept,
absl::AnyInvocable<void(absl::Status)> on_shutdown,
const EndpointConfig& config,
std::unique_ptr<MemoryAllocatorFactory> memory_allocator_factory) = 0;
};
} // namespace experimental
} // namespace grpc_event_engine
#endif // GRPC_SRC_CORE_LIB_EVENT_ENGINE_POSIX_H