diff options
Diffstat (limited to '3rdparty/asio/include/asio/write_at.hpp')
-rw-r--r-- | 3rdparty/asio/include/asio/write_at.hpp | 246 |
1 files changed, 179 insertions, 67 deletions
diff --git a/3rdparty/asio/include/asio/write_at.hpp b/3rdparty/asio/include/asio/write_at.hpp index 17227748964..a33514e61a0 100644 --- a/3rdparty/asio/include/asio/write_at.hpp +++ b/3rdparty/asio/include/asio/write_at.hpp @@ -2,7 +2,7 @@ // write_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,11 +29,20 @@ #include "asio/detail/push_options.hpp" namespace asio { +namespace detail { + +template <typename> class initiate_async_write_at; +#if !defined(ASIO_NO_IOSTREAM) +template <typename> class initiate_async_write_at_streambuf; +#endif // !defined(ASIO_NO_IOSTREAM) + +} // namespace detail /** * @defgroup write_at asio::write_at * - * @brief Write a certain amount of data at a specified offset before returning. + * @brief The @c write_at function is a composed operation that writes a + * certain amount of data at a specified offset before returning. */ /*@{*/ @@ -392,8 +402,9 @@ std::size_t write_at(SyncRandomAccessWriteDevice& d, uint64_t offset, /** * @defgroup async_write_at asio::async_write_at * - * @brief Start an asynchronous operation to write a certain amount of data at - * the specified offset. + * @brief The @c async_write_at function is a composed asynchronous operation + * that writes a certain amount of data at the specified offset before + * completion. */ /*@{*/ @@ -401,9 +412,10 @@ std::size_t write_at(SyncRandomAccessWriteDevice& d, uint64_t offset, /// specified offset. /** * This function is used to asynchronously write a certain number of bytes of - * data to a random access device at a specified offset. The function call - * always returns immediately. The asynchronous operation will continue until - * one of the following conditions is true: + * data to a random access device at a 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 All of the data in the supplied buffers has been written. That is, the * bytes transferred is equal to the sum of the buffer sizes. @@ -426,11 +438,13 @@ std::size_t write_at(SyncRandomAccessWriteDevice& d, uint64_t offset, * @param buffers One or more buffers containing the data to be written. * 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 write 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 write 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, @@ -440,9 +454,12 @@ std::size_t write_at(SyncRandomAccessWriteDevice& 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 write a single data buffer use the @ref buffer function as follows: @@ -452,22 +469,41 @@ std::size_t write_at(SyncRandomAccessWriteDevice& d, uint64_t offset, * See the @ref buffer documentation for information on writing 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 AsyncRandomAccessWriteDevice type's + * async_write_some_at operation. */ template <typename AsyncRandomAccessWriteDevice, typename ConstBufferSequence, - typename WriteHandler> -ASIO_INITFN_RESULT_TYPE(WriteHandler, - void (asio::error_code, std::size_t)) -async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, - const ConstBufferSequence& buffers, - ASIO_MOVE_ARG(WriteHandler) handler); + ASIO_COMPLETION_TOKEN_FOR(void (asio::error_code, + std::size_t)) WriteToken = default_completion_token_t< + typename AsyncRandomAccessWriteDevice::executor_type>> +auto async_write_at(AsyncRandomAccessWriteDevice& d, + uint64_t offset, const ConstBufferSequence& buffers, + WriteToken&& token = default_completion_token_t< + typename AsyncRandomAccessWriteDevice::executor_type>()) + -> decltype( + async_initiate<WriteToken, + void (asio::error_code, std::size_t)>( + declval<detail::initiate_async_write_at< + AsyncRandomAccessWriteDevice>>(), + token, offset, buffers, transfer_all())); /// Start an asynchronous operation to write a certain amount of data at the /// specified offset. /** * This function is used to asynchronously write a certain number of bytes of - * data to a random access device at a specified offset. The function call - * always returns immediately. The asynchronous operation will continue until - * one of the following conditions is true: + * data to a random access device at a 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 All of the data in the supplied buffers has been written. That is, the * bytes transferred is equal to the sum of the buffer sizes. @@ -490,7 +526,7 @@ async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, * @param buffers One or more buffers containing the data to be written. * 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 write operation is complete. The signature of the function object @@ -506,9 +542,11 @@ async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, * non-zero return value indicates the maximum number of bytes to be written on * the next call to the device's async_write_some_at function. * - * @param handler The handler to be called when the write 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 write 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, @@ -518,9 +556,12 @@ async_write_at(AsyncRandomAccessWriteDevice& 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 write a single data buffer use the @ref buffer function as follows: @@ -531,15 +572,35 @@ async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, * See the @ref buffer documentation for information on writing 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 AsyncRandomAccessWriteDevice type's + * async_write_some_at operation. */ -template <typename AsyncRandomAccessWriteDevice, typename ConstBufferSequence, - typename CompletionCondition, typename WriteHandler> -ASIO_INITFN_RESULT_TYPE(WriteHandler, - void (asio::error_code, std::size_t)) -async_write_at(AsyncRandomAccessWriteDevice& d, +template <typename AsyncRandomAccessWriteDevice, + typename ConstBufferSequence, typename CompletionCondition, + ASIO_COMPLETION_TOKEN_FOR(void (asio::error_code, + std::size_t)) WriteToken = default_completion_token_t< + typename AsyncRandomAccessWriteDevice::executor_type>> +auto async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, const ConstBufferSequence& buffers, CompletionCondition completion_condition, - ASIO_MOVE_ARG(WriteHandler) handler); + WriteToken&& token = default_completion_token_t< + typename AsyncRandomAccessWriteDevice::executor_type>()) + -> decltype( + async_initiate<WriteToken, + void (asio::error_code, std::size_t)>( + declval<detail::initiate_async_write_at< + AsyncRandomAccessWriteDevice>>(), + token, offset, buffers, + static_cast<CompletionCondition&&>(completion_condition))); #if !defined(ASIO_NO_EXTENSIONS) #if !defined(ASIO_NO_IOSTREAM) @@ -548,9 +609,10 @@ async_write_at(AsyncRandomAccessWriteDevice& d, /// specified offset. /** * This function is used to asynchronously write a certain number of bytes of - * data to a random access device at a specified offset. The function call - * always returns immediately. The asynchronous operation will continue until - * one of the following conditions is true: + * data to a random access device at a 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 All of the data in the supplied basic_streambuf has been written. * @@ -571,11 +633,13 @@ async_write_at(AsyncRandomAccessWriteDevice& d, * * @param b A basic_streambuf object from which data will be written. 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 write 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 write 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, @@ -585,24 +649,47 @@ async_write_at(AsyncRandomAccessWriteDevice& 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 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 AsyncRandomAccessWriteDevice type's + * async_write_some_at operation. */ template <typename AsyncRandomAccessWriteDevice, typename Allocator, - typename WriteHandler> -ASIO_INITFN_RESULT_TYPE(WriteHandler, - void (asio::error_code, std::size_t)) -async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, - basic_streambuf<Allocator>& b, ASIO_MOVE_ARG(WriteHandler) handler); + ASIO_COMPLETION_TOKEN_FOR(void (asio::error_code, + std::size_t)) WriteToken = default_completion_token_t< + typename AsyncRandomAccessWriteDevice::executor_type>> +auto async_write_at(AsyncRandomAccessWriteDevice& d, + uint64_t offset, basic_streambuf<Allocator>& b, + WriteToken&& token = default_completion_token_t< + typename AsyncRandomAccessWriteDevice::executor_type>()) + -> decltype( + async_initiate<WriteToken, + void (asio::error_code, std::size_t)>( + declval<detail::initiate_async_write_at_streambuf< + AsyncRandomAccessWriteDevice>>(), + token, offset, &b, transfer_all())); /// Start an asynchronous operation to write a certain amount of data at the /// specified offset. /** * This function is used to asynchronously write a certain number of bytes of - * data to a random access device at a specified offset. The function call - * always returns immediately. The asynchronous operation will continue until - * one of the following conditions is true: + * data to a random access device at a 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 All of the data in the supplied basic_streambuf has been written. * @@ -623,7 +710,7 @@ async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, * * @param b A basic_streambuf object from which data will be written. 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 write operation is complete. The signature of the function object @@ -639,9 +726,11 @@ async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, * non-zero return value indicates the maximum number of bytes to be written on * the next call to the device's async_write_some_at function. * - * @param handler The handler to be called when the write 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 write 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, @@ -651,17 +740,40 @@ async_write_at(AsyncRandomAccessWriteDevice& 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 AsyncRandomAccessWriteDevice type's + * async_write_some_at operation. */ -template <typename AsyncRandomAccessWriteDevice, typename Allocator, - typename CompletionCondition, typename WriteHandler> -ASIO_INITFN_RESULT_TYPE(WriteHandler, - void (asio::error_code, std::size_t)) -async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, +template <typename AsyncRandomAccessWriteDevice, + typename Allocator, typename CompletionCondition, + ASIO_COMPLETION_TOKEN_FOR(void (asio::error_code, + std::size_t)) WriteToken = default_completion_token_t< + typename AsyncRandomAccessWriteDevice::executor_type>> +auto async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset, basic_streambuf<Allocator>& b, CompletionCondition completion_condition, - ASIO_MOVE_ARG(WriteHandler) handler); + WriteToken&& token = default_completion_token_t< + typename AsyncRandomAccessWriteDevice::executor_type>()) + -> decltype( + async_initiate<WriteToken, + void (asio::error_code, std::size_t)>( + declval<detail::initiate_async_write_at_streambuf< + AsyncRandomAccessWriteDevice>>(), + token, offset, &b, + static_cast<CompletionCondition&&>(completion_condition))); #endif // !defined(ASIO_NO_IOSTREAM) #endif // !defined(ASIO_NO_EXTENSIONS) |