// basic_datagram_socket.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)
* @par Thread Safety
* @e Distinct @e objects: Safe.@n
* @e Shared @e objects: Unsafe.
+ *
+ * Synchronous @c send, @c send_to, @c receive, @c receive_from, and @c connect
+ * operations are thread safe with respect to each other, if the underlying
+ * operating system calls are also thread safe. This means that it is permitted
+ * to perform concurrent calls to these synchronous operations on a single
+ * socket object. Other synchronous operations, such as @c open or @c close, are
+ * not thread safe.
*/
template <typename Protocol, typename Executor>
class basic_datagram_socket
*/
template <typename ExecutionContext>
explicit basic_datagram_socket(ExecutionContext& context,
- typename enable_if<
+ typename constraint<
is_convertible<ExecutionContext&, execution_context&>::value
- >::type* = 0)
+ >::type = 0)
: basic_socket<Protocol, Executor>(context)
{
}
template <typename ExecutionContext>
basic_datagram_socket(ExecutionContext& context,
const protocol_type& protocol,
- typename enable_if<
- is_convertible<ExecutionContext&, execution_context&>::value
- >::type* = 0)
+ typename constraint<
+ is_convertible<ExecutionContext&, execution_context&>::value,
+ defaulted_constraint
+ >::type = defaulted_constraint())
: basic_socket<Protocol, Executor>(context, protocol)
{
}
template <typename ExecutionContext>
basic_datagram_socket(ExecutionContext& context,
const endpoint_type& endpoint,
- typename enable_if<
+ typename constraint<
is_convertible<ExecutionContext&, execution_context&>::value
- >::type* = 0)
+ >::type = 0)
: basic_socket<Protocol, Executor>(context, endpoint)
{
}
template <typename ExecutionContext>
basic_datagram_socket(ExecutionContext& context,
const protocol_type& protocol, const native_handle_type& native_socket,
- typename enable_if<
+ typename constraint<
is_convertible<ExecutionContext&, execution_context&>::value
- >::type* = 0)
+ >::type = 0)
: basic_socket<Protocol, Executor>(context, protocol, native_socket)
{
}
*/
template <typename Protocol1, typename Executor1>
basic_datagram_socket(basic_datagram_socket<Protocol1, Executor1>&& other,
- typename enable_if<
+ typename constraint<
is_convertible<Protocol1, Protocol>::value
&& is_convertible<Executor1, Executor>::value
- >::type* = 0)
+ >::type = 0)
: basic_socket<Protocol, Executor>(std::move(other))
{
}
* constructor.
*/
template <typename Protocol1, typename Executor1>
- typename enable_if<
+ typename constraint<
is_convertible<Protocol1, Protocol>::value
&& is_convertible<Executor1, Executor>::value,
basic_datagram_socket&
/// Start an asynchronous send on a connected socket.
/**
* This function is used to asynchronously send data on the datagram socket.
- * The function call always returns immediately.
+ * It is an initiating function for an @ref asynchronous_operation, and always
+ * returns immediately.
*
* @param buffers One or more data buffers to be sent on the socket. 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.
+ * remain valid until the completion handler is called.
*
- * @param handler The handler to be called when the send 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 send 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(
* const boost::system::error_code& error, // Result of operation.
- * std::size_t bytes_transferred // Number of bytes sent.
+ * std::size_t bytes_transferred // Number of bytes sent.
* ); @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 The async_send operation can only be used with a connected socket.
* Use the async_send_to function to send data on an unconnected datagram
* socket.
* See the @ref buffer documentation for information on sending multiple
* buffers in one go, and how to use it with arrays, boost::array or
* std::vector.
+ *
+ * @par Per-Operation Cancellation
+ * On POSIX or Windows operating systems, this asynchronous operation supports
+ * cancellation for the following boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * @li @c cancellation_type::total
*/
template <typename ConstBufferSequence,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) WriteHandler
+ std::size_t)) WriteToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
- BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler,
+ BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken,
void (boost::system::error_code, std::size_t))
async_send(const ConstBufferSequence& buffers,
- BOOST_ASIO_MOVE_ARG(WriteHandler) handler
+ BOOST_ASIO_MOVE_ARG(WriteToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
{
- return async_initiate<WriteHandler,
+ return async_initiate<WriteToken,
void (boost::system::error_code, std::size_t)>(
- initiate_async_send(this), handler,
+ initiate_async_send(this), token,
buffers, socket_base::message_flags(0));
}
/// Start an asynchronous send on a connected socket.
/**
* This function is used to asynchronously send data on the datagram socket.
- * The function call always returns immediately.
+ * It is an initiating function for an @ref asynchronous_operation, and always
+ * returns immediately.
*
* @param buffers One or more data buffers to be sent on the socket. 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.
+ * remain valid until the completion handler is called.
*
* @param flags Flags specifying how the send call is to be made.
*
- * @param handler The handler to be called when the send 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 send 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(
* const boost::system::error_code& error, // Result of operation.
- * std::size_t bytes_transferred // Number of bytes sent.
+ * std::size_t bytes_transferred // Number of bytes sent.
* ); @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 The async_send operation can only be used with a connected socket.
* Use the async_send_to function to send data on an unconnected datagram
* socket.
+ *
+ * @par Per-Operation Cancellation
+ * On POSIX or Windows operating systems, this asynchronous operation supports
+ * cancellation for the following boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * @li @c cancellation_type::total
*/
template <typename ConstBufferSequence,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) WriteHandler
+ std::size_t)) WriteToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
- BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler,
+ BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken,
void (boost::system::error_code, std::size_t))
async_send(const ConstBufferSequence& buffers,
socket_base::message_flags flags,
- BOOST_ASIO_MOVE_ARG(WriteHandler) handler
+ BOOST_ASIO_MOVE_ARG(WriteToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
{
- return async_initiate<WriteHandler,
+ return async_initiate<WriteToken,
void (boost::system::error_code, std::size_t)>(
- initiate_async_send(this), handler, buffers, flags);
+ initiate_async_send(this), token, buffers, flags);
}
/// Send a datagram to the specified endpoint.
/// Start an asynchronous send.
/**
* This function is used to asynchronously send a datagram to the specified
- * remote endpoint. The function call always returns immediately.
+ * remote endpoint. It is an initiating function for an @ref
+ * asynchronous_operation, and always returns immediately.
*
* @param buffers One or more data buffers to be sent to the remote endpoint.
* 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 destination The remote endpoint to which the data will be sent.
* Copies will be made of the endpoint as required.
*
- * @param handler The handler to be called when the send 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 send 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(
* const boost::system::error_code& error, // Result of operation.
- * std::size_t bytes_transferred // Number of bytes sent.
+ * std::size_t bytes_transferred // Number of bytes sent.
* ); @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
+ *
* @par Example
* To send a single data buffer use the @ref buffer function as follows:
* @code
* See the @ref buffer documentation for information on sending multiple
* buffers in one go, and how to use it with arrays, boost::array or
* std::vector.
+ *
+ * @par Per-Operation Cancellation
+ * On POSIX or Windows operating systems, this asynchronous operation supports
+ * cancellation for the following boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * @li @c cancellation_type::total
*/
template <typename ConstBufferSequence,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) WriteHandler
+ std::size_t)) WriteToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
- BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler,
+ BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken,
void (boost::system::error_code, std::size_t))
async_send_to(const ConstBufferSequence& buffers,
const endpoint_type& destination,
- BOOST_ASIO_MOVE_ARG(WriteHandler) handler
+ BOOST_ASIO_MOVE_ARG(WriteToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
{
- return async_initiate<WriteHandler,
+ return async_initiate<WriteToken,
void (boost::system::error_code, std::size_t)>(
- initiate_async_send_to(this), handler, buffers,
+ initiate_async_send_to(this), token, buffers,
destination, socket_base::message_flags(0));
}
/// Start an asynchronous send.
/**
* This function is used to asynchronously send a datagram to the specified
- * remote endpoint. The function call always returns immediately.
+ * remote endpoint. It is an initiating function for an @ref
+ * asynchronous_operation, and always returns immediately.
*
* @param buffers One or more data buffers to be sent to the remote endpoint.
* 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 flags Flags specifying how the send call is to be made.
*
* @param destination The remote endpoint to which the data will be sent.
* Copies will be made of the endpoint as required.
*
- * @param handler The handler to be called when the send 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 send 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(
* const boost::system::error_code& error, // Result of operation.
- * std::size_t bytes_transferred // Number of bytes sent.
+ * std::size_t bytes_transferred // Number of bytes sent.
* ); @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
+ *
+ * @par Per-Operation Cancellation
+ * On POSIX or Windows operating systems, this asynchronous operation supports
+ * cancellation for the following boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * @li @c cancellation_type::total
*/
template <typename ConstBufferSequence,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) WriteHandler
+ std::size_t)) WriteToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
- BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler,
+ BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteToken,
void (boost::system::error_code, std::size_t))
async_send_to(const ConstBufferSequence& buffers,
const endpoint_type& destination, socket_base::message_flags flags,
- BOOST_ASIO_MOVE_ARG(WriteHandler) handler
+ BOOST_ASIO_MOVE_ARG(WriteToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
{
- return async_initiate<WriteHandler,
+ return async_initiate<WriteToken,
void (boost::system::error_code, std::size_t)>(
- initiate_async_send_to(this), handler, buffers, destination, flags);
+ initiate_async_send_to(this), token, buffers, destination, flags);
}
/// Receive some data on a connected socket.
/// Start an asynchronous receive on a connected socket.
/**
* This function is used to asynchronously receive data from the datagram
- * socket. The function call always returns immediately.
+ * socket. It is an initiating function for an @ref asynchronous_operation,
+ * and always returns immediately.
*
* @param buffers One or more buffers into which the data will be received.
* 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 receive 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 receive 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(
* const boost::system::error_code& error, // Result of operation.
- * std::size_t bytes_transferred // Number of bytes received.
+ * std::size_t bytes_transferred // Number of bytes received.
* ); @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 The async_receive operation can only be used with a connected socket.
* Use the async_receive_from function to receive data on an unconnected
* datagram socket.
* See the @ref buffer documentation for information on receiving into
* multiple buffers in one go, and how to use it with arrays, boost::array or
* std::vector.
+ *
+ * @par Per-Operation Cancellation
+ * On POSIX or Windows operating systems, this asynchronous operation supports
+ * cancellation for the following boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * @li @c cancellation_type::total
*/
template <typename MutableBufferSequence,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) ReadHandler
+ std::size_t)) ReadToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(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_receive(const MutableBufferSequence& buffers,
- BOOST_ASIO_MOVE_ARG(ReadHandler) handler
+ BOOST_ASIO_MOVE_ARG(ReadToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
{
- return async_initiate<ReadHandler,
+ return async_initiate<ReadToken,
void (boost::system::error_code, std::size_t)>(
- initiate_async_receive(this), handler,
+ initiate_async_receive(this), token,
buffers, socket_base::message_flags(0));
}
/// Start an asynchronous receive on a connected socket.
/**
* This function is used to asynchronously receive data from the datagram
- * socket. The function call always returns immediately.
+ * socket. It is an initiating function for an @ref asynchronous_operation,
+ * and always returns immediately.
*
* @param buffers One or more buffers into which the data will be received.
* 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 flags Flags specifying how the receive call is to be made.
*
- * @param handler The handler to be called when the receive 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 receive 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(
* const boost::system::error_code& error, // Result of operation.
- * std::size_t bytes_transferred // Number of bytes received.
+ * std::size_t bytes_transferred // Number of bytes received.
* ); @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 The async_receive operation can only be used with a connected socket.
* Use the async_receive_from function to receive data on an unconnected
* datagram socket.
+ *
+ * @par Per-Operation Cancellation
+ * On POSIX or Windows operating systems, this asynchronous operation supports
+ * cancellation for the following boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * @li @c cancellation_type::total
*/
template <typename MutableBufferSequence,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) ReadHandler
+ std::size_t)) ReadToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(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_receive(const MutableBufferSequence& buffers,
socket_base::message_flags flags,
- BOOST_ASIO_MOVE_ARG(ReadHandler) handler
+ BOOST_ASIO_MOVE_ARG(ReadToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
{
- return async_initiate<ReadHandler,
+ return async_initiate<ReadToken,
void (boost::system::error_code, std::size_t)>(
- initiate_async_receive(this), handler, buffers, flags);
+ initiate_async_receive(this), token, buffers, flags);
}
/// Receive a datagram with the endpoint of the sender.
/// Start an asynchronous receive.
/**
- * This function is used to asynchronously receive a datagram. The function
- * call always returns immediately.
+ * This function is used to asynchronously receive a datagram. It is an
+ * initiating function for an @ref asynchronous_operation, and always returns
+ * immediately.
*
* @param buffers One or more buffers into which the data will be received.
* 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 sender_endpoint An endpoint object that receives the endpoint of
* the remote sender of the datagram. Ownership of the sender_endpoint object
* is retained by the caller, which must guarantee that it is valid until the
- * handler is called.
+ * completion handler is called.
*
- * @param handler The handler to be called when the receive 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 receive 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(
* const boost::system::error_code& error, // Result of operation.
- * std::size_t bytes_transferred // Number of bytes received.
+ * std::size_t bytes_transferred // Number of bytes received.
* ); @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
+ *
* @par Example
* To receive into a single data buffer use the @ref buffer function as
* follows:
* See the @ref buffer documentation for information on receiving into
* multiple buffers in one go, and how to use it with arrays, boost::array or
* std::vector.
+ *
+ * @par Per-Operation Cancellation
+ * On POSIX or Windows operating systems, this asynchronous operation supports
+ * cancellation for the following boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * @li @c cancellation_type::total
*/
template <typename MutableBufferSequence,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) ReadHandler
+ std::size_t)) ReadToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(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_receive_from(const MutableBufferSequence& buffers,
endpoint_type& sender_endpoint,
- BOOST_ASIO_MOVE_ARG(ReadHandler) handler
+ BOOST_ASIO_MOVE_ARG(ReadToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
{
- return async_initiate<ReadHandler,
+ return async_initiate<ReadToken,
void (boost::system::error_code, std::size_t)>(
- initiate_async_receive_from(this), handler, buffers,
+ initiate_async_receive_from(this), token, buffers,
&sender_endpoint, socket_base::message_flags(0));
}
/// Start an asynchronous receive.
/**
- * This function is used to asynchronously receive a datagram. The function
- * call always returns immediately.
+ * This function is used to asynchronously receive a datagram. It is an
+ * initiating function for an @ref asynchronous_operation, and always returns
+ * immediately.
*
* @param buffers One or more buffers into which the data will be received.
* 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 sender_endpoint An endpoint object that receives the endpoint of
* the remote sender of the datagram. Ownership of the sender_endpoint object
* is retained by the caller, which must guarantee that it is valid until the
- * handler is called.
+ * completion handler is called.
*
* @param flags Flags specifying how the receive call is to be made.
*
- * @param handler The handler to be called when the receive 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 receive 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(
* const boost::system::error_code& error, // Result of operation.
- * std::size_t bytes_transferred // Number of bytes received.
+ * std::size_t bytes_transferred // Number of bytes received.
* ); @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
+ *
+ * @par Per-Operation Cancellation
+ * On POSIX or Windows operating systems, this asynchronous operation supports
+ * cancellation for the following boost::asio::cancellation_type values:
+ *
+ * @li @c cancellation_type::terminal
+ *
+ * @li @c cancellation_type::partial
+ *
+ * @li @c cancellation_type::total
*/
template <typename MutableBufferSequence,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- std::size_t)) ReadHandler
+ std::size_t)) ReadToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(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_receive_from(const MutableBufferSequence& buffers,
endpoint_type& sender_endpoint, socket_base::message_flags flags,
- BOOST_ASIO_MOVE_ARG(ReadHandler) handler
+ BOOST_ASIO_MOVE_ARG(ReadToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
{
- return async_initiate<ReadHandler,
+ return async_initiate<ReadToken,
void (boost::system::error_code, std::size_t)>(
- initiate_async_receive_from(this), handler,
+ initiate_async_receive_from(this), token,
buffers, &sender_endpoint, flags);
}
projects / ceph.git / blobdiff