summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/asio/src/doc/overview/cpp2011.qbk
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/asio/src/doc/overview/cpp2011.qbk')
-rw-r--r--3rdparty/asio/src/doc/overview/cpp2011.qbk275
1 files changed, 275 insertions, 0 deletions
diff --git a/3rdparty/asio/src/doc/overview/cpp2011.qbk b/3rdparty/asio/src/doc/overview/cpp2011.qbk
new file mode 100644
index 00000000000..fa9e6622b67
--- /dev/null
+++ b/3rdparty/asio/src/doc/overview/cpp2011.qbk
@@ -0,0 +1,275 @@
+[/
+ / Copyright (c) 2003-2016 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]
+
+[link asio.overview.cpp2011.chrono Chrono]
+
+[link asio.overview.cpp2011.futures Futures]
+
+[/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_context& 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]
+
+[section:chrono Chrono]
+
+Asio provides timers based on the `std::chrono` facilities via the [link
+asio.reference.basic_waitable_timer basic_waitable_timer] class template.
+The typedefs [link asio.reference.system_timer system_timer], [link
+asio.reference.steady_timer steady_timer] and [link
+asio.reference.high_resolution_timer high_resolution_timer] utilise the
+standard clocks `system_clock`, `steady_clock` and `high_resolution_clock`
+respectively.
+
+Support for the `std::chrono` facilities is automatically enabled for [^g++]
+4.6 and later, when the [^-std=c++0x] or [^-std=gnu++0x] compiler options are
+used. (Note that, for [^g++], the draft-standard `monotonic_clock` is used in
+place of `steady_clock`.) Support may be disabled by defining
+`ASIO_DISABLE_STD_CHRONO`, or explicitly enabled for other compilers by
+defining `ASIO_HAS_STD_CHRONO`.
+
+When standard `chrono` is unavailable, Asio will otherwise use the Boost.Chrono
+library. The [link asio.reference.basic_waitable_timer basic_waitable_timer]
+class template may be used with either.
+
+[endsect]
+
+[section:futures Futures]
+
+The `asio::use_future` special value provides first-class support for returning a
+C++11 `std::future` from an asynchronous operation's initiating function.
+
+To use `asio::use_future`, pass it to an asynchronous operation instead of
+a normal completion handler. For example:
+
+ std::future<std::size_t> length =
+ my_socket.async_read_some(my_buffer, asio::use_future);
+
+Where a handler signature has the form:
+
+ void handler(asio::error_code ec, result_type result);
+
+the initiating function returns a `std::future` templated on `result_type`.
+In the above example, this is `std::size_t`. If the asynchronous operation
+fails, the `error_code` is converted into a `system_error` exception and
+passed back to the caller through the future.
+
+Where a handler signature has the form:
+
+ void handler(asio::error_code ec);
+
+the initiating function returns `std::future<void>`. As above, an error
+is passed back in the future as a `system_error` exception.
+
+[link asio.reference.use_future use_future],
+[link asio.reference.use_future_t use_future_t],
+[link asio.examples.cpp11_examples.futures Futures example (C++11)].
+
+[endsect]
+
+[endsect]