// read_until.hpp
// ~~~~~~~~~~~~~~
//
-// Copyright (c) 2003-2020 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+// Copyright (c) 2003-2022 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)
template <typename SyncReadStream, typename DynamicBuffer_v1>
std::size_t read_until(SyncReadStream& s,
BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, char delim,
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
- && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
- >::type* = 0);
+ >::type = 0,
+ typename constraint<
+ !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
+ >::type = 0);
/// Read data into a dynamic buffer sequence until it contains a specified
/// delimiter.
std::size_t read_until(SyncReadStream& s,
BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
char delim, boost::system::error_code& ec,
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
- && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
- >::type* = 0);
+ >::type = 0,
+ typename constraint<
+ !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
+ >::type = 0);
/// Read data into a dynamic buffer sequence until it contains a specified
/// delimiter.
std::size_t read_until(SyncReadStream& s,
BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
BOOST_ASIO_STRING_VIEW_PARAM delim,
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
- && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
- >::type* = 0);
+ >::type = 0,
+ typename constraint<
+ !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
+ >::type = 0);
/// Read data into a dynamic buffer sequence until it contains a specified
/// delimiter.
BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
BOOST_ASIO_STRING_VIEW_PARAM delim,
boost::system::error_code& ec,
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
- && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
- >::type* = 0);
+ >::type = 0,
+ typename constraint<
+ !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
+ >::type = 0);
#if !defined(BOOST_ASIO_NO_EXTENSIONS)
#if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
std::size_t read_until(SyncReadStream& s,
BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
const boost::regex& expr,
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
- && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
- >::type* = 0);
+ >::type = 0,
+ typename constraint<
+ !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
+ >::type = 0);
/// Read data into a dynamic buffer sequence until some part of the data it
/// contains matches a regular expression.
std::size_t read_until(SyncReadStream& s,
BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
const boost::regex& expr, boost::system::error_code& ec,
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
- && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
- >::type* = 0);
+ >::type = 0,
+ typename constraint<
+ !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
+ >::type = 0);
#endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
// || defined(GENERATING_DOCUMENTATION)
std::size_t read_until(SyncReadStream& s,
BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
MatchCondition match_condition,
- typename enable_if<
+ typename constraint<
is_match_condition<MatchCondition>::value
- && is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
- && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
- >::type* = 0);
+ >::type = 0,
+ typename constraint<
+ is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
+ >::type = 0,
+ typename constraint<
+ !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
+ >::type = 0);
/// Read data into a dynamic buffer sequence until a function object indicates a
/// match.
std::size_t read_until(SyncReadStream& s,
BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
MatchCondition match_condition, boost::system::error_code& ec,
- typename enable_if<
+ typename constraint<
is_match_condition<MatchCondition>::value
- && is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
- && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
- >::type* = 0);
+ >::type = 0,
+ typename constraint<
+ is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
+ >::type = 0,
+ typename constraint<
+ !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
+ >::type = 0);
#if !defined(BOOST_ASIO_NO_IOSTREAM)
template <typename SyncReadStream, typename Allocator, typename MatchCondition>
std::size_t read_until(SyncReadStream& s,
boost::asio::basic_streambuf<Allocator>& b, MatchCondition match_condition,
- typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
+ typename constraint<is_match_condition<MatchCondition>::value>::type = 0);
/// Read data into a streambuf until a function object indicates a match.
/**
std::size_t read_until(SyncReadStream& s,
boost::asio::basic_streambuf<Allocator>& b,
MatchCondition match_condition, boost::system::error_code& ec,
- typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
+ typename constraint<is_match_condition<MatchCondition>::value>::type = 0);
#endif // !defined(BOOST_ASIO_NO_IOSTREAM)
#endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
*/
template <typename SyncReadStream, typename DynamicBuffer_v2>
std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers, char delim,
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v2<DynamicBuffer_v2>::value
- >::type* = 0);
+ >::type = 0);
/// Read data into a dynamic buffer sequence until it contains a specified
/// delimiter.
template <typename SyncReadStream, typename DynamicBuffer_v2>
std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
char delim, boost::system::error_code& ec,
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v2<DynamicBuffer_v2>::value
- >::type* = 0);
+ >::type = 0);
/// Read data into a dynamic buffer sequence until it contains a specified
/// delimiter.
template <typename SyncReadStream, typename DynamicBuffer_v2>
std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
BOOST_ASIO_STRING_VIEW_PARAM delim,
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v2<DynamicBuffer_v2>::value
- >::type* = 0);
+ >::type = 0);
/// Read data into a dynamic buffer sequence until it contains a specified
/// delimiter.
template <typename SyncReadStream, typename DynamicBuffer_v2>
std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
BOOST_ASIO_STRING_VIEW_PARAM delim, boost::system::error_code& ec,
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v2<DynamicBuffer_v2>::value
- >::type* = 0);
+ >::type = 0);
#if !defined(BOOST_ASIO_NO_EXTENSIONS)
#if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
template <typename SyncReadStream, typename DynamicBuffer_v2>
std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
const boost::regex& expr,
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v2<DynamicBuffer_v2>::value
- >::type* = 0);
+ >::type = 0);
/// Read data into a dynamic buffer sequence until some part of the data it
/// contains matches a regular expression.
template <typename SyncReadStream, typename DynamicBuffer_v2>
std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
const boost::regex& expr, boost::system::error_code& ec,
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v2<DynamicBuffer_v2>::value
- >::type* = 0);
+ >::type = 0);
#endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
// || defined(GENERATING_DOCUMENTATION)
typename DynamicBuffer_v2, typename MatchCondition>
std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
MatchCondition match_condition,
- typename enable_if<
+ typename constraint<
is_match_condition<MatchCondition>::value
- && is_dynamic_buffer_v2<DynamicBuffer_v2>::value
- >::type* = 0);
+ >::type = 0,
+ typename constraint<
+ is_dynamic_buffer_v2<DynamicBuffer_v2>::value
+ >::type = 0);
/// Read data into a dynamic buffer sequence until a function object indicates a
/// match.
typename DynamicBuffer_v2, typename MatchCondition>
std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
MatchCondition match_condition, boost::system::error_code& ec,
- typename enable_if<
+ typename constraint<
is_match_condition<MatchCondition>::value
- && is_dynamic_buffer_v2<DynamicBuffer_v2>::value
- >::type* = 0);
+ >::type = 0,
+ typename constraint<
+ is_dynamic_buffer_v2<DynamicBuffer_v2>::value
+ >::type = 0);
#endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
/**
* This function is used to asynchronously read data into the specified dynamic
* buffer sequence until the dynamic buffer sequence's get area contains the
- * specified delimiter. The function call always returns immediately. The
- * asynchronous operation will continue until one of the following conditions
- * is true:
+ * specified delimiter. 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 get area of the dynamic buffer sequence contains the specified
* delimiter.
* @param buffers The dynamic buffer sequence into which the data will be read.
* 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 delim The delimiter character.
*
- * @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 boost::system::error_code& error,
*
* // The number of bytes in the dynamic buffer sequence's
* // get area up to and including the delimiter.
- * // 0 if an error occurred.
* 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. On
- * immediate completion, invocation of the handler will be performed in a
+ * 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 boost::asio::post().
*
+ * @par Completion Signature
+ * @code void(boost::system::error_code, std::size_t) @endcode
+ *
* @note After a successful async_read_until operation, the dynamic buffer
* sequence may contain additional data beyond the delimiter. An application
* will typically leave that data in the dynamic buffer sequence for a
* @code { 'd', 'e', ... } @endcode
* This data may be the start of a new line, to be extracted by a subsequent
* @c async_read_until operation.
+ *
+ * @par Per-Operation Cancellation
+ * This asynchronous operation supports cancellation for the following
+ * boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * if they are also supported by the @c AsyncReadStream type's
+ * @c async_read_some operation.
*/
template <typename AsyncReadStream, typename DynamicBuffer_v1,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) ReadHandler
+ std::size_t)) ReadToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
typename AsyncReadStream::executor_type)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
void (boost::system::error_code, std::size_t))
async_read_until(AsyncReadStream& s,
BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, char delim,
- BOOST_ASIO_MOVE_ARG(ReadHandler) handler
+ BOOST_ASIO_MOVE_ARG(ReadToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
typename AsyncReadStream::executor_type),
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
- && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
- >::type* = 0);
+ >::type = 0,
+ typename constraint<
+ !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
+ >::type = 0);
/// Start an asynchronous operation to read data into a dynamic buffer sequence
/// until it contains a specified delimiter.
/**
* This function is used to asynchronously read data into the specified dynamic
* buffer sequence until the dynamic buffer sequence's get area contains the
- * specified delimiter. The function call always returns immediately. The
- * asynchronous operation will continue until one of the following conditions
- * is true:
+ * specified delimiter. 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 get area of the dynamic buffer sequence contains the specified
* delimiter.
* @param buffers The dynamic buffer sequence into which the data will be read.
* 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 delim The delimiter string.
*
- * @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 boost::system::error_code& error,
*
* // The number of bytes in the dynamic buffer sequence's
* // get area up to and including the delimiter.
- * // 0 if an error occurred.
* 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. On
- * immediate completion, invocation of the handler will be performed in a
+ * 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 boost::asio::post().
*
+ * @par Completion Signature
+ * @code void(boost::system::error_code, std::size_t) @endcode
+ *
* @note After a successful async_read_until operation, the dynamic buffer
* sequence may contain additional data beyond the delimiter. An application
* will typically leave that data in the dynamic buffer sequence for a
* @code { 'd', 'e', ... } @endcode
* This data may be the start of a new line, to be extracted by a subsequent
* @c async_read_until operation.
+ *
+ * @par Per-Operation Cancellation
+ * This asynchronous operation supports cancellation for the following
+ * boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * if they are also supported by the @c AsyncReadStream type's
+ * @c async_read_some operation.
*/
template <typename AsyncReadStream, typename DynamicBuffer_v1,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) ReadHandler
+ std::size_t)) ReadToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
typename AsyncReadStream::executor_type)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
void (boost::system::error_code, std::size_t))
async_read_until(AsyncReadStream& s,
BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
BOOST_ASIO_STRING_VIEW_PARAM delim,
- BOOST_ASIO_MOVE_ARG(ReadHandler) handler
+ BOOST_ASIO_MOVE_ARG(ReadToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
typename AsyncReadStream::executor_type),
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
- && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
- >::type* = 0);
+ >::type = 0,
+ typename constraint<
+ !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
+ >::type = 0);
#if !defined(BOOST_ASIO_NO_EXTENSIONS)
#if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
/**
* This function is used to asynchronously read data into the specified dynamic
* buffer sequence until the dynamic buffer sequence's get area contains some
- * data that matches a regular expression. The function call always returns
- * immediately. The asynchronous operation will continue until one of the
- * following conditions is true:
+ * data that matches a regular expression. 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 A substring of the dynamic buffer sequence's get area matches the regular
* expression.
* @param buffers The dynamic buffer sequence into which the data will be read.
* 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 expr The regular expression.
*
- * @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 boost::system::error_code& error,
* 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. On
- * immediate completion, invocation of the handler will be performed in a
+ * 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 boost::asio::post().
*
+ * @par Completion Signature
+ * @code void(boost::system::error_code, std::size_t) @endcode
+ *
* @note After a successful async_read_until operation, the dynamic buffer
* sequence may contain additional data beyond that which matched the regular
* expression. An application will typically leave that data in the dynamic
* @code { 'd', 'e', ... } @endcode
* This data may be the start of a new line, to be extracted by a subsequent
* @c async_read_until operation.
+ *
+ * @par Per-Operation Cancellation
+ * This asynchronous operation supports cancellation for the following
+ * boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * if they are also supported by the @c AsyncReadStream type's
+ * @c async_read_some operation.
*/
template <typename AsyncReadStream, typename DynamicBuffer_v1,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) ReadHandler
+ std::size_t)) ReadToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
typename AsyncReadStream::executor_type)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
void (boost::system::error_code, std::size_t))
async_read_until(AsyncReadStream& s,
BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
const boost::regex& expr,
- BOOST_ASIO_MOVE_ARG(ReadHandler) handler
+ BOOST_ASIO_MOVE_ARG(ReadToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
typename AsyncReadStream::executor_type),
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
- && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
- >::type* = 0);
+ >::type = 0,
+ typename constraint<
+ !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
+ >::type = 0);
#endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
// || defined(GENERATING_DOCUMENTATION)
* This function is used to asynchronously read data into the specified dynamic
* buffer sequence until a user-defined match condition function object, when
* applied to the data contained in the dynamic buffer sequence, indicates a
- * successful match. The function call always returns immediately. The
- * asynchronous operation will continue until one of the following conditions
- * is true:
+ * successful match. 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 match condition function object returns a std::pair where the second
* element evaluates to true.
* @param buffers The dynamic buffer sequence into which the data will be read.
* 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 match_condition The function object to be called to determine whether
* a match exists. The signature of the function object must be:
* @c second member of the return value is true if a match has been found, false
* otherwise.
*
- * @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 boost::system::error_code& error,
* 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. On
- * immediate completion, invocation of the handler will be performed in a
+ * 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 boost::asio::post().
*
* @note After a successful async_read_until operation, the dynamic buffer
* object. An application will typically leave that data in the dynamic buffer
* sequence for a subsequent async_read_until operation to examine.
*
+ * @par Completion Signature
+ * @code void(boost::system::error_code, std::size_t) @endcode
+ *
* @note The default implementation of the @c is_match_condition type trait
* evaluates to true for function pointers and function objects with a
* @c result_type typedef. It must be specialised for other user-defined
* std::string data;
* boost::asio::async_read_until(s, data, match_char('a'), handler);
* @endcode
+ *
+ * @par Per-Operation Cancellation
+ * This asynchronous operation supports cancellation for the following
+ * boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * if they are also supported by the @c AsyncReadStream type's
+ * @c async_read_some operation.
*/
template <typename AsyncReadStream,
typename DynamicBuffer_v1, typename MatchCondition,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) ReadHandler
+ std::size_t)) ReadToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
typename AsyncReadStream::executor_type)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
void (boost::system::error_code, std::size_t))
async_read_until(AsyncReadStream& s,
BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
MatchCondition match_condition,
- BOOST_ASIO_MOVE_ARG(ReadHandler) handler
+ BOOST_ASIO_MOVE_ARG(ReadToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
typename AsyncReadStream::executor_type),
- typename enable_if<
+ typename constraint<
is_match_condition<MatchCondition>::value
- && is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
- && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
- >::type* = 0);
+ >::type = 0,
+ typename constraint<
+ is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
+ >::type = 0,
+ typename constraint<
+ !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
+ >::type = 0);
#if !defined(BOOST_ASIO_NO_IOSTREAM)
/**
* This function is used to asynchronously read data into the specified
* streambuf until the streambuf's get area contains the specified delimiter.
- * The function call always returns immediately. The asynchronous operation
- * will continue until one of the following conditions is true:
+ * 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 get area of the streambuf contains the specified delimiter.
*
*
* @param b A 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.
+ * valid until the completion handler is called.
*
* @param delim The delimiter character.
*
- * @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 boost::system::error_code& error,
* 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. On
- * immediate completion, invocation of the handler will be performed in a
+ * 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 boost::asio::post().
*
+ * @par Completion Signature
+ * @code void(boost::system::error_code, std::size_t) @endcode
+ *
* @note After a successful async_read_until operation, the streambuf may
* contain additional data beyond the delimiter. An application will typically
* leave that data in the streambuf for a subsequent async_read_until operation
* @code { 'd', 'e', ... } @endcode
* This data may be the start of a new line, to be extracted by a subsequent
* @c async_read_until operation.
+ *
+ * @par Per-Operation Cancellation
+ * This asynchronous operation supports cancellation for the following
+ * boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * if they are also supported by the @c AsyncReadStream type's
+ * @c async_read_some operation.
*/
template <typename AsyncReadStream, typename Allocator,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) ReadHandler
+ std::size_t)) ReadToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
typename AsyncReadStream::executor_type)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
void (boost::system::error_code, std::size_t))
async_read_until(AsyncReadStream& s,
boost::asio::basic_streambuf<Allocator>& b, char delim,
- BOOST_ASIO_MOVE_ARG(ReadHandler) handler
+ BOOST_ASIO_MOVE_ARG(ReadToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
typename AsyncReadStream::executor_type));
/**
* This function is used to asynchronously read data into the specified
* streambuf until the streambuf's get area contains the specified delimiter.
- * The function call always returns immediately. The asynchronous operation
- * will continue until one of the following conditions is true:
+ * 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 get area of the streambuf contains the specified delimiter.
*
*
* @param b A 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.
+ * valid until the completion handler is called.
*
* @param delim The delimiter string.
*
- * @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 boost::system::error_code& error,
* 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. On
- * immediate completion, invocation of the handler will be performed in a
+ * 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 boost::asio::post().
*
+ * @par Completion Signature
+ * @code void(boost::system::error_code, std::size_t) @endcode
+ *
* @note After a successful async_read_until operation, the streambuf may
* contain additional data beyond the delimiter. An application will typically
* leave that data in the streambuf for a subsequent async_read_until operation
* @code { 'd', 'e', ... } @endcode
* This data may be the start of a new line, to be extracted by a subsequent
* @c async_read_until operation.
+ *
+ * @par Per-Operation Cancellation
+ * This asynchronous operation supports cancellation for the following
+ * boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * if they are also supported by the @c AsyncReadStream type's
+ * @c async_read_some operation.
*/
template <typename AsyncReadStream, typename Allocator,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) ReadHandler
+ std::size_t)) ReadToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
typename AsyncReadStream::executor_type)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
void (boost::system::error_code, std::size_t))
async_read_until(AsyncReadStream& s,
boost::asio::basic_streambuf<Allocator>& b,
BOOST_ASIO_STRING_VIEW_PARAM delim,
- BOOST_ASIO_MOVE_ARG(ReadHandler) handler
+ BOOST_ASIO_MOVE_ARG(ReadToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
typename AsyncReadStream::executor_type));
/**
* This function is used to asynchronously read data into the specified
* streambuf until the streambuf's get area contains some data that matches a
- * regular expression. The function call always returns immediately. The
- * asynchronous operation will continue until one of the following conditions
- * is true:
+ * regular expression. 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 A substring of the streambuf's get area matches the regular expression.
*
*
* @param b A 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.
+ * valid until the completion handler is called.
*
* @param expr The regular expression.
*
- * @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 boost::system::error_code& error,
* 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. On
- * immediate completion, invocation of the handler will be performed in a
+ * 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 boost::asio::post().
*
+ * @par Completion Signature
+ * @code void(boost::system::error_code, std::size_t) @endcode
+ *
* @note After a successful async_read_until operation, the streambuf may
* contain additional data beyond that which matched the regular expression. An
* application will typically leave that data in the streambuf for a subsequent
* @code { 'd', 'e', ... } @endcode
* This data may be the start of a new line, to be extracted by a subsequent
* @c async_read_until operation.
+ *
+ * @par Per-Operation Cancellation
+ * This asynchronous operation supports cancellation for the following
+ * boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * if they are also supported by the @c AsyncReadStream type's
+ * @c async_read_some operation.
*/
template <typename AsyncReadStream, typename Allocator,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) ReadHandler
+ std::size_t)) ReadToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
typename AsyncReadStream::executor_type)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
void (boost::system::error_code, std::size_t))
async_read_until(AsyncReadStream& s,
boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr,
- BOOST_ASIO_MOVE_ARG(ReadHandler) handler
+ BOOST_ASIO_MOVE_ARG(ReadToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
typename AsyncReadStream::executor_type));
/**
* This function is used to asynchronously read data into the specified
* streambuf until a user-defined match condition function object, when applied
- * to the data contained in the streambuf, indicates a successful match. The
- * function call always returns immediately. The asynchronous operation will
- * continue until one of the following conditions is true:
+ * to the data contained in the streambuf, indicates a successful match. 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 match condition function object returns a std::pair where the second
* element evaluates to true.
* @c second member of the return value is true if a match has been found, false
* otherwise.
*
- * @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 boost::system::error_code& error,
* 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. On
- * immediate completion, invocation of the handler will be performed in a
+ * 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 boost::asio::post().
*
* @note After a successful async_read_until operation, the streambuf may
* application will typically leave that data in the streambuf for a subsequent
* async_read_until operation to examine.
*
+ * @par Completion Signature
+ * @code void(boost::system::error_code, std::size_t) @endcode
+ *
* @note The default implementation of the @c is_match_condition type trait
* evaluates to true for function pointers and function objects with a
* @c result_type typedef. It must be specialised for other user-defined
* boost::asio::streambuf b;
* boost::asio::async_read_until(s, b, match_char('a'), handler);
* @endcode
+ *
+ * @par Per-Operation Cancellation
+ * This asynchronous operation supports cancellation for the following
+ * boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * if they are also supported by the @c AsyncReadStream type's
+ * @c async_read_some operation.
*/
template <typename AsyncReadStream, typename Allocator, typename MatchCondition,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) ReadHandler
+ std::size_t)) ReadToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
typename AsyncReadStream::executor_type)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
void (boost::system::error_code, std::size_t))
async_read_until(AsyncReadStream& s,
boost::asio::basic_streambuf<Allocator>& b,
MatchCondition match_condition,
- BOOST_ASIO_MOVE_ARG(ReadHandler) handler
+ BOOST_ASIO_MOVE_ARG(ReadToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
typename AsyncReadStream::executor_type),
- typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
+ typename constraint<is_match_condition<MatchCondition>::value>::type = 0);
#endif // !defined(BOOST_ASIO_NO_IOSTREAM)
#endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
/**
* This function is used to asynchronously read data into the specified dynamic
* buffer sequence until the dynamic buffer sequence's get area contains the
- * specified delimiter. The function call always returns immediately. The
- * asynchronous operation will continue until one of the following conditions
- * is true:
+ * specified delimiter. 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 get area of the dynamic buffer sequence contains the specified
* delimiter.
* @param buffers The dynamic buffer sequence into which the data will be read.
* 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 delim The delimiter character.
*
- * @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 boost::system::error_code& error,
* 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. On
- * immediate completion, invocation of the handler will be performed in a
+ * 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 boost::asio::post().
*
+ * @par Completion Signature
+ * @code void(boost::system::error_code, std::size_t) @endcode
+ *
* @note After a successful async_read_until operation, the dynamic buffer
* sequence may contain additional data beyond the delimiter. An application
* will typically leave that data in the dynamic buffer sequence for a
* @code { 'd', 'e', ... } @endcode
* This data may be the start of a new line, to be extracted by a subsequent
* @c async_read_until operation.
+ *
+ * @par Per-Operation Cancellation
+ * This asynchronous operation supports cancellation for the following
+ * boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * if they are also supported by the @c AsyncReadStream type's
+ * @c async_read_some operation.
*/
template <typename AsyncReadStream, typename DynamicBuffer_v2,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) ReadHandler
+ std::size_t)) ReadToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
typename AsyncReadStream::executor_type)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
void (boost::system::error_code, std::size_t))
async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, char delim,
- BOOST_ASIO_MOVE_ARG(ReadHandler) handler
+ BOOST_ASIO_MOVE_ARG(ReadToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
typename AsyncReadStream::executor_type),
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v2<DynamicBuffer_v2>::value
- >::type* = 0);
+ >::type = 0);
/// Start an asynchronous operation to read data into a dynamic buffer sequence
/// until it contains a specified delimiter.
/**
* This function is used to asynchronously read data into the specified dynamic
* buffer sequence until the dynamic buffer sequence's get area contains the
- * specified delimiter. The function call always returns immediately. The
- * asynchronous operation will continue until one of the following conditions
- * is true:
+ * specified delimiter. 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 get area of the dynamic buffer sequence contains the specified
* delimiter.
* @param buffers The dynamic buffer sequence into which the data will be read.
* 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 delim The delimiter string.
*
- * @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 boost::system::error_code& error,
*
* // The number of bytes in the dynamic buffer sequence's
* // get area up to and including the delimiter.
- * // 0 if an error occurred.
* 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. On
- * immediate completion, invocation of the handler will be performed in a
+ * 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 boost::asio::post().
*
+ * @par Completion Signature
+ * @code void(boost::system::error_code, std::size_t) @endcode
+ *
* @note After a successful async_read_until operation, the dynamic buffer
* sequence may contain additional data beyond the delimiter. An application
* will typically leave that data in the dynamic buffer sequence for a
* @code { 'd', 'e', ... } @endcode
* This data may be the start of a new line, to be extracted by a subsequent
* @c async_read_until operation.
+ *
+ * @par Per-Operation Cancellation
+ * This asynchronous operation supports cancellation for the following
+ * boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * if they are also supported by the @c AsyncReadStream type's
+ * @c async_read_some operation.
*/
template <typename AsyncReadStream, typename DynamicBuffer_v2,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) ReadHandler
+ std::size_t)) ReadToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
typename AsyncReadStream::executor_type)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
void (boost::system::error_code, std::size_t))
async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers,
BOOST_ASIO_STRING_VIEW_PARAM delim,
- BOOST_ASIO_MOVE_ARG(ReadHandler) handler
+ BOOST_ASIO_MOVE_ARG(ReadToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
typename AsyncReadStream::executor_type),
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v2<DynamicBuffer_v2>::value
- >::type* = 0);
+ >::type = 0);
#if !defined(BOOST_ASIO_NO_EXTENSIONS)
#if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
/**
* This function is used to asynchronously read data into the specified dynamic
* buffer sequence until the dynamic buffer sequence's get area contains some
- * data that matches a regular expression. The function call always returns
- * immediately. The asynchronous operation will continue until one of the
- * following conditions is true:
+ * data that matches a regular expression. 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 A substring of the dynamic buffer sequence's get area matches the regular
* expression.
* @param buffers The dynamic buffer sequence into which the data will be read.
* 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 expr The regular expression.
*
- * @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 boost::system::error_code& error,
* 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. On
- * immediate completion, invocation of the handler will be performed in a
+ * 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 boost::asio::post().
*
+ * @par Completion Signature
+ * @code void(boost::system::error_code, std::size_t) @endcode
+ *
* @note After a successful async_read_until operation, the dynamic buffer
* sequence may contain additional data beyond that which matched the regular
* expression. An application will typically leave that data in the dynamic
* @code { 'd', 'e', ... } @endcode
* This data may be the start of a new line, to be extracted by a subsequent
* @c async_read_until operation.
+ *
+ * @par Per-Operation Cancellation
+ * This asynchronous operation supports cancellation for the following
+ * boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * if they are also supported by the @c AsyncReadStream type's
+ * @c async_read_some operation.
*/
template <typename AsyncReadStream, typename DynamicBuffer_v2,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) ReadHandler
+ std::size_t)) ReadToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
typename AsyncReadStream::executor_type)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
void (boost::system::error_code, std::size_t))
async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers,
const boost::regex& expr,
- BOOST_ASIO_MOVE_ARG(ReadHandler) handler
+ BOOST_ASIO_MOVE_ARG(ReadToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
typename AsyncReadStream::executor_type),
- typename enable_if<
+ typename constraint<
is_dynamic_buffer_v2<DynamicBuffer_v2>::value
- >::type* = 0);
+ >::type = 0);
#endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
// || defined(GENERATING_DOCUMENTATION)
* This function is used to asynchronously read data into the specified dynamic
* buffer sequence until a user-defined match condition function object, when
* applied to the data contained in the dynamic buffer sequence, indicates a
- * successful match. The function call always returns immediately. The
- * asynchronous operation will continue until one of the following conditions
- * is true:
+ * successful match. 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 match condition function object returns a std::pair where the second
* element evaluates to true.
* @param buffers The dynamic buffer sequence into which the data will be read.
* 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 match_condition The function object to be called to determine whether
* a match exists. The signature of the function object must be:
* @c second member of the return value is true if a match has been found, false
* otherwise.
*
- * @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 boost::system::error_code& error,
* 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. On
- * immediate completion, invocation of the handler will be performed in a
+ * 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 boost::asio::post().
*
* @note After a successful async_read_until operation, the dynamic buffer
* object. An application will typically leave that data in the dynamic buffer
* sequence for a subsequent async_read_until operation to examine.
*
+ * @par Completion Signature
+ * @code void(boost::system::error_code, std::size_t) @endcode
+ *
* @note The default implementation of the @c is_match_condition type trait
* evaluates to true for function pointers and function objects with a
* @c result_type typedef. It must be specialised for other user-defined
* std::string data;
* boost::asio::async_read_until(s, data, match_char('a'), handler);
* @endcode
+ *
+ * @par Per-Operation Cancellation
+ * This asynchronous operation supports cancellation for the following
+ * boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * if they are also supported by the @c AsyncReadStream type's
+ * @c async_read_some operation.
*/
template <typename AsyncReadStream,
typename DynamicBuffer_v2, typename MatchCondition,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) ReadHandler
+ std::size_t)) ReadToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
typename AsyncReadStream::executor_type)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
void (boost::system::error_code, std::size_t))
async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers,
MatchCondition match_condition,
- BOOST_ASIO_MOVE_ARG(ReadHandler) handler
+ BOOST_ASIO_MOVE_ARG(ReadToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
typename AsyncReadStream::executor_type),
- typename enable_if<
+ typename constraint<
is_match_condition<MatchCondition>::value
- && is_dynamic_buffer_v2<DynamicBuffer_v2>::value
- >::type* = 0);
+ >::type = 0,
+ typename constraint<
+ is_dynamic_buffer_v2<DynamicBuffer_v2>::value
+ >::type = 0);
#endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
projects / ceph.git / blobdiff