diff options
Diffstat (limited to '3rdparty/asio/include/asio/connect.hpp')
-rw-r--r-- | 3rdparty/asio/include/asio/connect.hpp | 451 |
1 files changed, 286 insertions, 165 deletions
diff --git a/3rdparty/asio/include/asio/connect.hpp b/3rdparty/asio/include/asio/connect.hpp index 7dba932ecfb..d2916675455 100644 --- a/3rdparty/asio/include/asio/connect.hpp +++ b/3rdparty/asio/include/asio/connect.hpp @@ -2,7 +2,7 @@ // connect.hpp // ~~~~~~~~~~~ // -// Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// Copyright (c) 2003-2024 Christopher M. Kohlhoff (chris at kohlhoff dot com) // // Distributed under the Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) @@ -27,6 +27,10 @@ namespace asio { namespace detail { + struct default_connect_condition; + template <typename, typename> class initiate_async_range_connect; + template <typename, typename> class initiate_async_iterator_connect; + char (&has_iterator_helper(...))[2]; template <typename T> @@ -58,7 +62,8 @@ struct is_endpoint_sequence /** * @defgroup connect asio::connect * - * @brief Establishes a socket connection by trying each endpoint in a sequence. + * @brief The @c connect function is a composed operation that establishes a + * socket connection by trying each endpoint in a sequence. */ /*@{*/ @@ -81,17 +86,15 @@ struct is_endpoint_sequence * Otherwise, contains the error from the last connection attempt. * * @par Example - * @code tcp::resolver r(io_context); + * @code tcp::resolver r(my_context); * tcp::resolver::query q("host", "service"); - * tcp::socket s(io_context); + * tcp::socket s(my_context); * asio::connect(s, r.resolve(q)); @endcode */ -template <typename Protocol ASIO_SVC_TPARAM, typename EndpointSequence> -typename Protocol::endpoint connect( - basic_socket<Protocol ASIO_SVC_TARG>& s, +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); + constraint_t<is_endpoint_sequence<EndpointSequence>::value> = 0); /// Establishes a socket connection by trying each endpoint in a sequence. /** @@ -113,9 +116,9 @@ typename Protocol::endpoint connect( * default-constructed endpoint. * * @par Example - * @code tcp::resolver r(io_context); + * @code tcp::resolver r(my_context); * tcp::resolver::query q("host", "service"); - * tcp::socket s(io_context); + * tcp::socket s(my_context); * asio::error_code ec; * asio::connect(s, r.resolve(q), ec); * if (ec) @@ -123,16 +126,14 @@ typename Protocol::endpoint connect( * // An error occurred. * } @endcode */ -template <typename Protocol ASIO_SVC_TPARAM, typename EndpointSequence> -typename Protocol::endpoint connect( - basic_socket<Protocol ASIO_SVC_TARG>& s, +template <typename Protocol, typename Executor, typename EndpointSequence> +typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s, const EndpointSequence& endpoints, asio::error_code& ec, - typename enable_if<is_endpoint_sequence< - EndpointSequence>::value>::type* = 0); + constraint_t<is_endpoint_sequence<EndpointSequence>::value> = 0); #if !defined(ASIO_NO_DEPRECATED) -/// (Deprecated.) Establishes a socket connection by trying each endpoint in a -/// sequence. +/// (Deprecated: Use range overload.) 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 connect member @@ -155,12 +156,12 @@ typename Protocol::endpoint connect( * Iterator represents the end of the sequence. This is a valid assumption for * iterator types such as @c asio::ip::tcp::resolver::iterator. */ -template <typename Protocol ASIO_SVC_TPARAM, typename Iterator> -Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, Iterator begin, - typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0); +template <typename Protocol, typename Executor, typename Iterator> +Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin, + constraint_t<!is_endpoint_sequence<Iterator>::value> = 0); -/// (Deprecated.) Establishes a socket connection by trying each endpoint in a -/// sequence. +/// (Deprecated: Use range overload.) 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 connect member @@ -183,10 +184,10 @@ Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, Iterator begin, * Iterator represents the end of the sequence. This is a valid assumption for * iterator types such as @c asio::ip::tcp::resolver::iterator. */ -template <typename Protocol ASIO_SVC_TPARAM, typename Iterator> -Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, +template <typename Protocol, typename Executor, typename Iterator> +Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin, asio::error_code& ec, - typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0); + constraint_t<!is_endpoint_sequence<Iterator>::value> = 0); #endif // !defined(ASIO_NO_DEPRECATED) /// Establishes a socket connection by trying each endpoint in a sequence. @@ -210,14 +211,14 @@ Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * Otherwise, contains the error from the last connection attempt. * * @par Example - * @code tcp::resolver r(io_context); + * @code tcp::resolver r(my_context); * tcp::resolver::query q("host", "service"); * tcp::resolver::results_type e = r.resolve(q); - * tcp::socket s(io_context); + * tcp::socket s(my_context); * asio::connect(s, e.begin(), e.end()); @endcode */ -template <typename Protocol ASIO_SVC_TPARAM, typename Iterator> -Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, +template <typename Protocol, typename Executor, typename Iterator> +Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin, Iterator end); /// Establishes a socket connection by trying each endpoint in a sequence. @@ -242,10 +243,10 @@ Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * endpoint. Otherwise, the end iterator. * * @par Example - * @code tcp::resolver r(io_context); + * @code tcp::resolver r(my_context); * tcp::resolver::query q("host", "service"); * tcp::resolver::results_type e = r.resolve(q); - * tcp::socket s(io_context); + * tcp::socket s(my_context); * asio::error_code ec; * asio::connect(s, e.begin(), e.end(), ec); * if (ec) @@ -253,8 +254,8 @@ Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * // An error occurred. * } @endcode */ -template <typename Protocol ASIO_SVC_TPARAM, typename Iterator> -Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, +template <typename Protocol, typename Executor, typename Iterator> +Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin, Iterator end, asio::error_code& ec); /// Establishes a socket connection by trying each endpoint in a sequence. @@ -301,20 +302,18 @@ Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * } * }; @endcode * It would be used with the asio::connect function as follows: - * @code tcp::resolver r(io_context); + * @code tcp::resolver r(my_context); * tcp::resolver::query q("host", "service"); - * tcp::socket s(io_context); + * tcp::socket s(my_context); * tcp::endpoint e = asio::connect(s, * r.resolve(q), my_connect_condition()); * std::cout << "Connected to: " << e << std::endl; @endcode */ -template <typename Protocol ASIO_SVC_TPARAM, +template <typename Protocol, typename Executor, typename EndpointSequence, typename ConnectCondition> -typename Protocol::endpoint connect( - basic_socket<Protocol ASIO_SVC_TARG>& s, +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); + constraint_t<is_endpoint_sequence<EndpointSequence>::value> = 0); /// Establishes a socket connection by trying each endpoint in a sequence. /** @@ -361,9 +360,9 @@ typename Protocol::endpoint connect( * } * }; @endcode * It would be used with the asio::connect function as follows: - * @code tcp::resolver r(io_context); + * @code tcp::resolver r(my_context); * tcp::resolver::query q("host", "service"); - * tcp::socket s(io_context); + * tcp::socket s(my_context); * asio::error_code ec; * tcp::endpoint e = asio::connect(s, * r.resolve(q), my_connect_condition(), ec); @@ -376,18 +375,16 @@ typename Protocol::endpoint connect( * std::cout << "Connected to: " << e << std::endl; * } @endcode */ -template <typename Protocol ASIO_SVC_TPARAM, +template <typename Protocol, typename Executor, typename EndpointSequence, typename ConnectCondition> -typename Protocol::endpoint connect( - basic_socket<Protocol ASIO_SVC_TARG>& s, +typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s, const EndpointSequence& endpoints, ConnectCondition connect_condition, asio::error_code& ec, - typename enable_if<is_endpoint_sequence< - EndpointSequence>::value>::type* = 0); + constraint_t<is_endpoint_sequence<EndpointSequence>::value> = 0); #if !defined(ASIO_NO_DEPRECATED) -/// (Deprecated.) Establishes a socket connection by trying each endpoint in a -/// sequence. +/// (Deprecated: Use range overload.) 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 connect member @@ -421,14 +418,14 @@ typename Protocol::endpoint connect( * Iterator represents the end of the sequence. This is a valid assumption for * iterator types such as @c asio::ip::tcp::resolver::iterator. */ -template <typename Protocol ASIO_SVC_TPARAM, +template <typename Protocol, typename Executor, typename Iterator, typename ConnectCondition> -Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, +Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin, ConnectCondition connect_condition, - typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0); + constraint_t<!is_endpoint_sequence<Iterator>::value> = 0); -/// (Deprecated.) Establishes a socket connection by trying each endpoint in a -/// sequence. +/// (Deprecated: Use range overload.) 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 connect member @@ -462,11 +459,11 @@ Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * Iterator represents the end of the sequence. This is a valid assumption for * iterator types such as @c asio::ip::tcp::resolver::iterator. */ -template <typename Protocol ASIO_SVC_TPARAM, +template <typename Protocol, typename Executor, typename Iterator, typename ConnectCondition> -Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, Iterator begin, +Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin, ConnectCondition connect_condition, asio::error_code& ec, - typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0); + constraint_t<!is_endpoint_sequence<Iterator>::value> = 0); #endif // !defined(ASIO_NO_DEPRECATED) /// Establishes a socket connection by trying each endpoint in a sequence. @@ -515,17 +512,17 @@ Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, Iterator begin, * } * }; @endcode * It would be used with the asio::connect function as follows: - * @code tcp::resolver r(io_context); + * @code tcp::resolver r(my_context); * tcp::resolver::query q("host", "service"); * tcp::resolver::results_type e = r.resolve(q); - * tcp::socket s(io_context); + * tcp::socket s(my_context); * tcp::resolver::results_type::iterator i = asio::connect( * s, e.begin(), e.end(), my_connect_condition()); * std::cout << "Connected to: " << i->endpoint() << std::endl; @endcode */ -template <typename Protocol ASIO_SVC_TPARAM, +template <typename Protocol, typename Executor, typename Iterator, typename ConnectCondition> -Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, Iterator begin, +Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin, Iterator end, ConnectCondition connect_condition); /// Establishes a socket connection by trying each endpoint in a sequence. @@ -575,10 +572,10 @@ Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, Iterator begin, * } * }; @endcode * It would be used with the asio::connect function as follows: - * @code tcp::resolver r(io_context); + * @code tcp::resolver r(my_context); * tcp::resolver::query q("host", "service"); * tcp::resolver::results_type e = r.resolve(q); - * tcp::socket s(io_context); + * tcp::socket s(my_context); * asio::error_code ec; * tcp::resolver::results_type::iterator i = asio::connect( * s, e.begin(), e.end(), my_connect_condition()); @@ -591,9 +588,9 @@ Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, Iterator begin, * std::cout << "Connected to: " << i->endpoint() << std::endl; * } @endcode */ -template <typename Protocol ASIO_SVC_TPARAM, +template <typename Protocol, typename Executor, typename Iterator, typename ConnectCondition> -Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, +Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin, Iterator end, ConnectCondition connect_condition, asio::error_code& ec); @@ -602,8 +599,8 @@ Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, /** * @defgroup async_connect asio::async_connect * - * @brief Asynchronously establishes a socket connection by trying each - * endpoint in a sequence. + * @brief The @c async_connect function is a composed asynchronous operation + * that establishes a socket connection by trying each endpoint in a sequence. */ /*@{*/ @@ -613,16 +610,19 @@ Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * 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 * // asio::error::not_found. Otherwise, contains the @@ -634,14 +634,17 @@ Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * 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. Invocation - * of the handler will be performed in a manner equivalent to using - * asio::io_context::post(). + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a + * manner equivalent to using asio::post(). + * + * @par Completion Signature + * @code void(asio::error_code, typename Protocol::endpoint) @endcode * * @par Example - * @code tcp::resolver r(io_context); + * @code tcp::resolver r(my_context); * tcp::resolver::query q("host", "service"); - * tcp::socket s(io_context); + * tcp::socket s(my_context); * * // ... * @@ -667,34 +670,51 @@ Iterator connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * { * // ... * } @endcode + * + * @par Per-Operation Cancellation + * This asynchronous operation supports cancellation for the following + * asio::cancellation_type values: + * + * @li @c cancellation_type::terminal + * + * @li @c cancellation_type::partial + * + * if they are also supported by the socket's @c async_connect operation. */ -template <typename Protocol ASIO_SVC_TPARAM, - typename EndpointSequence, typename RangeConnectHandler> -ASIO_INITFN_RESULT_TYPE(RangeConnectHandler, - void (asio::error_code, typename Protocol::endpoint)) -async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, +template <typename Protocol, typename Executor, typename EndpointSequence, + ASIO_COMPLETION_TOKEN_FOR(void (asio::error_code, + typename Protocol::endpoint)) RangeConnectToken + = default_completion_token_t<Executor>> +auto async_connect(basic_socket<Protocol, Executor>& s, const EndpointSequence& endpoints, - ASIO_MOVE_ARG(RangeConnectHandler) handler, - typename enable_if<is_endpoint_sequence< - EndpointSequence>::value>::type* = 0); + RangeConnectToken&& token = default_completion_token_t<Executor>(), + constraint_t<is_endpoint_sequence<EndpointSequence>::value> = 0) + -> decltype( + async_initiate<RangeConnectToken, + void (asio::error_code, typename Protocol::endpoint)>( + declval<detail::initiate_async_range_connect<Protocol, Executor>>(), + token, endpoints, declval<detail::default_connect_condition>())); #if !defined(ASIO_NO_DEPRECATED) -/// (Deprecated.) Asynchronously establishes a socket connection by trying each -/// endpoint in a sequence. +/// (Deprecated: Use range overload.) Asynchronously 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 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 * // asio::error::not_found. Otherwise, contains the @@ -706,21 +726,39 @@ async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * Iterator iterator * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. Invocation - * of the handler will be performed in a manner equivalent to using - * asio::io_context::post(). + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a + * manner equivalent to using asio::post(). + * + * @par Completion Signature + * @code void(asio::error_code, 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 asio::ip::tcp::resolver::iterator. + * + * @par Per-Operation Cancellation + * This asynchronous operation supports cancellation for the following + * asio::cancellation_type values: + * + * @li @c cancellation_type::terminal + * + * @li @c cancellation_type::partial + * + * if they are also supported by the socket's @c async_connect operation. */ -template <typename Protocol ASIO_SVC_TPARAM, - typename Iterator, typename IteratorConnectHandler> -ASIO_INITFN_RESULT_TYPE(IteratorConnectHandler, - void (asio::error_code, Iterator)) -async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, - Iterator begin, ASIO_MOVE_ARG(IteratorConnectHandler) handler, - typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0); +template <typename Protocol, typename Executor, typename Iterator, + ASIO_COMPLETION_TOKEN_FOR(void (asio::error_code, + Iterator)) IteratorConnectToken = default_completion_token_t<Executor>> +auto async_connect(basic_socket<Protocol, Executor>& s, Iterator begin, + IteratorConnectToken&& token = default_completion_token_t<Executor>(), + constraint_t<!is_endpoint_sequence<Iterator>::value> = 0) + -> decltype( + async_initiate<IteratorConnectToken, + void (asio::error_code, Iterator)>( + declval<detail::initiate_async_iterator_connect<Protocol, Executor>>(), + token, begin, Iterator(), + declval<detail::default_connect_condition>())); #endif // !defined(ASIO_NO_DEPRECATED) /// Asynchronously establishes a socket connection by trying each endpoint in a @@ -729,7 +767,8 @@ async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * 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. @@ -738,9 +777,11 @@ async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * * @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 * // asio::error::not_found. Otherwise, contains the @@ -752,13 +793,16 @@ async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * Iterator iterator * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. Invocation - * of the handler will be performed in a manner equivalent to using - * asio::io_context::post(). + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a + * manner equivalent to using asio::post(). + * + * @par Completion Signature + * @code void(asio::error_code, Iterator) @endcode * * @par Example * @code std::vector<tcp::endpoint> endpoints = ...; - * tcp::socket s(io_context); + * tcp::socket s(my_context); * asio::async_connect(s, * endpoints.begin(), endpoints.end(), * connect_handler); @@ -771,14 +815,28 @@ async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * { * // ... * } @endcode + * + * @par Per-Operation Cancellation + * This asynchronous operation supports cancellation for the following + * asio::cancellation_type values: + * + * @li @c cancellation_type::terminal + * + * @li @c cancellation_type::partial + * + * if they are also supported by the socket's @c async_connect operation. */ -template <typename Protocol ASIO_SVC_TPARAM, - typename Iterator, typename IteratorConnectHandler> -ASIO_INITFN_RESULT_TYPE(IteratorConnectHandler, - void (asio::error_code, Iterator)) -async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, - Iterator begin, Iterator end, - ASIO_MOVE_ARG(IteratorConnectHandler) handler); +template <typename Protocol, typename Executor, typename Iterator, + ASIO_COMPLETION_TOKEN_FOR(void (asio::error_code, + Iterator)) IteratorConnectToken = default_completion_token_t<Executor>> +auto async_connect( + basic_socket<Protocol, Executor>& s, Iterator begin, Iterator end, + IteratorConnectToken&& token = default_completion_token_t<Executor>()) + -> decltype( + async_initiate<IteratorConnectToken, + void (asio::error_code, Iterator)>( + declval<detail::initiate_async_iterator_connect<Protocol, Executor>>(), + token, begin, end, declval<detail::default_connect_condition>())); /// Asynchronously establishes a socket connection by trying each endpoint in a /// sequence. @@ -786,7 +844,8 @@ async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * 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. @@ -804,9 +863,11 @@ async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * 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 * // asio::error::not_found. Otherwise, contains the @@ -818,9 +879,12 @@ async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * Iterator iterator * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. Invocation - * of the handler will be performed in a manner equivalent to using - * asio::io_context::post(). + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a + * manner equivalent to using asio::post(). + * + * @par Completion Signature + * @code void(asio::error_code, typename Protocol::endpoint) @endcode * * @par Example * The following connect condition function object can be used to output @@ -837,9 +901,9 @@ async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * } * }; @endcode * It would be used with the asio::connect function as follows: - * @code tcp::resolver r(io_context); + * @code tcp::resolver r(my_context); * tcp::resolver::query q("host", "service"); - * tcp::socket s(io_context); + * tcp::socket s(my_context); * * // ... * @@ -874,25 +938,41 @@ async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * std::cout << "Connected to: " << endpoint << std::endl; * } * } @endcode + * + * @par Per-Operation Cancellation + * This asynchronous operation supports cancellation for the following + * asio::cancellation_type values: + * + * @li @c cancellation_type::terminal + * + * @li @c cancellation_type::partial + * + * if they are also supported by the socket's @c async_connect operation. */ -template <typename Protocol ASIO_SVC_TPARAM, typename EndpointSequence, - typename ConnectCondition, typename RangeConnectHandler> -ASIO_INITFN_RESULT_TYPE(RangeConnectHandler, - void (asio::error_code, typename Protocol::endpoint)) -async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, +template <typename Protocol, typename Executor, + typename EndpointSequence, typename ConnectCondition, + ASIO_COMPLETION_TOKEN_FOR(void (asio::error_code, + typename Protocol::endpoint)) RangeConnectToken + = default_completion_token_t<Executor>> +auto async_connect(basic_socket<Protocol, Executor>& s, const EndpointSequence& endpoints, ConnectCondition connect_condition, - ASIO_MOVE_ARG(RangeConnectHandler) handler, - typename enable_if<is_endpoint_sequence< - EndpointSequence>::value>::type* = 0); + RangeConnectToken&& token = default_completion_token_t<Executor>(), + constraint_t<is_endpoint_sequence<EndpointSequence>::value> = 0) + -> decltype( + async_initiate<RangeConnectToken, + void (asio::error_code, typename Protocol::endpoint)>( + declval<detail::initiate_async_range_connect<Protocol, Executor>>(), + token, endpoints, connect_condition)); #if !defined(ASIO_NO_DEPRECATED) -/// (Deprecated.) Asynchronously establishes a socket connection by trying each -/// endpoint in a sequence. +/// (Deprecated: Use range overload.) Asynchronously 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. @@ -910,9 +990,11 @@ async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * 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 * // asio::error::not_found. Otherwise, contains the @@ -924,22 +1006,40 @@ async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, * Iterator iterator * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. Invocation - * of the handler will be performed in a manner equivalent to using - * asio::io_context::post(). + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a + * manner equivalent to using asio::post(). + * + * @par Completion Signature + * @code void(asio::error_code, 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 asio::ip::tcp::resolver::iterator. + * + * @par Per-Operation Cancellation + * This asynchronous operation supports cancellation for the following + * asio::cancellation_type values: + * + * @li @c cancellation_type::terminal + * + * @li @c cancellation_type::partial + * + * if they are also supported by the socket's @c async_connect operation. */ -template <typename Protocol ASIO_SVC_TPARAM, typename Iterator, - typename ConnectCondition, typename IteratorConnectHandler> -ASIO_INITFN_RESULT_TYPE(IteratorConnectHandler, - void (asio::error_code, Iterator)) -async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, Iterator begin, - ConnectCondition connect_condition, - ASIO_MOVE_ARG(IteratorConnectHandler) handler, - typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0); +template <typename Protocol, typename Executor, + typename Iterator, typename ConnectCondition, + ASIO_COMPLETION_TOKEN_FOR(void (asio::error_code, + Iterator)) IteratorConnectToken = default_completion_token_t<Executor>> +auto async_connect(basic_socket<Protocol, Executor>& s, + Iterator begin, ConnectCondition connect_condition, + IteratorConnectToken&& token = default_completion_token_t<Executor>(), + constraint_t<!is_endpoint_sequence<Iterator>::value> = 0) + -> decltype( + async_initiate<IteratorConnectToken, + void (asio::error_code, Iterator)>( + declval<detail::initiate_async_iterator_connect<Protocol, Executor>>(), + token, begin, Iterator(), connect_condition)); #endif // !defined(ASIO_NO_DEPRECATED) /// Asynchronously establishes a socket connection by trying each endpoint in a @@ -948,7 +1048,8 @@ async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, Iterator begin, * 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. @@ -968,9 +1069,11 @@ async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, Iterator begin, * 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 * // asio::error::not_found. Otherwise, contains the @@ -982,9 +1085,12 @@ async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, Iterator begin, * Iterator iterator * ); @endcode * Regardless of whether the asynchronous operation completes immediately or - * not, the handler will not be invoked from within this function. Invocation - * of the handler will be performed in a manner equivalent to using - * asio::io_context::post(). + * not, the completion handler will not be invoked from within this function. + * On immediate completion, invocation of the handler will be performed in a + * manner equivalent to using asio::post(). + * + * @par Completion Signature + * @code void(asio::error_code, Iterator) @endcode * * @par Example * The following connect condition function object can be used to output @@ -1001,9 +1107,9 @@ async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, Iterator begin, * } * }; @endcode * It would be used with the asio::connect function as follows: - * @code tcp::resolver r(io_context); + * @code tcp::resolver r(my_context); * tcp::resolver::query q("host", "service"); - * tcp::socket s(io_context); + * tcp::socket s(my_context); * * // ... * @@ -1039,14 +1145,29 @@ async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, Iterator begin, * std::cout << "Connected to: " << i->endpoint() << std::endl; * } * } @endcode + * + * @par Per-Operation Cancellation + * This asynchronous operation supports cancellation for the following + * asio::cancellation_type values: + * + * @li @c cancellation_type::terminal + * + * @li @c cancellation_type::partial + * + * if they are also supported by the socket's @c async_connect operation. */ -template <typename Protocol ASIO_SVC_TPARAM, typename Iterator, - typename ConnectCondition, typename IteratorConnectHandler> -ASIO_INITFN_RESULT_TYPE(IteratorConnectHandler, - void (asio::error_code, Iterator)) -async_connect(basic_socket<Protocol ASIO_SVC_TARG>& s, +template <typename Protocol, typename Executor, + typename Iterator, typename ConnectCondition, + ASIO_COMPLETION_TOKEN_FOR(void (asio::error_code, + Iterator)) IteratorConnectToken = default_completion_token_t<Executor>> +auto async_connect(basic_socket<Protocol, Executor>& s, Iterator begin, Iterator end, ConnectCondition connect_condition, - ASIO_MOVE_ARG(IteratorConnectHandler) handler); + IteratorConnectToken&& token = default_completion_token_t<Executor>()) + -> decltype( + async_initiate<IteratorConnectToken, + void (asio::error_code, Iterator)>( + declval<detail::initiate_async_iterator_connect<Protocol, Executor>>(), + token, begin, end, connect_condition)); /*@}*/ |