diff --git a/include/tmc/asio/aw_asio.hpp b/include/tmc/asio/aw_asio.hpp index 49b696c9..6114f757 100644 --- a/include/tmc/asio/aw_asio.hpp +++ b/include/tmc/asio/aw_asio.hpp @@ -22,6 +22,18 @@ #include #include +// asio's synchronous (error_code&) operations report failure through the ec +// out-parameter. In asio's default configuration they *also* return that same +// error_code redundantly; defining ASIO_NO_DEPRECATED / BOOST_ASIO_NO_DEPRECATED +// makes the return type void instead. This discards the redundant return - so it +// doesn't trip clang-tidy's bugprone-unused-return-value - while compiling +// correctly in either configuration. +#if defined(ASIO_NO_DEPRECATED) || defined(BOOST_ASIO_NO_DEPRECATED) +#define TMC_ASIO_SYNC_DISCARD(...) __VA_ARGS__ +#else +#define TMC_ASIO_SYNC_DISCARD(...) std::ignore = (__VA_ARGS__) +#endif + namespace tmc { namespace detail { struct AwAsioTag {}; diff --git a/include/tmc/asio/safe_acceptor.hpp b/include/tmc/asio/safe_acceptor.hpp new file mode 100644 index 00000000..dbe8062d --- /dev/null +++ b/include/tmc/asio/safe_acceptor.hpp @@ -0,0 +1,295 @@ +// Copyright (c) 2023-2026 Logan McDougall +// +// Distributed under the Boost Software License, Version 1.0. (See accompanying +// file LICENSE or copy at http://www.boost.org/LICENSE_1_0.txt) + +#pragma once + +#include "tmc/asio/aw_asio.hpp" +#include "tmc/detail/compat.hpp" +#include "tmc/task.hpp" + +#include "tmc/detail/tiny_mutex.hpp" + +#ifdef TMC_USE_BOOST_ASIO +#include +#include +#else +#include +#include +#endif + +#include +#include + +namespace tmc { +namespace detail { +#ifdef TMC_USE_BOOST_ASIO +namespace asio_ns = ::boost::asio; +#else +namespace asio_ns = ::asio; +#endif +} // namespace detail + +/// Type that serializes Asio acceptor operations so they can be initiated safely from +/// different coroutines. Unlike a strand, this only serializes the initiation of +/// operations; it does not serialize full handlers. +/// +/// Methods behave exactly as the underlying object's methods with the same name, except: +/// - methods are thread-safe +/// - methods implicitly use the `tmc::aw_asio` completion +/// +/// The asio_safe_acceptor must outlive every task that uses it, including any task still +/// waiting to acquire its mutex. Destroying it while such tasks exist is a +/// use-after-free. +/// +/// Templated on the underlying Asio acceptor type so it can serialize acceptors +/// for any AcceptableProtocol (e.g. `ip::tcp`, `local::stream_protocol`). All +/// associated types are derived from `Acceptor`. +template +class asio_safe_acceptor { +public: + using acceptor_type = Acceptor; + using protocol_type = typename Acceptor::protocol_type; + using endpoint_type = typename Acceptor::endpoint_type; + using executor_type = typename Acceptor::executor_type; + using native_handle_type = typename Acceptor::native_handle_type; + using wait_type = typename Acceptor::wait_type; + // The socket type produced by `async_accept()`: the protocol's socket rebound + // to the acceptor's executor (matches Asio's own accept-return type). + using socket_type = + typename protocol_type::socket::template rebind_executor::other; +#ifdef TMC_USE_BOOST_ASIO + using error_code = boost::system::error_code; +#else + using error_code = asio::error_code; +#endif + +private: + acceptor_type acceptor_; + tmc::tiny_mutex mut_; + +public: + /// Constructs this from an Asio acceptor. + explicit asio_safe_acceptor(acceptor_type acceptor) : acceptor_(std::move(acceptor)) {} + + /// Allows access to the underlying (unsynchronized) Asio object. + acceptor_type& inner() noexcept { return acceptor_; } + /// Allows access to the underlying (unsynchronized) Asio object. + const acceptor_type& inner() const noexcept { return acceptor_; } + + tmc::task is_open() noexcept { + co_await mut_; + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(acceptor_.is_open()); + TMC_UNREACHABLE; + } + + tmc::task open(protocol_type protocol) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(acceptor_.open(protocol, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + template + tmc::task set_option(SettableSocketOption option) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(acceptor_.set_option(option, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + tmc::task bind(endpoint_type endpoint) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(acceptor_.bind(endpoint, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + tmc::task + listen(int backlog = tmc::detail::asio_ns::socket_base::max_listen_connections) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(acceptor_.listen(backlog, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + tmc::task> async_accept() { + co_await mut_; + co_return co_await acceptor_.async_accept(tmc::aw_asio); + } + + tmc::task> async_accept_endpoint() { + co_await mut_; + // `peer` is filled before the completion handler runs; it lives in this + // coroutine frame, so it outlives the async operation. + endpoint_type peer; + auto [ec, sock] = co_await acceptor_.async_accept(peer, tmc::aw_asio); + co_return std::tuple{ec, std::move(sock), std::move(peer)}; + } + + tmc::task> async_wait(wait_type w) { + co_await mut_; + + co_return co_await acceptor_.async_wait(w, tmc::aw_asio); + } + + tmc::task cancel() { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(acceptor_.cancel(ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + tmc::task close() { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(acceptor_.close(ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + tmc::task get_executor() { + co_await mut_; + + executor_type ex = acceptor_.get_executor(); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(std::move(ex)); + TMC_UNREACHABLE; + } + + tmc::task + assign(protocol_type protocol, native_handle_type native_acceptor) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(acceptor_.assign(protocol, native_acceptor, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + tmc::task> release() { + co_await mut_; + + error_code ec; + native_handle_type handle = acceptor_.release(ec); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(std::tuple{ec, handle}); + TMC_UNREACHABLE; + } + + template + tmc::task> + get_option(GettableSocketOption option) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(acceptor_.get_option(option, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(std::tuple{ec, std::move(option)}); + TMC_UNREACHABLE; + } + + template + tmc::task> + io_control(IoControlCommand command) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(acceptor_.io_control(command, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(std::tuple{ec, std::move(command)}); + TMC_UNREACHABLE; + } + + tmc::task non_blocking() { + co_await mut_; + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(acceptor_.non_blocking()); + TMC_UNREACHABLE; + } + + tmc::task non_blocking(bool mode) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(acceptor_.non_blocking(mode, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + tmc::task native_non_blocking() { + co_await mut_; + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(acceptor_.native_non_blocking()); + TMC_UNREACHABLE; + } + + tmc::task native_non_blocking(bool mode) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(acceptor_.native_non_blocking(mode, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + tmc::task> local_endpoint() { + co_await mut_; + + error_code ec; + endpoint_type ep = acceptor_.local_endpoint(ec); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(std::tuple{ec, std::move(ep)}); + TMC_UNREACHABLE; + } + + tmc::task native_handle() { + co_await mut_; + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(acceptor_.native_handle()); + TMC_UNREACHABLE; + } +}; + +template asio_safe_acceptor(Acceptor) -> asio_safe_acceptor; + +} // namespace tmc diff --git a/include/tmc/asio/safe_socket.hpp b/include/tmc/asio/safe_socket.hpp new file mode 100644 index 00000000..bf663eb1 --- /dev/null +++ b/include/tmc/asio/safe_socket.hpp @@ -0,0 +1,480 @@ +// Copyright (c) 2023-2026 Logan McDougall +// +// Distributed under the Boost Software License, Version 1.0. (See accompanying +// file LICENSE or copy at http://www.boost.org/LICENSE_1_0.txt) + +#pragma once + +#include "tmc/asio/aw_asio.hpp" +#include "tmc/detail/compat.hpp" +#include "tmc/task.hpp" + +#include "tmc/detail/tiny_mutex.hpp" + +#ifdef TMC_USE_BOOST_ASIO +#include +#include +#include +#include +#else +#include +#include +#include +#include +#endif + +#include +#include +#include + +namespace tmc { +namespace detail { +#ifdef TMC_USE_BOOST_ASIO +namespace asio_ns = ::boost::asio; +#else +namespace asio_ns = ::asio; +#endif +} // namespace detail + +/// Type that serializes Asio socket operations so they can be initiated safely from +/// different coroutines. Unlike a strand, this only serializes the initiation of +/// operations; it does not serialize full handlers. +/// +/// It does not prevent overlapping reads and writes. The user is responsible +/// for ensuring at most 1 read and 1 write are active at any time, per the usual Asio +/// contract. +/// +/// Methods behave exactly as the underlying object's methods with the same name, except: +/// - methods are thread-safe +/// - methods implicitly use the `tmc::aw_asio` completion +/// +/// The asio_safe_socket must outlive every task that uses it, including any task still +/// waiting to acquire its mutex. Destroying it while such tasks exist is a +/// use-after-free. +/// +/// Templated on the underlying Asio socket type so it can serialize sockets for +/// any protocol. The stream-oriented composed operations (`async_read`, +/// `async_write`) and their single-shot forms (`async_read_some`, +/// `async_write_some`) are constrained to stream sockets; on a socket type that +/// lacks them (e.g. a datagram socket) they are not present. All other operations work +/// for any socket. +template +class asio_safe_socket { +public: + using socket_type = Socket; + using protocol_type = typename Socket::protocol_type; + using endpoint_type = typename Socket::endpoint_type; + using executor_type = typename Socket::executor_type; + using native_handle_type = typename Socket::native_handle_type; + using wait_type = typename Socket::wait_type; + using message_flags = typename Socket::message_flags; +#ifdef TMC_USE_BOOST_ASIO + using error_code = boost::system::error_code; +#else + using error_code = asio::error_code; +#endif + +private: + socket_type socket_; + tmc::tiny_mutex mut_; + + // Set true while a composed async_read()/async_write() is running, and + // cleared by cancel(). This closes the window where a cancel() lands between + // the composed operation's single-shot reads/writes - when nothing is pending + // on the socket for socket_.cancel() to hit. Only touched under mut_. + bool read_active_ = false; + bool write_active_ = false; + +public: + /// Constructs this from an Asio socket. + explicit asio_safe_socket(socket_type socket) : socket_(std::move(socket)) {} + + /// Allows access to the underlying (unsynchronized) Asio object. + socket_type& inner() noexcept { return socket_; } + + /// Allows access to the underlying (unsynchronized) Asio object. + const socket_type& inner() const noexcept { return socket_; } + + tmc::task is_open() noexcept { + co_await mut_; + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(socket_.is_open()); + TMC_UNREACHABLE; + } + + tmc::task> async_connect(endpoint_type endpoint) { + co_await mut_; + + co_return co_await socket_.async_connect(endpoint, tmc::aw_asio); + } + + // Reads until the buffer sequence is full, EOF, or another error occurs + // (like `asio::async_read`). Unlike the asio composed operation - whose + // intermediate re-initiations would run on the I/O executor, outside the + // mutex - this is implemented as a loop of single-shot reads, so every + // initiation is serialized against other operations on this object. + // + // Only one read may be in flight at a time (the usual asio stream contract). + template + requires requires(socket_type& S, MutableBufferSequence B) { + S.async_read_some(B, tmc::aw_asio); + } + tmc::task> + async_read(MutableBufferSequence buffers) { + std::size_t total = 0; + auto it = tmc::detail::asio_ns::buffer_sequence_begin(buffers); + auto end = tmc::detail::asio_ns::buffer_sequence_end(buffers); + bool started = false; + for (; it != end; ++it) { + tmc::detail::asio_ns::mutable_buffer b = *it; + while (b.size() != 0) { + co_await mut_; + // A cancel() that landed between our single-shot reads (when nothing + // was pending for socket_.cancel() to hit) cleared read_active_. Abort + // here at the chunk boundary so the cancel is never silently dropped. + if (started && !read_active_) { + co_return std::tuple{ + error_code(tmc::detail::asio_ns::error::operation_aborted), total + }; + } + read_active_ = true; + started = true; + auto [ec, n] = co_await socket_.async_read_some(b, tmc::aw_asio); + total += n; + b += n; + if (ec) { + co_return std::tuple{ec, total}; + } + } + } + co_return std::tuple{error_code{}, total}; + } + + template + requires requires(socket_type& S, MutableBufferSequence B) { + S.async_read_some(B, tmc::aw_asio); + } + tmc::task> + async_read_some(MutableBufferSequence buffers) { + co_await mut_; + + co_return co_await socket_.async_read_some(std::move(buffers), tmc::aw_asio); + } + + // Writes the entire buffer sequence unless an error occurs (like + // `asio::async_write`). Unlike the asio composed operation - whose + // intermediate re-initiations would run on the I/O executor, outside the + // mutex - this is implemented as a loop of single-shot writes, so every + // initiation is serialized against other operations on this object. + // + // Only one write may be in flight at a time (the usual asio stream contract). + template + requires requires(socket_type& S, ConstBufferSequence B) { + S.async_write_some(B, tmc::aw_asio); + } + tmc::task> + async_write(ConstBufferSequence buffers) { + std::size_t total = 0; + auto it = tmc::detail::asio_ns::buffer_sequence_begin(buffers); + auto end = tmc::detail::asio_ns::buffer_sequence_end(buffers); + bool started = false; + for (; it != end; ++it) { + tmc::detail::asio_ns::const_buffer b = *it; + while (b.size() != 0) { + co_await mut_; + // A cancel() that landed between our single-shot writes (when nothing + // was pending for socket_.cancel() to hit) cleared write_active_. Abort + // here at the chunk boundary so the cancel is never silently dropped. + if (started && !write_active_) { + co_return std::tuple{ + error_code(tmc::detail::asio_ns::error::operation_aborted), total + }; + } + write_active_ = true; + started = true; + auto [ec, n] = co_await socket_.async_write_some(b, tmc::aw_asio); + total += n; + b += n; + if (ec) { + co_return std::tuple{ec, total}; + } + } + } + co_return std::tuple{error_code{}, total}; + } + + template + requires requires(socket_type& S, ConstBufferSequence B) { + S.async_write_some(B, tmc::aw_asio); + } + tmc::task> + async_write_some(ConstBufferSequence buffers) { + co_await mut_; + + co_return co_await socket_.async_write_some(std::move(buffers), tmc::aw_asio); + } + + tmc::task cancel() { + co_await mut_; + + // Cancel any single-shot operation currently pending on the socket... + error_code ec; + TMC_ASIO_SYNC_DISCARD(socket_.cancel(ec)); + + // ...and, in case a composed async_read()/async_write() is sitting between + // its single-shot operations (where there is nothing pending for the call + // above to hit), signal it to abort when it re-acquires the mutex. + read_active_ = false; + write_active_ = false; + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + tmc::task shutdown(socket_type::shutdown_type how) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(socket_.shutdown(how, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + tmc::task close() { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(socket_.close(ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + tmc::task> async_wait(wait_type w) { + co_await mut_; + + co_return co_await socket_.async_wait(w, tmc::aw_asio); + } + + template + tmc::task> async_send(ConstBufferSequence buffers) { + co_await mut_; + + co_return co_await socket_.async_send(std::move(buffers), tmc::aw_asio); + } + + template + tmc::task> + async_send(ConstBufferSequence buffers, message_flags flags) { + co_await mut_; + + co_return co_await socket_.async_send(std::move(buffers), flags, tmc::aw_asio); + } + + template + tmc::task> + async_receive(MutableBufferSequence buffers) { + co_await mut_; + + co_return co_await socket_.async_receive(std::move(buffers), tmc::aw_asio); + } + + template + tmc::task> + async_receive(MutableBufferSequence buffers, message_flags flags) { + co_await mut_; + + co_return co_await socket_.async_receive(std::move(buffers), flags, tmc::aw_asio); + } + + tmc::task get_executor() { + co_await mut_; + + executor_type ex = socket_.get_executor(); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(std::move(ex)); + TMC_UNREACHABLE; + } + + tmc::task open(protocol_type protocol) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(socket_.open(protocol, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + tmc::task assign(protocol_type protocol, native_handle_type native_socket) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(socket_.assign(protocol, native_socket, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + tmc::task> release() { + co_await mut_; + + error_code ec; + native_handle_type handle = socket_.release(ec); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(std::tuple{ec, handle}); + TMC_UNREACHABLE; + } + + tmc::task bind(endpoint_type endpoint) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(socket_.bind(endpoint, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + template + tmc::task set_option(SettableSocketOption option) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(socket_.set_option(option, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + template + tmc::task> + get_option(GettableSocketOption option) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(socket_.get_option(option, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(std::tuple{ec, std::move(option)}); + TMC_UNREACHABLE; + } + + template + tmc::task> + io_control(IoControlCommand command) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(socket_.io_control(command, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(std::tuple{ec, std::move(command)}); + TMC_UNREACHABLE; + } + + /// Returns the non-blocking mode of the socket. + tmc::task non_blocking() { + co_await mut_; + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(socket_.non_blocking()); + TMC_UNREACHABLE; + } + + tmc::task non_blocking(bool mode) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(socket_.non_blocking(mode, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + tmc::task native_non_blocking() { + co_await mut_; + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(socket_.native_non_blocking()); + TMC_UNREACHABLE; + } + + tmc::task native_non_blocking(bool mode) { + co_await mut_; + + error_code ec; + TMC_ASIO_SYNC_DISCARD(socket_.native_non_blocking(mode, ec)); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(ec); + TMC_UNREACHABLE; + } + + tmc::task> local_endpoint() { + co_await mut_; + + error_code ec; + endpoint_type ep = socket_.local_endpoint(ec); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(std::tuple{ec, std::move(ep)}); + TMC_UNREACHABLE; + } + + tmc::task> remote_endpoint() { + co_await mut_; + + error_code ec; + endpoint_type ep = socket_.remote_endpoint(ec); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(std::tuple{ec, std::move(ep)}); + TMC_UNREACHABLE; + } + + tmc::task> at_mark() { + co_await mut_; + + error_code ec; + bool marked = socket_.at_mark(ec); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(std::tuple{ec, marked}); + TMC_UNREACHABLE; + } + + tmc::task> available() { + co_await mut_; + + error_code ec; + std::size_t n = socket_.available(ec); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(std::tuple{ec, n}); + TMC_UNREACHABLE; + } + + tmc::task native_handle() { + co_await mut_; + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(socket_.native_handle()); + TMC_UNREACHABLE; + } +}; + +template asio_safe_socket(Socket) -> asio_safe_socket; + +} // namespace tmc diff --git a/include/tmc/asio/safe_timer.hpp b/include/tmc/asio/safe_timer.hpp new file mode 100644 index 00000000..f0c15ff1 --- /dev/null +++ b/include/tmc/asio/safe_timer.hpp @@ -0,0 +1,156 @@ +// Copyright (c) 2023-2026 Logan McDougall +// +// Distributed under the Boost Software License, Version 1.0. (See accompanying +// file LICENSE or copy at http://www.boost.org/LICENSE_1_0.txt) + +#pragma once + +#include "tmc/asio/aw_asio.hpp" +#include "tmc/detail/compat.hpp" +#include "tmc/task.hpp" + +#include "tmc/detail/tiny_mutex.hpp" + +#ifdef TMC_USE_BOOST_ASIO +#include +#include +#else +#include +#include +#endif + +#include +#include +#include + +namespace tmc { +namespace detail { +#ifdef TMC_USE_BOOST_ASIO +namespace asio_ns = ::boost::asio; +#else +namespace asio_ns = ::asio; +#endif +} // namespace detail + +/// Type that serializes Asio timer operations so expiry updates and waits can be +/// initiated safely from different coroutines. Unlike a strand, this only serializes the +/// initiation of operations; it does not serialize full handlers. +/// +/// Methods behave exactly as the underlying object's methods with the same name, except: +/// - methods are thread-safe +/// - methods implicitly use the `tmc::aw_asio` completion +/// +/// The asio_safe_timer must outlive every task that uses it, including any task still +/// waiting to acquire its mutex. Destroying it while such tasks exist is a +/// use-after-free. +class asio_safe_timer { +public: + using timer_type = tmc::detail::asio_ns::steady_timer; +#ifdef TMC_USE_BOOST_ASIO + using error_code = boost::system::error_code; +#else + using error_code = asio::error_code; +#endif + using duration = timer_type::duration; + using time_point = timer_type::time_point; + using executor_type = timer_type::executor_type; + +private: + timer_type timer_; + tmc::tiny_mutex mut_; + +public: + /// Constructs this from an Asio steady_timer. + explicit asio_safe_timer(timer_type timer) : timer_(std::move(timer)) {} + + /// Allows access to the underlying (unsynchronized) Asio object. + timer_type& inner() noexcept { return timer_; } + /// Allows access to the underlying (unsynchronized) Asio object. + const timer_type& inner() const noexcept { return timer_; } + + tmc::task> async_wait() { + co_await mut_; + + co_return co_await timer_.async_wait(tmc::aw_asio); + } + + /// Combines expires_after and async_wait. Changing the expiry cancels + /// every outstanding wait on this timer before the new wait begins; those + /// cancelled waits complete with operation_aborted. + tmc::task> async_wait_for(duration expiry) { + co_await mut_; + + timer_.expires_after(expiry); + co_return co_await timer_.async_wait(tmc::aw_asio); + } + + /// Combines expires_at and async_wait. Like async_wait_for, changing + /// the expiry cancels every outstanding wait before the new wait begins; those + /// cancelled waits complete with operation_aborted. + tmc::task> async_wait_until(time_point expiry) { + co_await mut_; + + timer_.expires_at(expiry); + co_return co_await timer_.async_wait(tmc::aw_asio); + } + + tmc::task cancel() { + co_await mut_; + + std::size_t count = timer_.cancel(); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(count); + TMC_UNREACHABLE; + } + + tmc::task cancel_one() { + co_await mut_; + + std::size_t count = timer_.cancel_one(); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(count); + TMC_UNREACHABLE; + } + + tmc::task expiry() { + co_await mut_; + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(timer_.expiry()); + TMC_UNREACHABLE; + } + + tmc::task expires_at(time_point expiry) { + co_await mut_; + + std::size_t count = timer_.expires_at(expiry); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(count); + TMC_UNREACHABLE; + } + + tmc::task expires_after(duration expiry) { + co_await mut_; + + std::size_t count = timer_.expires_after(expiry); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(count); + TMC_UNREACHABLE; + } + + tmc::task get_executor() { + co_await mut_; + + executor_type ex = timer_.get_executor(); + + // Manual unlock is required since this coro didn't suspend + co_await mut_.co_unlock_return(std::move(ex)); + TMC_UNREACHABLE; + } +}; + +} // namespace tmc diff --git a/include/tmc/detail/compat.hpp b/include/tmc/detail/compat.hpp index 4454277c..1be8b690 100644 --- a/include/tmc/detail/compat.hpp +++ b/include/tmc/detail/compat.hpp @@ -297,3 +297,15 @@ static_assert(std::atomic::is_always_lock_free); #else #define TMC_AWAIT_RESUME #endif + +// Marks a point that control flow can never reach. +// std::unreachable() requires C++23; fall back to intrinsics on C++20. +#include +#if defined(__cpp_lib_unreachable) && __cpp_lib_unreachable >= 202202L +#include +#define TMC_UNREACHABLE std::unreachable() +#elif defined(_MSC_VER) && !defined(__clang__) +#define TMC_UNREACHABLE __assume(false) +#else +#define TMC_UNREACHABLE __builtin_unreachable() +#endif diff --git a/include/tmc/detail/tiny_mutex.hpp b/include/tmc/detail/tiny_mutex.hpp new file mode 100644 index 00000000..2e25c286 --- /dev/null +++ b/include/tmc/detail/tiny_mutex.hpp @@ -0,0 +1,329 @@ +// Copyright (c) 2023-2026 Logan McDougall +// +// Distributed under the Boost Software License, Version 1.0. (See accompanying +// file LICENSE or copy at http://www.boost.org/LICENSE_1_0.txt) + +#pragma once + +#include "tmc/aw_resume_on.hpp" +#include "tmc/aw_yield.hpp" +#include "tmc/detail/concepts_awaitable.hpp" +#include "tmc/detail/thread_locals.hpp" +#include "tmc/ex_any.hpp" +#include "tmc/task.hpp" + +#include +#include +#include +#include +#include + +namespace tmc { +class tiny_mutex; + +namespace detail { +struct tiny_mutex_waiter { + tiny_mutex_waiter* next; + std::coroutine_handle<> continuation; + tmc::ex_any* continuation_executor; + size_t continuation_priority; +}; + +struct tiny_mutex_state { + static inline constexpr uintptr_t RUNNING = 0x1; + + std::atomic waiters; + std::atomic refs; + + inline tiny_mutex_state() noexcept : waiters{0}, refs{1} {} +}; + +// Ensure that it's safe to use pointer tagging to synchronize. +static_assert(alignof(tiny_mutex_waiter) >= 2); + +[[nodiscard]] inline bool tiny_mutex_running(uintptr_t Value) noexcept { + return 0 != (Value & tiny_mutex_state::RUNNING); +} + +[[nodiscard]] inline tiny_mutex_waiter* tiny_mutex_waiters(uintptr_t Value) noexcept { + return reinterpret_cast(Value & ~tiny_mutex_state::RUNNING); +} + +inline void release_tiny_mutex_state(tiny_mutex_state* State) noexcept { + if (State->refs.fetch_sub(1, std::memory_order_acq_rel) == 1) { + assert(State->waiters.load(std::memory_order_acquire) == 0); + delete State; + } +} + +template +using tiny_mutex_return_storage_t = std::conditional_t< + std::is_lvalue_reference_v, Result, std::remove_cvref_t>; + +} // namespace detail + +class [[nodiscard("You must co_await aw_tiny_mutex_lock for it to have any effect.")]] +aw_tiny_mutex_lock : tmc::detail::AwaitTagNoGroupAsIs { + tmc::detail::tiny_mutex_waiter me; + std::atomic parent; + + friend class tiny_mutex; + + inline aw_tiny_mutex_lock(tiny_mutex& Parent) noexcept : parent(&Parent) {} + +public: + inline bool await_ready() noexcept { return false; } + + std::coroutine_handle<> await_suspend(std::coroutine_handle<> Outer) noexcept; + + inline void await_resume() noexcept {} + + aw_tiny_mutex_lock(aw_tiny_mutex_lock const&) = delete; + aw_tiny_mutex_lock& operator=(aw_tiny_mutex_lock const&) = delete; + aw_tiny_mutex_lock(aw_tiny_mutex_lock&&) = delete; + aw_tiny_mutex_lock& operator=(aw_tiny_mutex_lock&&) = delete; +}; + +template +class [[nodiscard( + "You must co_await aw_tiny_mutex_co_unlock_return for it to have any " + "effect." +)]] aw_tiny_mutex_co_unlock_return : tmc::detail::AwaitTagNoGroupAsIs { + + // Store lvalues by reference. Move rvalues into this. + using ReturnValueStorage = std::conditional_t< + std::is_lvalue_reference_v, Result, std::remove_cvref_t>; + + // Handle value return and void return. + struct empty {}; + using ResultStorage = + std::conditional_t, empty, ReturnValueStorage>; + TMC_NO_UNIQUE_ADDRESS ResultStorage result; + + friend class tiny_mutex; + + template + inline explicit aw_tiny_mutex_co_unlock_return(ResultArg&& ResultIn) noexcept + : result(static_cast(ResultIn)) {} + + inline aw_tiny_mutex_co_unlock_return() noexcept {} + +public: + inline bool await_ready() noexcept { return false; } + + template void await_suspend(std::coroutine_handle

Outer) noexcept { + if constexpr (std::is_void_v) { + Outer.promise().return_void(); + } else { + Outer.promise().return_value(static_cast(result)); + } + Outer.promise().customizer.post_continuation(Outer); + } + + // Never runs; post_continuation destroys this coroutine. + [[maybe_unused]] inline void await_resume() noexcept {} + + aw_tiny_mutex_co_unlock_return(aw_tiny_mutex_co_unlock_return const&) = delete; + aw_tiny_mutex_co_unlock_return& + operator=(aw_tiny_mutex_co_unlock_return const&) = delete; + aw_tiny_mutex_co_unlock_return(aw_tiny_mutex_co_unlock_return&&) = delete; + aw_tiny_mutex_co_unlock_return& operator=(aw_tiny_mutex_co_unlock_return&&) = delete; +}; + +/// A serializing primitive similar to `tmc::mutex`, except ownership ends when +/// the acquiring coroutine next suspends. This makes it suitable for protecting +/// short, synchronous stretches of coroutine execution without carrying the +/// lock across later awaits. +class tiny_mutex { + friend class aw_tiny_mutex_lock; + + tmc::detail::tiny_mutex_state* state; + + std::coroutine_handle<> enqueue(tmc::detail::tiny_mutex_waiter& Waiter) noexcept; + + static tmc::task run_loop(tmc::detail::tiny_mutex_state* State); + +public: + inline tiny_mutex() noexcept : state(new tmc::detail::tiny_mutex_state) {} + + /// Move construction transfers ownership of the shared state. The refcount is + /// unchanged (ownership moves, it is not shared). Do not move a mutex while + /// another thread may be concurrently locking it. + inline tiny_mutex(tiny_mutex&& Other) noexcept : state(Other.state) { + Other.state = nullptr; + } + + /// Move assignment releases this mutex's current state (following the same + /// "no queued waiters" contract as destruction) and adopts Other's. Do not + /// move a mutex while another thread may be concurrently locking either one. + inline tiny_mutex& operator=(tiny_mutex&& Other) noexcept { + if (this == &Other) { + return *this; + } + if (state != nullptr) { + // 0 (no waiters) or 1 (a runner is active with an empty queue) are valid. + assert(state->waiters.load(std::memory_order_acquire) < 2); + tmc::detail::release_tiny_mutex_state(state); + } + state = Other.state; + Other.state = nullptr; + return *this; + } + + /// Returns true if a runner is currently executing queued work for the mutex. + /// This value is not guaranteed to be consistent with any other operation. + inline bool is_locked() noexcept { + return tmc::detail::tiny_mutex_running( + state->waiters.load(std::memory_order_relaxed) + ); + } + + /// Suspend this coroutine and resubmit it to its current executor. Since the + /// lock is owned by the runner rather than the caller, this releases the + /// mutex before the coroutine resumes later. + inline aw_yield co_unlock() noexcept { return tmc::yield(); } + + /// Completes this coroutine immediately, returns value to its parent + /// coroutine, and resubmits the parent to its current executor. Since the + /// lock is owned by the runner rather than the caller, this releases the + /// mutex before the coroutine resumes later. + /// + /// The purpose of this is to skip a round-trip through the executor when + /// you want to unlock this mutex immediately before returning. + /// + /// ``` + /// // You can replace this: + /// co_await mut.co_unlock(); + /// co_return result; + /// + /// // With this: + /// co_await mut.co_unlock_return(result); + /// TMC_UNREACHABLE; + /// ``` + template + inline aw_tiny_mutex_co_unlock_return + co_unlock_return(Result&& result) noexcept { + return aw_tiny_mutex_co_unlock_return(static_cast(result)); + } + + /// Completes this coroutine immediately and resubmits the parent to its + /// current executor. Since the lock is owned by the runner rather than the + /// caller, this releases the mutex before the coroutine resumes later. + /// + /// The purpose of this is to skip a round-trip through the executor when + /// you want to unlock this mutex immediately before returning. + /// + /// ``` + /// // You can replace this: + /// co_await mut.co_unlock(); + /// co_return; + /// + /// // With this: + /// co_await mut.co_unlock_return(); + /// TMC_UNREACHABLE; + /// ``` + inline aw_tiny_mutex_co_unlock_return co_unlock_return() noexcept { + return aw_tiny_mutex_co_unlock_return(); + } + + /// Queue this coroutine to run under the mutex until it next suspends. + inline aw_tiny_mutex_lock operator co_await() noexcept { + return aw_tiny_mutex_lock(*this); + } + + /// Destruction is only valid once all queued work has completed and no + /// runner is active. + ~tiny_mutex(); + +private: + tiny_mutex(tiny_mutex const& Other) = delete; + tiny_mutex& operator=(tiny_mutex const& Other) = delete; +}; + +inline std::coroutine_handle<> +aw_tiny_mutex_lock::await_suspend(std::coroutine_handle<> Outer) noexcept { + auto* mutex = parent.load(std::memory_order_acquire); + me.continuation = Outer; + me.continuation_executor = tmc::detail::this_thread::executor(); + me.continuation_priority = tmc::detail::this_thread::this_task().prio; + return mutex->enqueue(me); +} + +inline std::coroutine_handle<> +tiny_mutex::enqueue(tmc::detail::tiny_mutex_waiter& Waiter) noexcept { + auto* State = state; + uintptr_t head = State->waiters.load(std::memory_order_acquire); + uintptr_t desired; + do { + Waiter.next = tmc::detail::tiny_mutex_waiters(head); + desired = + reinterpret_cast(&Waiter) | tmc::detail::tiny_mutex_state::RUNNING; + } while (!State->waiters.compare_exchange_strong( + head, desired, std::memory_order_acq_rel, std::memory_order_acquire + )); + + if (tmc::detail::tiny_mutex_running(head)) { + return std::noop_coroutine(); + } + + // No runner existed prior to the CAS above, so this await_suspend path + // cannot be resumed until we return the new runner handle. + return static_cast>(run_loop(State)); +} + +inline tmc::task tiny_mutex::run_loop(tmc::detail::tiny_mutex_state* State) { + State->refs.fetch_add(1, std::memory_order_relaxed); + while (true) { + auto stateWord = State->waiters.exchange( + tmc::detail::tiny_mutex_state::RUNNING, std::memory_order_acq_rel + ); + auto* curr = tmc::detail::tiny_mutex_waiters(stateWord); + if (curr == nullptr) { + uintptr_t expected = tmc::detail::tiny_mutex_state::RUNNING; + if (State->waiters.compare_exchange_strong( + expected, 0, std::memory_order_acq_rel, std::memory_order_acquire + )) { + break; + } + continue; + } + + while (curr != nullptr) { + auto* next = curr->next; + auto continuation = curr->continuation; + tmc::ex_any* continuationExecutor = curr->continuation_executor; + auto continuationPriority = curr->continuation_priority; + + co_await tmc::resume_on(continuationExecutor).with_priority(continuationPriority); + + continuation.resume(); + curr = next; + } + } + tmc::detail::release_tiny_mutex_state(State); +} + +inline tiny_mutex::~tiny_mutex() { + auto* State = state; + if (State == nullptr) { + return; // moved-from + } + // 0 (no waiters) or 1 (this is the running task) are valid + assert(State->waiters.load(std::memory_order_acquire) < 2); + tmc::detail::release_tiny_mutex_state(State); +} + +namespace detail { +template <> struct awaitable_traits { + static constexpr configure_mode mode = WRAPPER; + + using result_type = void; + using self_type = tmc::tiny_mutex; + using awaiter_type = tmc::aw_tiny_mutex_lock; + + static awaiter_type get_awaiter(self_type& Awaitable) noexcept { + return Awaitable.operator co_await(); + } +}; +} // namespace detail +} // namespace tmc