1[/ 2 / Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) 3 / 4 / Distributed under the Boost Software License, Version 1.0. (See accompanying 5 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 /] 7 8[section:cpp2011 C++ 2011 Support] 9 10 11[link boost_asio.overview.cpp2011.move_objects Movable I/O Objects] 12 13[link boost_asio.overview.cpp2011.move_handlers Movable Handlers] 14 15[link boost_asio.overview.cpp2011.variadic Variadic Templates] 16 17[link boost_asio.overview.cpp2011.array Array Container] 18 19[link boost_asio.overview.cpp2011.atomic Atomics] 20 21[link boost_asio.overview.cpp2011.shared_ptr Shared Pointers] 22 23[link boost_asio.overview.cpp2011.chrono Chrono] 24 25[link boost_asio.overview.cpp2011.futures Futures] 26 27 28[section:move_objects Movable I/O Objects] 29 30When move support is available (via rvalue references), Boost.Asio allows move 31construction and assignment of sockets, serial ports, POSIX descriptors and 32Windows handles. 33 34Move support allows you to write code like: 35 36 tcp::socket make_socket(io_context& i) 37 { 38 tcp::socket s(i); 39 ... 40 std::move(s); 41 } 42 43or: 44 45 class connection : public enable_shared_from_this<connection> 46 { 47 private: 48 tcp::socket socket_; 49 ... 50 public: 51 connection(tcp::socket&& s) : socket_(std::move(s)) {} 52 ... 53 }; 54 55 ... 56 57 class server 58 { 59 private: 60 tcp::acceptor acceptor_; 61 ... 62 void handle_accept(error_code ec, tcp::socket socket) 63 { 64 if (!ec) 65 std::make_shared<connection>(std::move(socket))->go(); 66 acceptor_.async_accept(...); 67 } 68 ... 69 }; 70 71as well as: 72 73 std::vector<tcp::socket> sockets; 74 sockets.push_back(tcp::socket(...)); 75 76A word of warning: There is nothing stopping you from moving these objects 77while there are pending asynchronous operations, but it is unlikely to be a 78good idea to do so. In particular, composed operations like [link 79boost_asio.reference.async_read async_read()] store a reference to the stream object. 80Moving during the composed operation means that the composed operation may 81attempt to access a moved-from object. 82 83Move support is automatically enabled for [^g++] 4.5 and later, when the 84[^-std=c++0x] or [^-std=gnu++0x] compiler options are used. It may be disabled 85by defining `BOOST_ASIO_DISABLE_MOVE`, or explicitly enabled for other compilers by 86defining `BOOST_ASIO_HAS_MOVE`. Note that these macros also affect the availability 87of [link boost_asio.overview.cpp2011.move_handlers movable handlers]. 88 89[endsect] 90 91[section:move_handlers Movable Handlers] 92 93With C++11 and later, user-defined completion handlers are only required to be 94move constructible, and are not required to be copy constructible. 95 96When move support is enabled, asynchronous that are documented as follows: 97 98 template <typename Handler> 99 void async_XYZ(..., Handler handler); 100 101are actually declared as: 102 103 template <typename Handler> 104 void async_XYZ(..., Handler&& handler); 105 106The handler argument is perfectly forwarded and the move construction occurs 107within the body of `async_XYZ()`. This ensures that all other function 108arguments are evaluated prior to the move. This is critical when the other 109arguments to `async_XYZ()` are members of the handler. For example: 110 111 struct my_operation 112 { 113 unique_ptr<tcp::socket> socket; 114 unique_ptr<vector<char>> buffer; 115 ... 116 void operator(error_code ec, size_t length) 117 { 118 ... 119 socket->async_read_some(boost::asio::buffer(*buffer), std::move(*this)); 120 ... 121 } 122 }; 123 124Move support is automatically enabled for [^g++] 4.5 and later, when the 125[^-std=c++0x] or [^-std=gnu++0x] compiler options are used. It may be disabled 126by defining `BOOST_ASIO_DISABLE_MOVE`, or explicitly enabled for other compilers by 127defining `BOOST_ASIO_HAS_MOVE`. Note that these macros also affect the availability 128of [link boost_asio.overview.cpp2011.move_objects movable I/O objects]. 129 130[endsect] 131 132[section:variadic Variadic Templates] 133 134When supported by a compiler, Boost.Asio can use variadic templates to implement the 135[link boost_asio.reference.basic_socket_streambuf.connect 136basic_socket_streambuf::connect()] and [link 137boost_asio.reference.basic_socket_iostream.connect basic_socket_iostream::connect()] 138functions. 139 140Support for variadic templates is automatically enabled for [^g++] 4.3 and 141later, when the [^-std=c++0x] or [^-std=gnu++0x] compiler options are used. It 142may be disabled by defining `BOOST_ASIO_DISABLE_VARIADIC_TEMPLATES`, or explicitly 143enabled for other compilers by defining `BOOST_ASIO_HAS_VARIADIC_TEMPLATES`. 144 145[endsect] 146 147[section:array Array Container] 148 149Where the standard library provides `std::array<>`, Boost.Asio: 150 151* Provides overloads for the [link boost_asio.reference.buffer buffer()] function. 152 153* Uses it in preference to `boost::array<>` for the 154 [link boost_asio.reference.ip__address_v4.bytes_type ip::address_v4::bytes_type] and 155 [link boost_asio.reference.ip__address_v6.bytes_type ip::address_v6::bytes_type] 156 types. 157 158* Uses it in preference to `boost::array<>` where a fixed size array type is 159 needed in the implementation. 160 161Support for `std::array<>` is automatically enabled for [^g++] 4.3 and later, 162when the [^-std=c++0x] or [^-std=gnu++0x] compiler options are used, as well as 163for Microsoft Visual C++ 10. It may be disabled by defining 164`BOOST_ASIO_DISABLE_STD_ARRAY`, or explicitly enabled for other compilers by 165defining `BOOST_ASIO_HAS_STD_ARRAY`. 166 167[endsect] 168 169[section:atomic Atomics] 170 171Boost.Asio's implementation can use `std::atomic<>` in preference to 172`boost::detail::atomic_count`. 173 174Support for the standard atomic integer template is automatically enabled for 175[^g++] 4.5 and later, when the [^-std=c++0x] or [^-std=gnu++0x] compiler 176options are used. It may be disabled by defining `BOOST_ASIO_DISABLE_STD_ATOMIC`, or 177explicitly enabled for other compilers by defining `BOOST_ASIO_HAS_STD_ATOMIC`. 178 179[endsect] 180 181[section:shared_ptr Shared Pointers] 182 183Boost.Asio's implementation can use `std::shared_ptr<>` and `std::weak_ptr<>` in 184preference to the Boost equivalents. 185 186Support for the standard smart pointers is automatically enabled for [^g++] 4.3 187and later, when the [^-std=c++0x] or [^-std=gnu++0x] compiler options are used, 188as well as for Microsoft Visual C++ 10. It may be disabled by defining 189`BOOST_ASIO_DISABLE_STD_SHARED_PTR`, or explicitly enabled for other compilers by 190defining `BOOST_ASIO_HAS_STD_SHARED_PTR`. 191 192[endsect] 193 194[section:chrono Chrono] 195 196Boost.Asio provides timers based on the `std::chrono` facilities via the [link 197boost_asio.reference.basic_waitable_timer basic_waitable_timer] class template. 198The typedefs [link boost_asio.reference.system_timer system_timer], [link 199boost_asio.reference.steady_timer steady_timer] and [link 200boost_asio.reference.high_resolution_timer high_resolution_timer] utilise the 201standard clocks `system_clock`, `steady_clock` and `high_resolution_clock` 202respectively. 203 204Support for the `std::chrono` facilities is automatically enabled for [^g++] 2054.6 and later, when the [^-std=c++0x] or [^-std=gnu++0x] compiler options are 206used. (Note that, for [^g++], the draft-standard `monotonic_clock` is used in 207place of `steady_clock`.) Support may be disabled by defining 208`BOOST_ASIO_DISABLE_STD_CHRONO`, or explicitly enabled for other compilers by 209defining `BOOST_ASIO_HAS_STD_CHRONO`. 210 211When standard `chrono` is unavailable, Boost.Asio will otherwise use the Boost.Chrono 212library. The [link boost_asio.reference.basic_waitable_timer basic_waitable_timer] 213class template may be used with either. 214 215[endsect] 216 217[section:futures Futures] 218 219The `boost::asio::use_future` special value provides first-class support for returning a 220C++11 `std::future` from an asynchronous operation's initiating function. 221 222To use `boost::asio::use_future`, pass it to an asynchronous operation instead of 223a normal completion handler. For example: 224 225 std::future<std::size_t> length = 226 my_socket.async_read_some(my_buffer, boost::asio::use_future); 227 228Where a handler signature has the form: 229 230 void handler(boost::system::error_code ec, result_type result); 231 232the initiating function returns a `std::future` templated on `result_type`. 233In the above example, this is `std::size_t`. If the asynchronous operation 234fails, the `error_code` is converted into a `system_error` exception and 235passed back to the caller through the future. 236 237Where a handler signature has the form: 238 239 void handler(boost::system::error_code ec); 240 241the initiating function returns `std::future<void>`. As above, an error 242is passed back in the future as a `system_error` exception. 243 244[link boost_asio.reference.use_future use_future], 245[link boost_asio.reference.use_future_t use_future_t], 246[link boost_asio.examples.cpp11_examples.futures Futures example (C++11)]. 247 248[endsect] 249 250[endsect] 251