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