diff options
Diffstat (limited to '3rdparty/asio/include/asio/read_at.hpp')
-rw-r--r-- | 3rdparty/asio/include/asio/read_at.hpp | 247 |
1 files changed, 177 insertions, 70 deletions
diff --git a/3rdparty/asio/include/asio/read_at.hpp b/3rdparty/asio/include/asio/read_at.hpp index 16e6af1568c..09a0b22e12e 100644 --- a/3rdparty/asio/include/asio/read_at.hpp +++ b/3rdparty/asio/include/asio/read_at.hpp @@ -2,7 +2,7 @@ // read_at.hpp // ~~~~~~~~~~~ // -// Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// Copyright (c) 2003-2024 Christopher M. Kohlhoff (chris at kohlhoff dot com) // // Distributed under the Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) @@ -18,6 +18,7 @@ #include "asio/detail/config.hpp" #include <cstddef> #include "asio/async_result.hpp" +#include "asio/completion_condition.hpp" #include "asio/detail/cstdint.hpp" #include "asio/error.hpp" @@ -28,12 +29,20 @@ #include "asio/detail/push_options.hpp" namespace asio { +namespace detail { + +template <typename> class initiate_async_read_at; +#if !defined(ASIO_NO_IOSTREAM) +template <typename> class initiate_async_read_at_streambuf; +#endif // !defined(ASIO_NO_IOSTREAM) + +} // namespace detail /** * @defgroup read_at asio::read_at * - * @brief Attempt to read a certain amount of data at the specified offset - * before returning. + * @brief The @c read_at function is a composed operation that reads a certain + * amount of data at the specified offset before returning. */ /*@{*/ @@ -394,8 +403,8 @@ std::size_t read_at(SyncRandomAccessReadDevice& d, /** * @defgroup async_read_at asio::async_read_at * - * @brief Start an asynchronous operation to read a certain amount of data at - * the specified offset. + * @brief The @c async_read_at function is a composed asynchronous operation + * that reads a certain amount of data at the specified offset. */ /*@{*/ @@ -403,9 +412,10 @@ std::size_t read_at(SyncRandomAccessReadDevice& d, /// specified offset. /** * This function is used to asynchronously read a certain number of bytes of - * data from a random access device at the specified offset. The function call - * always returns immediately. The asynchronous operation will continue until - * one of the following conditions is true: + * data from a random access device at the specified offset. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. The asynchronous operation will continue until one of the + * following conditions is true: * * @li The supplied buffers are full. That is, the bytes transferred is equal to * the sum of the buffer sizes. @@ -424,11 +434,13 @@ std::size_t read_at(SyncRandomAccessReadDevice& d, * of the buffer sizes indicates the maximum number of bytes to read from the * device. Although the buffers object may be copied as necessary, ownership of * the underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const asio::error_code& error, @@ -439,9 +451,12 @@ std::size_t read_at(SyncRandomAccessReadDevice& d, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. Invocation of - * the handler will be performed in a manner equivalent to using - * asio::io_context::post(). + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a + * manner equivalent to using asio::post(). + * + * @par Completion Signature + * @code void(asio::error_code, std::size_t) @endcode * * @par Example * To read into a single data buffer use the @ref buffer function as follows: @@ -457,22 +472,40 @@ std::size_t read_at(SyncRandomAccessReadDevice& d, * d, 42, buffers, * asio::transfer_all(), * handler); @endcode + * + * @par Per-Operation Cancellation + * This asynchronous operation supports cancellation for the following + * asio::cancellation_type values: + * + * @li @c cancellation_type::terminal + * + * @li @c cancellation_type::partial + * + * if they are also supported by the @c AsyncRandomAccessReadDevice type's + * async_read_some_at operation. */ template <typename AsyncRandomAccessReadDevice, typename MutableBufferSequence, - typename ReadHandler> -ASIO_INITFN_RESULT_TYPE(ReadHandler, - void (asio::error_code, std::size_t)) -async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, - const MutableBufferSequence& buffers, - ASIO_MOVE_ARG(ReadHandler) handler); + ASIO_COMPLETION_TOKEN_FOR(void (asio::error_code, + std::size_t)) ReadToken = default_completion_token_t< + typename AsyncRandomAccessReadDevice::executor_type>> +auto async_read_at(AsyncRandomAccessReadDevice& d, + uint64_t offset, const MutableBufferSequence& buffers, + ReadToken&& token = default_completion_token_t< + typename AsyncRandomAccessReadDevice::executor_type>()) + -> decltype( + async_initiate<ReadToken, + void (asio::error_code, std::size_t)>( + declval<detail::initiate_async_read_at<AsyncRandomAccessReadDevice>>(), + token, offset, buffers, transfer_all())); /// Start an asynchronous operation to read a certain amount of data at the /// specified offset. /** * This function is used to asynchronously read a certain number of bytes of - * data from a random access device at the specified offset. The function call - * always returns immediately. The asynchronous operation will continue until - * one of the following conditions is true: + * data from a random access device at the specified offset. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. The asynchronous operation will continue until one of the + * following conditions is true: * * @li The supplied buffers are full. That is, the bytes transferred is equal to * the sum of the buffer sizes. @@ -488,7 +521,7 @@ async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, * of the buffer sizes indicates the maximum number of bytes to read from the * device. Although the buffers object may be copied as necessary, ownership of * the underlying memory blocks is retained by the caller, which must guarantee - * that they remain valid until the handler is called. + * that they remain valid until the completion handler is called. * * @param completion_condition The function object to be called to determine * whether the read operation is complete. The signature of the function object @@ -504,9 +537,11 @@ async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, * return value indicates the maximum number of bytes to be read on the next * call to the device's async_read_some_at function. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const asio::error_code& error, @@ -517,9 +552,12 @@ async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. Invocation of - * the handler will be performed in a manner equivalent to using - * asio::io_context::post(). + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a + * manner equivalent to using asio::post(). + * + * @par Completion Signature + * @code void(asio::error_code, std::size_t) @endcode * * @par Example * To read into a single data buffer use the @ref buffer function as follows: @@ -530,15 +568,34 @@ async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, * See the @ref buffer documentation for information on reading into multiple * buffers in one go, and how to use it with arrays, boost::array or * std::vector. + * + * @par Per-Operation Cancellation + * This asynchronous operation supports cancellation for the following + * asio::cancellation_type values: + * + * @li @c cancellation_type::terminal + * + * @li @c cancellation_type::partial + * + * if they are also supported by the @c AsyncRandomAccessReadDevice type's + * async_read_some_at operation. */ -template <typename AsyncRandomAccessReadDevice, typename MutableBufferSequence, - typename CompletionCondition, typename ReadHandler> -ASIO_INITFN_RESULT_TYPE(ReadHandler, - void (asio::error_code, std::size_t)) -async_read_at(AsyncRandomAccessReadDevice& d, +template <typename AsyncRandomAccessReadDevice, + typename MutableBufferSequence, typename CompletionCondition, + ASIO_COMPLETION_TOKEN_FOR(void (asio::error_code, + std::size_t)) ReadToken = default_completion_token_t< + typename AsyncRandomAccessReadDevice::executor_type>> +auto async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, const MutableBufferSequence& buffers, CompletionCondition completion_condition, - ASIO_MOVE_ARG(ReadHandler) handler); + ReadToken&& token = default_completion_token_t< + typename AsyncRandomAccessReadDevice::executor_type>()) + -> decltype( + async_initiate<ReadToken, + void (asio::error_code, std::size_t)>( + declval<detail::initiate_async_read_at<AsyncRandomAccessReadDevice>>(), + token, offset, buffers, + static_cast<CompletionCondition&&>(completion_condition))); #if !defined(ASIO_NO_EXTENSIONS) #if !defined(ASIO_NO_IOSTREAM) @@ -547,9 +604,10 @@ async_read_at(AsyncRandomAccessReadDevice& d, /// specified offset. /** * This function is used to asynchronously read a certain number of bytes of - * data from a random access device at the specified offset. The function call - * always returns immediately. The asynchronous operation will continue until - * one of the following conditions is true: + * data from a random access device at the specified offset. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. The asynchronous operation will continue until one of the + * following conditions is true: * * @li An error occurred. * @@ -563,11 +621,13 @@ async_read_at(AsyncRandomAccessReadDevice& d, * * @param b A basic_streambuf object into which the data will be read. Ownership * of the streambuf is retained by the caller, which must guarantee that it - * remains valid until the handler is called. + * remains valid until the completion handler is called. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const asio::error_code& error, @@ -578,30 +638,53 @@ async_read_at(AsyncRandomAccessReadDevice& d, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. Invocation of - * the handler will be performed in a manner equivalent to using - * asio::io_context::post(). + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a + * manner equivalent to using asio::post(). + * + * @par Completion Signature + * @code void(asio::error_code, std::size_t) @endcode * * @note This overload is equivalent to calling: * @code asio::async_read_at( * d, 42, b, * asio::transfer_all(), * handler); @endcode + * + * @par Per-Operation Cancellation + * This asynchronous operation supports cancellation for the following + * asio::cancellation_type values: + * + * @li @c cancellation_type::terminal + * + * @li @c cancellation_type::partial + * + * if they are also supported by the @c AsyncRandomAccessReadDevice type's + * async_read_some_at operation. */ template <typename AsyncRandomAccessReadDevice, typename Allocator, - typename ReadHandler> -ASIO_INITFN_RESULT_TYPE(ReadHandler, - void (asio::error_code, std::size_t)) -async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, - basic_streambuf<Allocator>& b, ASIO_MOVE_ARG(ReadHandler) handler); + ASIO_COMPLETION_TOKEN_FOR(void (asio::error_code, + std::size_t)) ReadToken = default_completion_token_t< + typename AsyncRandomAccessReadDevice::executor_type>> +auto async_read_at(AsyncRandomAccessReadDevice& d, + uint64_t offset, basic_streambuf<Allocator>& b, + ReadToken&& token = default_completion_token_t< + typename AsyncRandomAccessReadDevice::executor_type>()) + -> decltype( + async_initiate<ReadToken, + void (asio::error_code, std::size_t)>( + declval<detail::initiate_async_read_at_streambuf< + AsyncRandomAccessReadDevice>>(), + token, offset, &b, transfer_all())); /// Start an asynchronous operation to read a certain amount of data at the /// specified offset. /** * This function is used to asynchronously read a certain number of bytes of - * data from a random access device at the specified offset. The function call - * always returns immediately. The asynchronous operation will continue until - * one of the following conditions is true: + * data from a random access device at the specified offset. It is an + * initiating function for an @ref asynchronous_operation, and always returns + * immediately. The asynchronous operation will continue until one of the + * following conditions is true: * * @li The completion_condition function object returns 0. * @@ -615,7 +698,7 @@ async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, * * @param b A basic_streambuf object into which the data will be read. Ownership * of the streambuf is retained by the caller, which must guarantee that it - * remains valid until the handler is called. + * remains valid until the completion handler is called. * * @param completion_condition The function object to be called to determine * whether the read operation is complete. The signature of the function object @@ -631,9 +714,11 @@ async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, * return value indicates the maximum number of bytes to be read on the next * call to the device's async_read_some_at function. * - * @param handler The handler to be called when the read operation completes. - * Copies will be made of the handler as required. The function signature of the - * handler must be: + * @param token The @ref completion_token that will be used to produce a + * completion handler, which will be called when the read completes. + * Potential completion tokens include @ref use_future, @ref use_awaitable, + * @ref yield_context, or a function object with the correct completion + * signature. The function signature of the completion handler must be: * @code void handler( * // Result of operation. * const asio::error_code& error, @@ -644,18 +729,40 @@ async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, * std::size_t bytes_transferred * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. Invocation of - * the handler will be performed in a manner equivalent to using - * asio::io_context::post(). + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a + * manner equivalent to using asio::post(). + * + * @par Completion Signature + * @code void(asio::error_code, std::size_t) @endcode + * + * @par Per-Operation Cancellation + * This asynchronous operation supports cancellation for the following + * asio::cancellation_type values: + * + * @li @c cancellation_type::terminal + * + * @li @c cancellation_type::partial + * + * if they are also supported by the @c AsyncRandomAccessReadDevice type's + * async_read_some_at operation. */ -template <typename AsyncRandomAccessReadDevice, typename Allocator, - typename CompletionCondition, typename ReadHandler> -ASIO_INITFN_RESULT_TYPE(ReadHandler, - void (asio::error_code, std::size_t)) -async_read_at(AsyncRandomAccessReadDevice& d, - uint64_t offset, basic_streambuf<Allocator>& b, - CompletionCondition completion_condition, - ASIO_MOVE_ARG(ReadHandler) handler); +template <typename AsyncRandomAccessReadDevice, + typename Allocator, typename CompletionCondition, + ASIO_COMPLETION_TOKEN_FOR(void (asio::error_code, + std::size_t)) ReadToken = default_completion_token_t< + typename AsyncRandomAccessReadDevice::executor_type>> +auto async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset, + basic_streambuf<Allocator>& b, CompletionCondition completion_condition, + ReadToken&& token = default_completion_token_t< + typename AsyncRandomAccessReadDevice::executor_type>()) + -> decltype( + async_initiate<ReadToken, + void (asio::error_code, std::size_t)>( + declval<detail::initiate_async_read_at_streambuf< + AsyncRandomAccessReadDevice>>(), + token, offset, &b, + static_cast<CompletionCondition&&>(completion_condition))); #endif // !defined(ASIO_NO_IOSTREAM) #endif // !defined(ASIO_NO_EXTENSIONS) |