1 - 
//
 
2 - 
// Copyright (c) 2026 Steve Gerbino
 
3 - 
//
 
4 - 
// Distributed under the Boost Software License, Version 1.0. (See accompanying
 
5 - 
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
6 - 
//
 
7 - 
// Official repository: https://github.com/cppalliance/corosio
 
8 - 
//
 
9 -
 
10 - 
#ifndef BOOST_COROSIO_SOCKET_OPTION_HPP
 
11 - 
#define BOOST_COROSIO_SOCKET_OPTION_HPP
 
12 -
 
13 - 
#include <boost/corosio/detail/config.hpp>
 
14 -
 
15 - 
#include <cstddef>
 
16 -
 
17 - 
/** @file socket_option.hpp
 
18 -
 
19 - 
    Type-erased socket option types that avoid platform-specific
 
20 - 
    headers. The protocol level and option name for each type are
 
21 - 
    resolved at link time via the compiled library.
 
22 -
 
23 - 
    For an inline (zero-overhead) alternative that includes platform
 
24 - 
    headers, use `<boost/corosio/native/native_socket_option.hpp>`
 
25 - 
    (`boost::corosio::native_socket_option`).
 
26 -
 
27 - 
    Both variants satisfy the same option-type interface and work
 
28 - 
    interchangeably with `tcp_socket::set_option` /
 
29 - 
    `tcp_socket::get_option` and the corresponding acceptor methods.
 
30 -
 
31 - 
    @see native_socket_option
 
32 - 
*/
 
33 -
 
34 - 
namespace boost::corosio::socket_option {
 
35 -
 
36 - 
/** Base class for concrete boolean socket options.
 
37 -
 
38 - 
    Stores a boolean as an `int` suitable for `setsockopt`/`getsockopt`.
 
39 - 
    Derived types provide `level()` and `name()` for the specific option.
 
40 - 
*/
 
41 - 
class boolean_option
 
42 - 
{
 
43 - 
    int value_ = 0;
 
44 -
 
45 - 
public:
 
46 - 
    /// Construct with default value (disabled).
 
47 - 
    boolean_option() = default;
 
48 -
 
49 - 
    /** Construct with an explicit value.
 
50 -
 
51 - 
        @param v `true` to enable the option, `false` to disable.
 
52 - 
    */
 
53 - 
    explicit boolean_option( bool v ) noexcept : value_( v ? 1 : 0 ) {}
 
54 -
 
55 - 
    /// Assign a new value.
 
56 - 
    boolean_option& operator=( bool v ) noexcept
 
57 - 
    {
 
58 - 
        value_ = v ? 1 : 0;
 
59 - 
        return *this;
 
60 - 
    }
 
61 -
 
62 - 
    /// Return the option value.
 
63 - 
    bool value() const noexcept { return value_ != 0; }
 
64 -
 
65 - 
    /// Return the option value.
 
66 - 
    explicit operator bool() const noexcept { return value_ != 0; }
 
67 -
 
68 - 
    /// Return the negated option value.
 
69 - 
    bool operator!() const noexcept { return value_ == 0; }
 
70 -
 
71 - 
    /// Return a pointer to the underlying storage.
 
72 - 
    void* data() noexcept { return &value_; }
 
73 -
 
74 - 
    /// Return a pointer to the underlying storage.
 
75 - 
    void const* data() const noexcept { return &value_; }
 
76 -
 
77 - 
    /// Return the size of the underlying storage.
 
78 - 
    std::size_t size() const noexcept { return sizeof( value_ ); }
 
79 -
 
80 - 
    /** Normalize after `getsockopt` returns fewer bytes than expected.
 
81 -
 
82 - 
        Windows Vista+ may write only 1 byte for boolean options.
 
83 -
 
84 - 
        @param s The number of bytes actually written by `getsockopt`.
 
85 - 
    */
 
86 - 
    void resize( std::size_t s ) noexcept
 
87 - 
    {
 
88 - 
        if ( s == sizeof( char ) )
 
89 - 
            value_ = *reinterpret_cast<unsigned char*>( &value_ ) ? 1 : 0;
 
90 - 
    }
 
91 - 
};
 
92 -
 
93 - 
/** Base class for concrete integer socket options.
 
94 -
 
95 - 
    Stores an integer suitable for `setsockopt`/`getsockopt`.
 
96 - 
    Derived types provide `level()` and `name()` for the specific option.
 
97 - 
*/
 
98 - 
class integer_option
 
99 - 
{
 
100 - 
    int value_ = 0;
 
101 -
 
102 - 
public:
 
103 - 
    /// Construct with default value (zero).
 
104 - 
    integer_option() = default;
 
105 -
 
106 - 
    /** Construct with an explicit value.
 
107 -
 
108 - 
        @param v The option value.
 
109 - 
    */
 
110 - 
    explicit integer_option( int v ) noexcept : value_( v ) {}
 
111 -
 
112 - 
    /// Assign a new value.
 
113 - 
    integer_option& operator=( int v ) noexcept
 
114 - 
    {
 
115 - 
        value_ = v;
 
116 - 
        return *this;
 
117 - 
    }
 
118 -
 
119 - 
    /// Return the option value.
 
120 - 
    int value() const noexcept { return value_; }
 
121 -
 
122 - 
    /// Return a pointer to the underlying storage.
 
123 - 
    void* data() noexcept { return &value_; }
 
124 -
 
125 - 
    /// Return a pointer to the underlying storage.
 
126 - 
    void const* data() const noexcept { return &value_; }
 
127 -
 
128 - 
    /// Return the size of the underlying storage.
 
129 - 
    std::size_t size() const noexcept { return sizeof( value_ ); }
 
130 -
 
131 - 
    /** Normalize after `getsockopt` returns fewer bytes than expected.
 
132 -
 
133 - 
        @param s The number of bytes actually written by `getsockopt`.
 
134 - 
    */
 
135 - 
    void resize( std::size_t s ) noexcept
 
136 - 
    {
 
137 - 
        if ( s == sizeof( char ) )
 
138 - 
            value_ = static_cast<int>(
 
139 - 
                *reinterpret_cast<unsigned char*>( &value_ ) );
 
140 - 
    }
 
141 - 
};
 
142 -
 
143 - 
/** Disable Nagle's algorithm (TCP_NODELAY).
 
144 -
 
145 - 
    @par Example
 
146 - 
    @code
 
147 - 
    sock.set_option( socket_option::no_delay( true ) );
 
148 - 
    auto nd = sock.get_option<socket_option::no_delay>();
 
149 - 
    if ( nd.value() )
 
150 - 
        // Nagle's algorithm is disabled
 
151 - 
    @endcode
 
152 - 
*/
 
153 - 
class BOOST_COROSIO_DECL no_delay : public boolean_option
 
154 - 
{
 
155 - 
public:
 
156 - 
    using boolean_option::boolean_option;
 
157 - 
    using boolean_option::operator=;
 
158 -
 
159 - 
    /// Return the protocol level.
 
160 - 
    static int level() noexcept;
 
161 -
 
162 - 
    /// Return the option name.
 
163 - 
    static int name() noexcept;
 
164 - 
};
 
165 -
 
166 - 
/** Enable periodic keepalive probes (SO_KEEPALIVE).
 
167 -
 
168 - 
    @par Example
 
169 - 
    @code
 
170 - 
    sock.set_option( socket_option::keep_alive( true ) );
 
171 - 
    @endcode
 
172 - 
*/
 
173 - 
class BOOST_COROSIO_DECL keep_alive : public boolean_option
 
174 - 
{
 
175 - 
public:
 
176 - 
    using boolean_option::boolean_option;
 
177 - 
    using boolean_option::operator=;
 
178 -
 
179 - 
    /// Return the protocol level.
 
180 - 
    static int level() noexcept;
 
181 -
 
182 - 
    /// Return the option name.
 
183 - 
    static int name() noexcept;
 
184 - 
};
 
185 -
 
186 - 
/** Restrict an IPv6 socket to IPv6 only (IPV6_V6ONLY).
 
187 -
 
188 - 
    When enabled, the socket only accepts IPv6 connections.
 
189 - 
    When disabled, the socket accepts both IPv4 and IPv6
 
190 - 
    connections (dual-stack mode).
 
191 -
 
192 - 
    @par Example
 
193 - 
    @code
 
194 - 
    sock.set_option( socket_option::v6_only( true ) );
 
195 - 
    @endcode
 
196 - 
*/
 
197 - 
class BOOST_COROSIO_DECL v6_only : public boolean_option
 
198 - 
{
 
199 - 
public:
 
200 - 
    using boolean_option::boolean_option;
 
201 - 
    using boolean_option::operator=;
 
202 -
 
203 - 
    /// Return the protocol level.
 
204 - 
    static int level() noexcept;
 
205 -
 
206 - 
    /// Return the option name.
 
207 - 
    static int name() noexcept;
 
208 - 
};
 
209 -
 
210 - 
/** Allow local address reuse (SO_REUSEADDR).
 
211 -
 
212 - 
    @par Example
 
213 - 
    @code
 
214 - 
    acc.set_option( socket_option::reuse_address( true ) );
 
215 - 
    @endcode
 
216 - 
*/
 
217 - 
class BOOST_COROSIO_DECL reuse_address : public boolean_option
 
218 - 
{
 
219 - 
public:
 
220 - 
    using boolean_option::boolean_option;
 
221 - 
    using boolean_option::operator=;
 
222 -
 
223 - 
    /// Return the protocol level.
 
224 - 
    static int level() noexcept;
 
225 -
 
226 - 
    /// Return the option name.
 
227 - 
    static int name() noexcept;
 
228 - 
};
 
229 -
 
230 - 
/** Allow multiple sockets to bind to the same port (SO_REUSEPORT).
 
231 -
 
232 - 
    Not available on all platforms. On unsupported platforms,
 
233 - 
    `set_option` will return an error.
 
234 -
 
235 - 
    @par Example
 
236 - 
    @code
 
237 - 
    acc.open( tcp::v6() );
 
238 - 
    acc.set_option( socket_option::reuse_port( true ) );
 
239 - 
    acc.bind( endpoint( ipv6_address::any(), 8080 ) );
 
240 - 
    acc.listen();
 
241 - 
    @endcode
 
242 - 
*/
 
243 - 
class BOOST_COROSIO_DECL reuse_port : public boolean_option
 
244 - 
{
 
245 - 
public:
 
246 - 
    using boolean_option::boolean_option;
 
247 - 
    using boolean_option::operator=;
 
248 -
 
249 - 
    /// Return the protocol level.
 
250 - 
    static int level() noexcept;
 
251 -
 
252 - 
    /// Return the option name.
 
253 - 
    static int name() noexcept;
 
254 - 
};
 
255 -
 
256 - 
/** Set the receive buffer size (SO_RCVBUF).
 
257 -
 
258 - 
    @par Example
 
259 - 
    @code
 
260 - 
    sock.set_option( socket_option::receive_buffer_size( 65536 ) );
 
261 - 
    auto opt = sock.get_option<socket_option::receive_buffer_size>();
 
262 - 
    int sz = opt.value();
 
263 - 
    @endcode
 
264 - 
*/
 
265 - 
class BOOST_COROSIO_DECL receive_buffer_size : public integer_option
 
266 - 
{
 
267 - 
public:
 
268 - 
    using integer_option::integer_option;
 
269 - 
    using integer_option::operator=;
 
270 -
 
271 - 
    /// Return the protocol level.
 
272 - 
    static int level() noexcept;
 
273 -
 
274 - 
    /// Return the option name.
 
275 - 
    static int name() noexcept;
 
276 - 
};
 
277 -
 
278 - 
/** Set the send buffer size (SO_SNDBUF).
 
279 -
 
280 - 
    @par Example
 
281 - 
    @code
 
282 - 
    sock.set_option( socket_option::send_buffer_size( 65536 ) );
 
283 - 
    @endcode
 
284 - 
*/
 
285 - 
class BOOST_COROSIO_DECL send_buffer_size : public integer_option
 
286 - 
{
 
287 - 
public:
 
288 - 
    using integer_option::integer_option;
 
289 - 
    using integer_option::operator=;
 
290 -
 
291 - 
    /// Return the protocol level.
 
292 - 
    static int level() noexcept;
 
293 -
 
294 - 
    /// Return the option name.
 
295 - 
    static int name() noexcept;
 
296 - 
};
 
297 -
 
298 - 
/** The SO_LINGER socket option.
 
299 -
 
300 - 
    Controls behavior when closing a socket with unsent data.
 
301 - 
    When enabled, `close()` blocks until pending data is sent
 
302 - 
    or the timeout expires.
 
303 -
 
304 - 
    @par Example
 
305 - 
    @code
 
306 - 
    sock.set_option( socket_option::linger( true, 5 ) );
 
307 - 
    auto opt = sock.get_option<socket_option::linger>();
 
308 - 
    if ( opt.enabled() )
 
309 - 
        std::cout << "linger timeout: " << opt.timeout() << "s\n";
 
310 - 
    @endcode
 
311 - 
*/
 
312 - 
class BOOST_COROSIO_DECL linger
 
313 - 
{
 
314 - 
    // Opaque storage for the platform's struct linger.
 
315 - 
    // POSIX: { int, int } = 8 bytes.
 
316 - 
    // Windows: { u_short, u_short } = 4 bytes.
 
317 - 
    static constexpr std::size_t max_storage_ = 8;
 
318 - 
    alignas( 4 ) unsigned char storage_[max_storage_]{};
 
319 -
 
320 - 
public:
 
321 - 
    /// Construct with default values (disabled, zero timeout).
 
322 - 
    linger() noexcept = default;
 
323 -
 
324 - 
    /** Construct with explicit values.
 
325 -
 
326 - 
        @param enabled `true` to enable linger behavior on close.
 
327 - 
        @param timeout The linger timeout in seconds.
 
328 - 
    */
 
329 - 
    linger( bool enabled, int timeout ) noexcept;
 
330 -
 
331 - 
    /// Return whether linger is enabled.
 
332 - 
    bool enabled() const noexcept;
 
333 -
 
334 - 
    /// Set whether linger is enabled.
 
335 - 
    void enabled( bool v ) noexcept;
 
336 -
 
337 - 
    /// Return the linger timeout in seconds.
 
338 - 
    int timeout() const noexcept;
 
339 -
 
340 - 
    /// Set the linger timeout in seconds.
 
341 - 
    void timeout( int v ) noexcept;
 
342 -
 
343 - 
    /// Return the protocol level.
 
344 - 
    static int level() noexcept;
 
345 -
 
346 - 
    /// Return the option name.
 
347 - 
    static int name() noexcept;
 
348 -
 
349 - 
    /// Return a pointer to the underlying storage.
 
350 - 
    void* data() noexcept { return storage_; }
 
351 -
 
352 - 
    /// Return a pointer to the underlying storage.
 
353 - 
    void const* data() const noexcept { return storage_; }
 
354 -
 
355 - 
    /// Return the size of the underlying storage.
 
356 - 
    std::size_t size() const noexcept;
 
357 -
 
358 - 
    /** Normalize after `getsockopt`.
 
359 -
 
360 - 
        No-op — `struct linger` is always returned at full size.
 
361 -
 
362 - 
        @param s The number of bytes actually written by `getsockopt`.
 
363 - 
    */
 
364 - 
    void resize( std::size_t ) noexcept {}
 
365 - 
};
 
366 -
 
367 - 
} // namespace boost::corosio::socket_option
 
368 -
 
369 - 
#endif // BOOST_COROSIO_SOCKET_OPTION_HPP