// connect.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 Protocol, typename Executor, typename EndpointSequence>
typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s,
const EndpointSequence& endpoints,
- typename enable_if<is_endpoint_sequence<
- EndpointSequence>::value>::type* = 0);
+ typename constraint<is_endpoint_sequence<
+ EndpointSequence>::value>::type = 0);
/// Establishes a socket connection by trying each endpoint in a sequence.
/**
template <typename Protocol, typename Executor, typename EndpointSequence>
typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s,
const EndpointSequence& endpoints, boost::system::error_code& ec,
- typename enable_if<is_endpoint_sequence<
- EndpointSequence>::value>::type* = 0);
+ typename constraint<is_endpoint_sequence<
+ EndpointSequence>::value>::type = 0);
#if !defined(BOOST_ASIO_NO_DEPRECATED)
/// (Deprecated: Use range overload.) Establishes a socket connection by trying
*/
template <typename Protocol, typename Executor, typename Iterator>
Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin,
- typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
+ typename constraint<!is_endpoint_sequence<Iterator>::value>::type = 0);
/// (Deprecated: Use range overload.) Establishes a socket connection by trying
/// each endpoint in a sequence.
template <typename Protocol, typename Executor, typename Iterator>
Iterator connect(basic_socket<Protocol, Executor>& s,
Iterator begin, boost::system::error_code& ec,
- typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
+ typename constraint<!is_endpoint_sequence<Iterator>::value>::type = 0);
#endif // !defined(BOOST_ASIO_NO_DEPRECATED)
/// Establishes a socket connection by trying each endpoint in a sequence.
typename EndpointSequence, typename ConnectCondition>
typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s,
const EndpointSequence& endpoints, ConnectCondition connect_condition,
- typename enable_if<is_endpoint_sequence<
- EndpointSequence>::value>::type* = 0);
+ typename constraint<is_endpoint_sequence<
+ EndpointSequence>::value>::type = 0);
/// Establishes a socket connection by trying each endpoint in a sequence.
/**
typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s,
const EndpointSequence& endpoints, ConnectCondition connect_condition,
boost::system::error_code& ec,
- typename enable_if<is_endpoint_sequence<
- EndpointSequence>::value>::type* = 0);
+ typename constraint<is_endpoint_sequence<
+ EndpointSequence>::value>::type = 0);
#if !defined(BOOST_ASIO_NO_DEPRECATED)
/// (Deprecated: Use range overload.) Establishes a socket connection by trying
typename Iterator, typename ConnectCondition>
Iterator connect(basic_socket<Protocol, Executor>& s,
Iterator begin, ConnectCondition connect_condition,
- typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
+ typename constraint<!is_endpoint_sequence<Iterator>::value>::type = 0);
/// (Deprecated: Use range overload.) Establishes a socket connection by trying
/// each endpoint in a sequence.
typename Iterator, typename ConnectCondition>
Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin,
ConnectCondition connect_condition, boost::system::error_code& ec,
- typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
+ typename constraint<!is_endpoint_sequence<Iterator>::value>::type = 0);
#endif // !defined(BOOST_ASIO_NO_DEPRECATED)
/// Establishes a socket connection by trying each endpoint in a sequence.
* This function attempts to connect a socket to one of a sequence of
* endpoints. It does this by repeated calls to the socket's @c async_connect
* member function, once for each endpoint in the sequence, until a connection
- * is successfully established.
+ * is successfully established. It is an initiating function for an @ref
+ * asynchronous_operation, and always returns immediately.
*
* @param s The socket to be connected. If the socket is already open, it will
* be closed.
*
* @param endpoints A sequence of endpoints.
*
- * @param handler The handler to be called when the connect 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 connect 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. if the sequence is empty, set to
* // boost::asio::error::not_found. Otherwise, contains the
* const typename Protocol::endpoint& endpoint
* ); @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, typename Protocol::endpoint) @endcode
+ *
* @par Example
* @code tcp::resolver r(my_context);
* tcp::resolver::query q("host", "service");
* {
* // ...
* } @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 socket's @c async_connect operation.
*/
template <typename Protocol, typename Executor, typename EndpointSequence,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- typename Protocol::endpoint)) RangeConnectHandler
+ typename Protocol::endpoint)) RangeConnectToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectToken,
void (boost::system::error_code, typename Protocol::endpoint))
async_connect(basic_socket<Protocol, Executor>& s,
const EndpointSequence& endpoints,
- BOOST_ASIO_MOVE_ARG(RangeConnectHandler) handler
+ BOOST_ASIO_MOVE_ARG(RangeConnectToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor),
- typename enable_if<is_endpoint_sequence<
- EndpointSequence>::value>::type* = 0);
+ typename constraint<is_endpoint_sequence<
+ EndpointSequence>::value>::type = 0);
#if !defined(BOOST_ASIO_NO_DEPRECATED)
/// (Deprecated: Use range overload.) Asynchronously establishes a socket
* This function attempts to connect a socket to one of a sequence of
* endpoints. It does this by repeated calls to the socket's @c async_connect
* member function, once for each endpoint in the sequence, until a connection
- * is successfully established.
+ * is successfully established. It is an initiating function for an @ref
+ * asynchronous_operation, and always returns immediately.
*
* @param s The socket to be connected. If the socket is already open, it will
* be closed.
*
* @param begin An iterator pointing to the start of a sequence of endpoints.
*
- * @param handler The handler to be called when the connect 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 connect 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. if the sequence is empty, set to
* // boost::asio::error::not_found. Otherwise, contains the
* Iterator iterator
* ); @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, Iterator) @endcode
+ *
* @note This overload assumes that a default constructed object of type @c
* Iterator represents the end of the sequence. This is a valid assumption for
* iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
+ *
+ * @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 socket's @c async_connect operation.
*/
template <typename Protocol, typename Executor, typename Iterator,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- Iterator)) IteratorConnectHandler
+ Iterator)) IteratorConnectToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectToken,
void (boost::system::error_code, Iterator))
async_connect(basic_socket<Protocol, Executor>& s, Iterator begin,
- BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler
+ BOOST_ASIO_MOVE_ARG(IteratorConnectToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor),
- typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
+ typename constraint<!is_endpoint_sequence<Iterator>::value>::type = 0);
#endif // !defined(BOOST_ASIO_NO_DEPRECATED)
/// Asynchronously establishes a socket connection by trying each endpoint in a
* This function attempts to connect a socket to one of a sequence of
* endpoints. It does this by repeated calls to the socket's @c async_connect
* member function, once for each endpoint in the sequence, until a connection
- * is successfully established.
+ * is successfully established. It is an initiating function for an @ref
+ * asynchronous_operation, and always returns immediately.
*
* @param s The socket to be connected. If the socket is already open, it will
* be closed.
*
* @param end An iterator pointing to the end of a sequence of endpoints.
*
- * @param handler The handler to be called when the connect 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 connect 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. if the sequence is empty, set to
* // boost::asio::error::not_found. Otherwise, contains the
* Iterator iterator
* ); @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, Iterator) @endcode
+ *
* @par Example
* @code std::vector<tcp::endpoint> endpoints = ...;
* tcp::socket s(my_context);
* {
* // ...
* } @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 socket's @c async_connect operation.
*/
template <typename Protocol, typename Executor, typename Iterator,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- Iterator)) IteratorConnectHandler
+ Iterator)) IteratorConnectToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectToken,
void (boost::system::error_code, Iterator))
async_connect(basic_socket<Protocol, Executor>& s, Iterator begin, Iterator end,
- BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler
+ BOOST_ASIO_MOVE_ARG(IteratorConnectToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor));
/// Asynchronously establishes a socket connection by trying each endpoint in a
* This function attempts to connect a socket to one of a sequence of
* endpoints. It does this by repeated calls to the socket's @c async_connect
* member function, once for each endpoint in the sequence, until a connection
- * is successfully established.
+ * is successfully established. It is an initiating function for an @ref
+ * asynchronous_operation, and always returns immediately.
*
* @param s The socket to be connected. If the socket is already open, it will
* be closed.
* The function object should return true if the next endpoint should be tried,
* and false if it should be skipped.
*
- * @param handler The handler to be called when the connect 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 connect 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. if the sequence is empty, set to
* // boost::asio::error::not_found. Otherwise, contains the
* Iterator iterator
* ); @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, typename Protocol::endpoint) @endcode
+ *
* @par Example
* The following connect condition function object can be used to output
* information about the individual connection attempts:
* std::cout << "Connected to: " << endpoint << std::endl;
* }
* } @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 socket's @c async_connect operation.
*/
template <typename Protocol, typename Executor,
typename EndpointSequence, typename ConnectCondition,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- typename Protocol::endpoint)) RangeConnectHandler
+ typename Protocol::endpoint)) RangeConnectToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectToken,
void (boost::system::error_code, typename Protocol::endpoint))
async_connect(basic_socket<Protocol, Executor>& s,
const EndpointSequence& endpoints, ConnectCondition connect_condition,
- BOOST_ASIO_MOVE_ARG(RangeConnectHandler) handler
+ BOOST_ASIO_MOVE_ARG(RangeConnectToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor),
- typename enable_if<is_endpoint_sequence<
- EndpointSequence>::value>::type* = 0);
+ typename constraint<is_endpoint_sequence<
+ EndpointSequence>::value>::type = 0);
#if !defined(BOOST_ASIO_NO_DEPRECATED)
/// (Deprecated: Use range overload.) Asynchronously establishes a socket
* This function attempts to connect a socket to one of a sequence of
* endpoints. It does this by repeated calls to the socket's @c async_connect
* member function, once for each endpoint in the sequence, until a connection
- * is successfully established.
+ * is successfully established. It is an initiating function for an @ref
+ * asynchronous_operation, and always returns immediately.
*
* @param s The socket to be connected. If the socket is already open, it will
* be closed.
* The function object should return true if the next endpoint should be tried,
* and false if it should be skipped.
*
- * @param handler The handler to be called when the connect 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 connect 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. if the sequence is empty, set to
* // boost::asio::error::not_found. Otherwise, contains the
* Iterator iterator
* ); @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, Iterator) @endcode
+ *
* @note This overload assumes that a default constructed object of type @c
* Iterator represents the end of the sequence. This is a valid assumption for
* iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
+ *
+ * @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 socket's @c async_connect operation.
*/
template <typename Protocol, typename Executor,
typename Iterator, typename ConnectCondition,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- Iterator)) IteratorConnectHandler
+ Iterator)) IteratorConnectToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectToken,
void (boost::system::error_code, Iterator))
async_connect(basic_socket<Protocol, Executor>& s, Iterator begin,
ConnectCondition connect_condition,
- BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler
+ BOOST_ASIO_MOVE_ARG(IteratorConnectToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor),
- typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
+ typename constraint<!is_endpoint_sequence<Iterator>::value>::type = 0);
#endif // !defined(BOOST_ASIO_NO_DEPRECATED)
/// Asynchronously establishes a socket connection by trying each endpoint in a
* This function attempts to connect a socket to one of a sequence of
* endpoints. It does this by repeated calls to the socket's @c async_connect
* member function, once for each endpoint in the sequence, until a connection
- * is successfully established.
+ * is successfully established. It is an initiating function for an @ref
+ * asynchronous_operation, and always returns immediately.
*
* @param s The socket to be connected. If the socket is already open, it will
* be closed.
* The function object should return true if the next endpoint should be tried,
* and false if it should be skipped.
*
- * @param handler The handler to be called when the connect 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 connect 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. if the sequence is empty, set to
* // boost::asio::error::not_found. Otherwise, contains the
* Iterator iterator
* ); @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, Iterator) @endcode
+ *
* @par Example
* The following connect condition function object can be used to output
* information about the individual connection attempts:
* std::cout << "Connected to: " << i->endpoint() << std::endl;
* }
* } @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 socket's @c async_connect operation.
*/
template <typename Protocol, typename Executor,
typename Iterator, typename ConnectCondition,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
- Iterator)) IteratorConnectHandler
+ Iterator)) IteratorConnectToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
-BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler,
+BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectToken,
void (boost::system::error_code, Iterator))
async_connect(basic_socket<Protocol, Executor>& s, Iterator begin,
Iterator end, ConnectCondition connect_condition,
- BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler
+ BOOST_ASIO_MOVE_ARG(IteratorConnectToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor));
/*@}*/