Add documentation for C++ 2011 (aka C++0x) support.
diff --git a/asio/src/doc/overview.qbk b/asio/src/doc/overview.qbk index 01aca0e..e596094 100644 --- a/asio/src/doc/overview.qbk +++ b/asio/src/doc/overview.qbk
@@ -33,6 +33,7 @@ * [link asio.overview.windows.stream_handle Stream-Oriented HANDLEs] * [link asio.overview.windows.random_access_handle Random-Access HANDLEs] * [link asio.overview.ssl SSL] +* [link asio.overview.cpp2011 C++ 2011 Support] * [link asio.overview.implementation Platform-Specific Implementation Notes] [include overview/rationale.qbk]
diff --git a/asio/src/doc/overview/cpp2011.qbk b/asio/src/doc/overview/cpp2011.qbk new file mode 100644 index 0000000..4fc7650 --- /dev/null +++ b/asio/src/doc/overview/cpp2011.qbk
@@ -0,0 +1,215 @@ +[/ + / Copyright (c) 2003-2011 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) + /] + +[section:cpp2011 C++ 2011 Support] + +[/boostify: non-boost docs start here] + +[link asio.overview.cpp2011.system_error System Errors and Error Codes] + +[/boostify: non-boost docs end here] + +[link asio.overview.cpp2011.move_objects Movable I/O Objects] + +[link asio.overview.cpp2011.move_handlers Movable Handlers] + +[link asio.overview.cpp2011.variadic Variadic Templates] + +[link asio.overview.cpp2011.array Array Container] + +[link asio.overview.cpp2011.atomic Atomics] + +[link asio.overview.cpp2011.shared_ptr Shared Pointers] + +[/boostify: non-boost docs start here] + +[section:system_error System Errors and Error Codes] + +When available, Asio can use the `std::error_code` and `std::system_error` +classes for reporting errors. In this case, the names `asio::error_code` and +`asio::system_error` will be typedefs for these standard classes. + +System error support is automatically enabled for [^g++] 4.6 and later, when +the [^-std=c++0x] or [^-std=gnu++0x] compiler options are used. It may be +disabled by defining `ASIO_DISABLE_STD_SYSTEM_ERROR`, or explicitly enabled for +other compilers by defining `ASIO_HAS_STD_SYSTEM_ERROR`. + +[endsect] + +[/boostify: non-boost docs end here] + +[section:move_objects Movable I/O Objects] + +When move support is available (via rvalue references), Asio allows move +construction and assignment of sockets, serial ports, POSIX descriptors and +Windows handles. + +Move support allows you to write code like: + + tcp::socket make_socket(io_service& i) + { + tcp::socket s(i); + ... + std::move(s); + } + +or: + + class connection : public enable_shared_from_this<connection> + { + private: + tcp::socket socket_; + ... + public: + connection(tcp::socket&& s) : socket_(std::move(s)) {} + ... + }; + + ... + + class server + { + private: + tcp::acceptor acceptor_; + tcp::socket socket_; + ... + void handle_accept(error_code ec) + { + if (!ec) + std::make_shared<connection>(std::move(socket_))->go(); + acceptor_.async_accept(socket_, ...); + } + ... + }; + +as well as: + + std::vector<tcp::socket> sockets; + sockets.push_back(tcp::socket(...)); + +A word of warning: There is nothing stopping you from moving these objects +while there are pending asynchronous operations, but it is unlikely to be a +good idea to do so. In particular, composed operations like [link +asio.reference.async_read async_read()] store a reference to the stream object. +Moving during the composed operation means that the composed operation may +attempt to access a moved-from object. + +Move support is automatically enabled for [^g++] 4.5 and later, when the +[^-std=c++0x] or [^-std=gnu++0x] compiler options are used. It may be disabled +by defining `ASIO_DISABLE_MOVE`, or explicitly enabled for other compilers by +defining `ASIO_HAS_MOVE`. Note that these macros also affect the availability +of [link asio.overview.cpp2011.move_handlers movable handlers]. + +[endsect] + +[section:move_handlers Movable Handlers] + +As an optimisation, user-defined completion handlers may provide move +constructors, and Asio's implementation will use a handler's move constructor +in preference to its copy constructor. In certain circumstances, Asio may be +able to eliminate all calls to a handler's copy constructor. However, handler +types are still required to be copy constructible. + +When move support is enabled, asynchronous that are documented as follows: + + template <typename Handler> + void async_XYZ(..., Handler handler); + +are actually declared as: + + template <typename Handler> + void async_XYZ(..., Handler&& handler); + +The handler argument is perfectly forwarded and the move construction occurs +within the body of `async_XYZ()`. This ensures that all other function +arguments are evaluated prior to the move. This is critical when the other +arguments to `async_XYZ()` are members of the handler. For example: + + struct my_operation + { + shared_ptr<tcp::socket> socket; + shared_ptr<vector<char>> buffer; + ... + void operator(error_code ec, size_t length) + { + ... + socket->async_read_some(asio::buffer(*buffer), std::move(*this)); + ... + } + }; + +Move support is automatically enabled for [^g++] 4.5 and later, when the +[^-std=c++0x] or [^-std=gnu++0x] compiler options are used. It may be disabled +by defining `ASIO_DISABLE_MOVE`, or explicitly enabled for other compilers by +defining `ASIO_HAS_MOVE`. Note that these macros also affect the availability +of [link asio.overview.cpp2011.move_objects movable I/O objects]. + +[endsect] + +[section:variadic Variadic Templates] + +When supported by a compiler, Asio can use variadic templates to implement the +[link asio.reference.basic_socket_streambuf.connect +basic_socket_streambuf::connect()] and [link +asio.reference.basic_socket_iostream.connect basic_socket_iostream::connect()] +functions. + +Support for variadic templates is automatically enabled for [^g++] 4.3 and +later, when the [^-std=c++0x] or [^-std=gnu++0x] compiler options are used. It +may be disabled by defining `ASIO_DISABLE_VARIADIC_TEMPLATES`, or explicitly +enabled for other compilers by defining `ASIO_HAS_VARIADIC_TEMPLATES`. + +[endsect] + +[section:array Array Container] + +Where the standard library provides `std::array<>`, Asio: + +* Provides overloads for the [link asio.reference.buffer buffer()] function. + +* Uses it in preference to `boost::array<>` for the + [link asio.reference.ip__address_v4.bytes_type ip::address_v4::bytes_type] and + [link asio.reference.ip__address_v6.bytes_type ip::address_v6::bytes_type] + types. + +* Uses it in preference to `boost::array<>` where a fixed size array type is + needed in the implementation. + +Support for `std::array<>` is automatically enabled for [^g++] 4.3 and later, +when the [^-std=c++0x] or [^-std=gnu++0x] compiler options are used, as well as +for Microsoft Visual C++ 10. It may be disabled by defining +`ASIO_DISABLE_STD_ARRAY`, or explicitly enabled for other compilers by +defining `ASIO_HAS_STD_ARRAY`. + +[endsect] + +[section:atomic Atomics] + +Asio's implementation can use `std::atomic<>` in preference to +`boost::detail::atomic_count`. + +Support for the standard atomic integer template is automatically enabled for +[^g++] 4.5 and later, when the [^-std=c++0x] or [^-std=gnu++0x] compiler +options are used. It may be disabled by defining `ASIO_DISABLE_STD_ATOMIC`, or +explicitly enabled for other compilers by defining `ASIO_HAS_STD_ATOMIC`. + +[endsect] + +[section:shared_ptr Shared Pointers] + +Asio's implementation can use `std::shared_ptr<>` and `std::weak_ptr<>` in +preference to the Boost equivalents. + +Support for the standard smart pointers is automatically enabled for [^g++] 4.3 +and later, when the [^-std=c++0x] or [^-std=gnu++0x] compiler options are used, +as well as for Microsoft Visual C++ 10. It may be disabled by defining +`ASIO_DISABLE_STD_SHARED_PTR`, or explicitly enabled for other compilers by +defining `ASIO_HAS_STD_SHARED_PTR`. + +[endsect] + +[endsect]