userver: userver/engine/io/socket.hpp Source File
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages Concepts
socket.hpp
Go to the documentation of this file.
1#pragma once
2
3/// @file userver/engine/io/socket.hpp
4/// @brief @copybrief engine::io::Socket
5
6#include <sys/socket.h>
7
8#include <initializer_list>
9
10#include <userver/engine/deadline.hpp>
11#include <userver/engine/io/common.hpp>
12#include <userver/engine/io/exception.hpp>
13#include <userver/engine/io/fd_control_holder.hpp>
14#include <userver/engine/io/sockaddr.hpp>
15
16struct iovec;
17
18USERVER_NAMESPACE_BEGIN
19
20namespace engine::io {
21
22/// Socket type
23enum class SocketType {
24 kStream = SOCK_STREAM, ///< Stream socket (e.g. TCP)
25 kDgram = SOCK_DGRAM, ///< Datagram socket (e.g. UDP)
26
27 kTcp = kStream,
28 kUdp = kDgram,
29};
30
31/// @brief Socket representation.
32///
33/// It is not thread-safe to concurrently read from socket. It is not
34/// thread-safe to concurrently write to socket. However it is safe to
35/// concurrently read and write into socket:
36/// @snippet src/engine/io/socket_test.cpp send self concurrent
37class [[nodiscard]] Socket final : public RwBase {
38public:
40 size_t bytes_received{0};
41 Sockaddr src_addr;
42 };
43
44 /// Constructs an invalid socket.
45 Socket() = default;
46
47 /// Constructs a socket for the address domain of specified type.
48 Socket(AddrDomain, SocketType);
49
50 /// @brief Adopts an existing socket for specified address domain.
51 /// @note File descriptor will be silently forced to nonblocking mode.
52 explicit Socket(int fd, AddrDomain domain = AddrDomain::kUnspecified);
53
54 /// Whether the socket is valid.
55 explicit operator bool() const { return IsValid(); }
56
57 /// Whether the socket is valid.
58 bool IsValid() const override;
59
60 /// @brief Connects the socket to a specified endpoint.
61 /// @note Sockaddr domain must match the socket's domain.
62 void Connect(const Sockaddr&, Deadline);
63
64 /// @brief Binds the socket to the specified endpoint.
65 /// @note Sockaddr domain must match the socket's domain.
66 void Bind(const Sockaddr&);
67
68 /// Starts listening for connections on a specified socket (must be bound).
69 void Listen(int backlog = SOMAXCONN);
70
71 /// Suspends current task until the socket has data available.
72 /// @returns false on timeout or on task cancellations; true otherwise.
73 [[nodiscard]] bool WaitReadable(Deadline) override;
74
75 /// Suspends current task until the socket can accept more data.
76 /// @returns false on timeout or on task cancellations; true otherwise.
77 [[nodiscard]] bool WaitWriteable(Deadline) override;
78
79 /// @brief Receives at least one byte from the socket.
80 /// @returns 0 if connection is closed on one side and no data could be
81 /// received any more, received bytes count otherwise.
82 [[nodiscard]] size_t RecvSome(void* buf, size_t len, Deadline deadline);
83
84 /// @brief Receives exactly len bytes from the socket.
85 /// @note Can return less than len if socket is closed by peer.
86 [[nodiscard]] size_t RecvAll(void* buf, size_t len, Deadline deadline);
87
88 /// @brief Receives up to len bytes from the stream
89 /// @returns
90 /// - nullopt on data absence
91 /// - optional{0} if socket is closed by peer.
92 /// - optional{data_bytes_available} otherwise,
93 /// 1 <= data_bytes_available <= len
94 [[nodiscard]] std::optional<size_t> RecvNoblock(void* buf, size_t len);
95
96 /// @brief Sends a buffer vector to the socket.
97 /// @note Can return less than len if socket is closed by peer.
98 /// @snippet src/engine/io/socket_test.cpp send vector data in socket
99 [[nodiscard]] size_t SendAll(std::initializer_list<IoData> list, Deadline deadline);
100
101 [[nodiscard]] size_t WriteAll(std::initializer_list<IoData> list, Deadline deadline) override {
102 return SendAll(list, deadline);
103 }
104
105 /// @brief Sends exactly list_size IoData to the socket.
106 /// @note Can return less than len if socket is closed by peer.
107 [[nodiscard]] size_t SendAll(const IoData* list, std::size_t list_size, Deadline deadline);
108
109 /// @brief Sends exactly list_size iovec to the socket.
110 /// @note Can return less than len if socket is closed by peer.
111 [[nodiscard]] size_t SendAll(const struct iovec* list, std::size_t list_size, Deadline deadline);
112
113 /// @brief Sends exactly len bytes to the socket.
114 /// @note Can return less than len if socket is closed by peer.
115 [[nodiscard]] size_t SendAll(const void* buf, size_t len, Deadline deadline);
116
117 /// @brief Accepts a connection from a listening socket.
118 /// @see engine::io::Listen
119 [[nodiscard]] Socket Accept(Deadline);
120
121 /// @brief Receives at least one byte from the socket, returning source
122 /// address.
123 /// @returns 0 in bytes_sent if connection is closed on one side and no data
124 /// could be received any more, received bytes count otherwise + source
125 /// address.
126 [[nodiscard]] RecvFromResult RecvSomeFrom(void* buf, size_t len, Deadline deadline);
127
128 /// @brief Sends exactly len bytes to the specified address via the socket.
129 /// @note Can return less than len in bytes_sent if socket is closed by peer.
130 /// @note Sockaddr domain must match the socket's domain.
131 /// @note Not for SocketType::kStream connections, see `man sendto`.
132 [[nodiscard]] size_t SendAllTo(const Sockaddr& dest_addr, const void* buf, size_t len, Deadline deadline);
133
134 /// File descriptor corresponding to this socket.
135 int Fd() const;
136
137 /// Address of a remote peer.
138 const Sockaddr& Getpeername();
139
140 /// Local socket address.
141 const Sockaddr& Getsockname();
142
143 /// Releases file descriptor and invalidates the socket.
144 [[nodiscard]] int Release() && noexcept;
145
146 /// @brief Closes and invalidates the socket.
147 /// @warning You should not call Close with pending I/O. This may work okay
148 /// sometimes but it's loosely predictable.
149 void Close();
150
151 /// Retrieves a socket option.
152 int GetOption(int layer, int optname) const;
153
154 /// Sets a socket option.
155 void SetOption(int layer, int optname, int optval);
156
157 /// @brief Receives at least one byte from the socket.
158 /// @returns 0 if connection is closed on one side and no data could be
159 /// received any more, received bytes count otherwise.
160 [[nodiscard]] size_t ReadSome(void* buf, size_t len, Deadline deadline) override {
161 return RecvSome(buf, len, deadline);
162 }
163
164 /// @brief Receives exactly len bytes from the socket.
165 /// @note Can return less than len if socket is closed by peer.
166 [[nodiscard]] size_t ReadAll(void* buf, size_t len, Deadline deadline) override {
167 return RecvAll(buf, len, deadline);
168 }
169
170 /// @brief Receives up to len bytes from the stream
171 /// @returns
172 /// - nullopt on data absence
173 /// - optional{0} if socket is closed by peer.
174 /// - optional{data_bytes_available} otherwise,
175 /// 1 <= data_bytes_available <= len
176 [[nodiscard]] std::optional<size_t> ReadNoblock(void* buf, size_t len) override { return RecvNoblock(buf, len); }
177
178 /// @brief Writes exactly len bytes to the socket.
179 /// @note Can return less than len if socket is closed by peer.
180 [[nodiscard]] size_t WriteAll(const void* buf, size_t len, Deadline deadline) override {
181 return SendAll(buf, len, deadline);
182 }
183
184private:
185 AddrDomain domain_{AddrDomain::kUnspecified};
186
187 impl::FdControlHolder fd_control_;
188 Sockaddr peername_;
189 Sockaddr sockname_;
190};
191
192} // namespace engine::io
193
194USERVER_NAMESPACE_END