1//
2// write.hpp
3// ~~~~~~~~~
4//
5// Copyright (c) 2003-2024 Christopher M. Kohlhoff (chris at kohlhoff dot com)
6//
7// Distributed under the Boost Software License, Version 1.0. (See accompanying
8// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
9//
10
11#ifndef BOOST_ASIO_WRITE_HPP
12#define BOOST_ASIO_WRITE_HPP
13
14#if defined(_MSC_VER) && (_MSC_VER >= 1200)
15# pragma once
16#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
17
18#include <boost/asio/detail/config.hpp>
19#include <cstddef>
20#include <boost/asio/async_result.hpp>
21#include <boost/asio/buffer.hpp>
22#include <boost/asio/completion_condition.hpp>
23#include <boost/asio/error.hpp>
24
25#if !defined(BOOST_ASIO_NO_EXTENSIONS)
26# include <boost/asio/basic_streambuf_fwd.hpp>
27#endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
28
29#include <boost/asio/detail/push_options.hpp>
30
31namespace boost {
32namespace asio {
33namespace detail {
34
35template <typename> class initiate_async_write;
36#if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
37template <typename> class initiate_async_write_dynbuf_v1;
38#endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
39template <typename> class initiate_async_write_dynbuf_v2;
40
41} // namespace detail
42
43/**
44 * @defgroup write boost::asio::write
45 *
46 * @brief The @c write function is a composed operation that writes a certain
47 * amount of data to a stream before returning.
48 */
49/*@{*/
50
51/// Write all of the supplied data to a stream before returning.
52/**
53 * This function is used to write a certain number of bytes of data to a stream.
54 * The call will block until one of the following conditions is true:
55 *
56 * @li All of the data in the supplied buffers has been written. That is, the
57 * bytes transferred is equal to the sum of the buffer sizes.
58 *
59 * @li An error occurred.
60 *
61 * This operation is implemented in terms of zero or more calls to the stream's
62 * write_some function.
63 *
64 * @param s The stream to which the data is to be written. The type must support
65 * the SyncWriteStream concept.
66 *
67 * @param buffers One or more buffers containing the data to be written. The sum
68 * of the buffer sizes indicates the maximum number of bytes to write to the
69 * stream.
70 *
71 * @returns The number of bytes transferred.
72 *
73 * @throws boost::system::system_error Thrown on failure.
74 *
75 * @par Example
76 * To write a single data buffer use the @ref buffer function as follows:
77 * @code boost::asio::write(s, boost::asio::buffer(data, size)); @endcode
78 * See the @ref buffer documentation for information on writing multiple
79 * buffers in one go, and how to use it with arrays, boost::array or
80 * std::vector.
81 *
82 * @note This overload is equivalent to calling:
83 * @code boost::asio::write(
84 * s, buffers,
85 * boost::asio::transfer_all()); @endcode
86 */
87template <typename SyncWriteStream, typename ConstBufferSequence>
88std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers,
89 constraint_t<
90 is_const_buffer_sequence<ConstBufferSequence>::value
91 > = 0);
92
93/// Write all of the supplied data to a stream before returning.
94/**
95 * This function is used to write a certain number of bytes of data to a stream.
96 * The call will block until one of the following conditions is true:
97 *
98 * @li All of the data in the supplied buffers has been written. That is, the
99 * bytes transferred is equal to the sum of the buffer sizes.
100 *
101 * @li An error occurred.
102 *
103 * This operation is implemented in terms of zero or more calls to the stream's
104 * write_some function.
105 *
106 * @param s The stream to which the data is to be written. The type must support
107 * the SyncWriteStream concept.
108 *
109 * @param buffers One or more buffers containing the data to be written. The sum
110 * of the buffer sizes indicates the maximum number of bytes to write to the
111 * stream.
112 *
113 * @param ec Set to indicate what error occurred, if any.
114 *
115 * @returns The number of bytes transferred.
116 *
117 * @par Example
118 * To write a single data buffer use the @ref buffer function as follows:
119 * @code boost::asio::write(s, boost::asio::buffer(data, size), ec); @endcode
120 * See the @ref buffer documentation for information on writing multiple
121 * buffers in one go, and how to use it with arrays, boost::array or
122 * std::vector.
123 *
124 * @note This overload is equivalent to calling:
125 * @code boost::asio::write(
126 * s, buffers,
127 * boost::asio::transfer_all(), ec); @endcode
128 */
129template <typename SyncWriteStream, typename ConstBufferSequence>
130std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers,
131 boost::system::error_code& ec,
132 constraint_t<
133 is_const_buffer_sequence<ConstBufferSequence>::value
134 > = 0);
135
136/// Write a certain amount of data to a stream before returning.
137/**
138 * This function is used to write a certain number of bytes of data to a stream.
139 * The call will block until one of the following conditions is true:
140 *
141 * @li All of the data in the supplied buffers has been written. That is, the
142 * bytes transferred is equal to the sum of the buffer sizes.
143 *
144 * @li The completion_condition function object returns 0.
145 *
146 * This operation is implemented in terms of zero or more calls to the stream's
147 * write_some function.
148 *
149 * @param s The stream to which the data is to be written. The type must support
150 * the SyncWriteStream concept.
151 *
152 * @param buffers One or more buffers containing the data to be written. The sum
153 * of the buffer sizes indicates the maximum number of bytes to write to the
154 * stream.
155 *
156 * @param completion_condition The function object to be called to determine
157 * whether the write operation is complete. The signature of the function object
158 * must be:
159 * @code std::size_t completion_condition(
160 * // Result of latest write_some operation.
161 * const boost::system::error_code& error,
162 *
163 * // Number of bytes transferred so far.
164 * std::size_t bytes_transferred
165 * ); @endcode
166 * A return value of 0 indicates that the write operation is complete. A
167 * non-zero return value indicates the maximum number of bytes to be written on
168 * the next call to the stream's write_some function.
169 *
170 * @returns The number of bytes transferred.
171 *
172 * @throws boost::system::system_error Thrown on failure.
173 *
174 * @par Example
175 * To write a single data buffer use the @ref buffer function as follows:
176 * @code boost::asio::write(s, boost::asio::buffer(data, size),
177 * boost::asio::transfer_at_least(32)); @endcode
178 * See the @ref buffer documentation for information on writing multiple
179 * buffers in one go, and how to use it with arrays, boost::array or
180 * std::vector.
181 */
182template <typename SyncWriteStream, typename ConstBufferSequence,
183 typename CompletionCondition>
184std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers,
185 CompletionCondition completion_condition,
186 constraint_t<
187 is_const_buffer_sequence<ConstBufferSequence>::value
188 > = 0);
189
190/// Write a certain amount of data to a stream before returning.
191/**
192 * This function is used to write a certain number of bytes of data to a stream.
193 * The call will block until one of the following conditions is true:
194 *
195 * @li All of the data in the supplied buffers has been written. That is, the
196 * bytes transferred is equal to the sum of the buffer sizes.
197 *
198 * @li The completion_condition function object returns 0.
199 *
200 * This operation is implemented in terms of zero or more calls to the stream's
201 * write_some function.
202 *
203 * @param s The stream to which the data is to be written. The type must support
204 * the SyncWriteStream concept.
205 *
206 * @param buffers One or more buffers containing the data to be written. The sum
207 * of the buffer sizes indicates the maximum number of bytes to write to the
208 * stream.
209 *
210 * @param completion_condition The function object to be called to determine
211 * whether the write operation is complete. The signature of the function object
212 * must be:
213 * @code std::size_t completion_condition(
214 * // Result of latest write_some operation.
215 * const boost::system::error_code& error,
216 *
217 * // Number of bytes transferred so far.
218 * std::size_t bytes_transferred
219 * ); @endcode
220 * A return value of 0 indicates that the write operation is complete. A
221 * non-zero return value indicates the maximum number of bytes to be written on
222 * the next call to the stream's write_some function.
223 *
224 * @param ec Set to indicate what error occurred, if any.
225 *
226 * @returns The number of bytes written. If an error occurs, returns the total
227 * number of bytes successfully transferred prior to the error.
228 */
229template <typename SyncWriteStream, typename ConstBufferSequence,
230 typename CompletionCondition>
231std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers,
232 CompletionCondition completion_condition, boost::system::error_code& ec,
233 constraint_t<
234 is_const_buffer_sequence<ConstBufferSequence>::value
235 > = 0);
236
237#if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
238
239/// Write all of the supplied data to a stream before returning.
240/**
241 * This function is used to write a certain number of bytes of data to a stream.
242 * The call will block until one of the following conditions is true:
243 *
244 * @li All of the data in the supplied dynamic buffer sequence has been written.
245 *
246 * @li An error occurred.
247 *
248 * This operation is implemented in terms of zero or more calls to the stream's
249 * write_some function.
250 *
251 * @param s The stream to which the data is to be written. The type must support
252 * the SyncWriteStream concept.
253 *
254 * @param buffers The dynamic buffer sequence from which data will be written.
255 * Successfully written data is automatically consumed from the buffers.
256 *
257 * @returns The number of bytes transferred.
258 *
259 * @throws boost::system::system_error Thrown on failure.
260 *
261 * @note This overload is equivalent to calling:
262 * @code boost::asio::write(
263 * s, buffers,
264 * boost::asio::transfer_all()); @endcode
265 */
266template <typename SyncWriteStream, typename DynamicBuffer_v1>
267std::size_t write(SyncWriteStream& s,
268 DynamicBuffer_v1&& buffers,
269 constraint_t<
270 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
271 > = 0,
272 constraint_t<
273 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
274 > = 0);
275
276/// Write all of the supplied data to a stream before returning.
277/**
278 * This function is used to write a certain number of bytes of data to a stream.
279 * The call will block until one of the following conditions is true:
280 *
281 * @li All of the data in the supplied dynamic buffer sequence has been written.
282 *
283 * @li An error occurred.
284 *
285 * This operation is implemented in terms of zero or more calls to the stream's
286 * write_some function.
287 *
288 * @param s The stream to which the data is to be written. The type must support
289 * the SyncWriteStream concept.
290 *
291 * @param buffers The dynamic buffer sequence from which data will be written.
292 * Successfully written data is automatically consumed from the buffers.
293 *
294 * @param ec Set to indicate what error occurred, if any.
295 *
296 * @returns The number of bytes transferred.
297 *
298 * @note This overload is equivalent to calling:
299 * @code boost::asio::write(
300 * s, buffers,
301 * boost::asio::transfer_all(), ec); @endcode
302 */
303template <typename SyncWriteStream, typename DynamicBuffer_v1>
304std::size_t write(SyncWriteStream& s,
305 DynamicBuffer_v1&& buffers,
306 boost::system::error_code& ec,
307 constraint_t<
308 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
309 > = 0,
310 constraint_t<
311 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
312 > = 0);
313
314/// Write a certain amount of data to a stream before returning.
315/**
316 * This function is used to write a certain number of bytes of data to a stream.
317 * The call will block until one of the following conditions is true:
318 *
319 * @li All of the data in the supplied dynamic buffer sequence has been written.
320 *
321 * @li The completion_condition function object returns 0.
322 *
323 * This operation is implemented in terms of zero or more calls to the stream's
324 * write_some function.
325 *
326 * @param s The stream to which the data is to be written. The type must support
327 * the SyncWriteStream concept.
328 *
329 * @param buffers The dynamic buffer sequence from which data will be written.
330 * Successfully written data is automatically consumed from the buffers.
331 *
332 * @param completion_condition The function object to be called to determine
333 * whether the write operation is complete. The signature of the function object
334 * must be:
335 * @code std::size_t completion_condition(
336 * // Result of latest write_some operation.
337 * const boost::system::error_code& error,
338 *
339 * // Number of bytes transferred so far.
340 * std::size_t bytes_transferred
341 * ); @endcode
342 * A return value of 0 indicates that the write operation is complete. A
343 * non-zero return value indicates the maximum number of bytes to be written on
344 * the next call to the stream's write_some function.
345 *
346 * @returns The number of bytes transferred.
347 *
348 * @throws boost::system::system_error Thrown on failure.
349 */
350template <typename SyncWriteStream, typename DynamicBuffer_v1,
351 typename CompletionCondition>
352std::size_t write(SyncWriteStream& s,
353 DynamicBuffer_v1&& buffers,
354 CompletionCondition completion_condition,
355 constraint_t<
356 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
357 > = 0,
358 constraint_t<
359 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
360 > = 0);
361
362/// Write a certain amount of data to a stream before returning.
363/**
364 * This function is used to write a certain number of bytes of data to a stream.
365 * The call will block until one of the following conditions is true:
366 *
367 * @li All of the data in the supplied dynamic buffer sequence has been written.
368 *
369 * @li The completion_condition function object returns 0.
370 *
371 * This operation is implemented in terms of zero or more calls to the stream's
372 * write_some function.
373 *
374 * @param s The stream to which the data is to be written. The type must support
375 * the SyncWriteStream concept.
376 *
377 * @param buffers The dynamic buffer sequence from which data will be written.
378 * Successfully written data is automatically consumed from the buffers.
379 *
380 * @param completion_condition The function object to be called to determine
381 * whether the write operation is complete. The signature of the function object
382 * must be:
383 * @code std::size_t completion_condition(
384 * // Result of latest write_some operation.
385 * const boost::system::error_code& error,
386 *
387 * // Number of bytes transferred so far.
388 * std::size_t bytes_transferred
389 * ); @endcode
390 * A return value of 0 indicates that the write operation is complete. A
391 * non-zero return value indicates the maximum number of bytes to be written on
392 * the next call to the stream's write_some function.
393 *
394 * @param ec Set to indicate what error occurred, if any.
395 *
396 * @returns The number of bytes written. If an error occurs, returns the total
397 * number of bytes successfully transferred prior to the error.
398 */
399template <typename SyncWriteStream, typename DynamicBuffer_v1,
400 typename CompletionCondition>
401std::size_t write(SyncWriteStream& s,
402 DynamicBuffer_v1&& buffers,
403 CompletionCondition completion_condition, boost::system::error_code& ec,
404 constraint_t<
405 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
406 > = 0,
407 constraint_t<
408 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
409 > = 0);
410
411#if !defined(BOOST_ASIO_NO_EXTENSIONS)
412#if !defined(BOOST_ASIO_NO_IOSTREAM)
413
414/// Write all of the supplied data to a stream before returning.
415/**
416 * This function is used to write a certain number of bytes of data to a stream.
417 * The call will block until one of the following conditions is true:
418 *
419 * @li All of the data in the supplied basic_streambuf has been written.
420 *
421 * @li An error occurred.
422 *
423 * This operation is implemented in terms of zero or more calls to the stream's
424 * write_some function.
425 *
426 * @param s The stream to which the data is to be written. The type must support
427 * the SyncWriteStream concept.
428 *
429 * @param b The basic_streambuf object from which data will be written.
430 *
431 * @returns The number of bytes transferred.
432 *
433 * @throws boost::system::system_error Thrown on failure.
434 *
435 * @note This overload is equivalent to calling:
436 * @code boost::asio::write(
437 * s, b,
438 * boost::asio::transfer_all()); @endcode
439 */
440template <typename SyncWriteStream, typename Allocator>
441std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b);
442
443/// Write all of the supplied data to a stream before returning.
444/**
445 * This function is used to write a certain number of bytes of data to a stream.
446 * The call will block until one of the following conditions is true:
447 *
448 * @li All of the data in the supplied basic_streambuf has been written.
449 *
450 * @li An error occurred.
451 *
452 * This operation is implemented in terms of zero or more calls to the stream's
453 * write_some function.
454 *
455 * @param s The stream to which the data is to be written. The type must support
456 * the SyncWriteStream concept.
457 *
458 * @param b The basic_streambuf object from which data will be written.
459 *
460 * @param ec Set to indicate what error occurred, if any.
461 *
462 * @returns The number of bytes transferred.
463 *
464 * @note This overload is equivalent to calling:
465 * @code boost::asio::write(
466 * s, b,
467 * boost::asio::transfer_all(), ec); @endcode
468 */
469template <typename SyncWriteStream, typename Allocator>
470std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b,
471 boost::system::error_code& ec);
472
473/// Write a certain amount of data to a stream before returning.
474/**
475 * This function is used to write a certain number of bytes of data to a stream.
476 * The call will block until one of the following conditions is true:
477 *
478 * @li All of the data in the supplied basic_streambuf has been written.
479 *
480 * @li The completion_condition function object returns 0.
481 *
482 * This operation is implemented in terms of zero or more calls to the stream's
483 * write_some function.
484 *
485 * @param s The stream to which the data is to be written. The type must support
486 * the SyncWriteStream concept.
487 *
488 * @param b The basic_streambuf object from which data will be written.
489 *
490 * @param completion_condition The function object to be called to determine
491 * whether the write operation is complete. The signature of the function object
492 * must be:
493 * @code std::size_t completion_condition(
494 * // Result of latest write_some operation.
495 * const boost::system::error_code& error,
496 *
497 * // Number of bytes transferred so far.
498 * std::size_t bytes_transferred
499 * ); @endcode
500 * A return value of 0 indicates that the write operation is complete. A
501 * non-zero return value indicates the maximum number of bytes to be written on
502 * the next call to the stream's write_some function.
503 *
504 * @returns The number of bytes transferred.
505 *
506 * @throws boost::system::system_error Thrown on failure.
507 */
508template <typename SyncWriteStream, typename Allocator,
509 typename CompletionCondition>
510std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b,
511 CompletionCondition completion_condition);
512
513/// Write a certain amount of data to a stream before returning.
514/**
515 * This function is used to write a certain number of bytes of data to a stream.
516 * The call will block until one of the following conditions is true:
517 *
518 * @li All of the data in the supplied basic_streambuf has been written.
519 *
520 * @li The completion_condition function object returns 0.
521 *
522 * This operation is implemented in terms of zero or more calls to the stream's
523 * write_some function.
524 *
525 * @param s The stream to which the data is to be written. The type must support
526 * the SyncWriteStream concept.
527 *
528 * @param b The basic_streambuf object from which data will be written.
529 *
530 * @param completion_condition The function object to be called to determine
531 * whether the write operation is complete. The signature of the function object
532 * must be:
533 * @code std::size_t completion_condition(
534 * // Result of latest write_some operation.
535 * const boost::system::error_code& error,
536 *
537 * // Number of bytes transferred so far.
538 * std::size_t bytes_transferred
539 * ); @endcode
540 * A return value of 0 indicates that the write operation is complete. A
541 * non-zero return value indicates the maximum number of bytes to be written on
542 * the next call to the stream's write_some function.
543 *
544 * @param ec Set to indicate what error occurred, if any.
545 *
546 * @returns The number of bytes written. If an error occurs, returns the total
547 * number of bytes successfully transferred prior to the error.
548 */
549template <typename SyncWriteStream, typename Allocator,
550 typename CompletionCondition>
551std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b,
552 CompletionCondition completion_condition, boost::system::error_code& ec);
553
554#endif // !defined(BOOST_ASIO_NO_IOSTREAM)
555#endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
556#endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
557
558/// Write all of the supplied data to a stream before returning.
559/**
560 * This function is used to write a certain number of bytes of data to a stream.
561 * The call will block until one of the following conditions is true:
562 *
563 * @li All of the data in the supplied dynamic buffer sequence has been written.
564 *
565 * @li An error occurred.
566 *
567 * This operation is implemented in terms of zero or more calls to the stream's
568 * write_some function.
569 *
570 * @param s The stream to which the data is to be written. The type must support
571 * the SyncWriteStream concept.
572 *
573 * @param buffers The dynamic buffer sequence from which data will be written.
574 * Successfully written data is automatically consumed from the buffers.
575 *
576 * @returns The number of bytes transferred.
577 *
578 * @throws boost::system::system_error Thrown on failure.
579 *
580 * @note This overload is equivalent to calling:
581 * @code boost::asio::write(
582 * s, buffers,
583 * boost::asio::transfer_all()); @endcode
584 */
585template <typename SyncWriteStream, typename DynamicBuffer_v2>
586std::size_t write(SyncWriteStream& s, DynamicBuffer_v2 buffers,
587 constraint_t<
588 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
589 > = 0);
590
591/// Write all of the supplied data to a stream before returning.
592/**
593 * This function is used to write a certain number of bytes of data to a stream.
594 * The call will block until one of the following conditions is true:
595 *
596 * @li All of the data in the supplied dynamic buffer sequence has been written.
597 *
598 * @li An error occurred.
599 *
600 * This operation is implemented in terms of zero or more calls to the stream's
601 * write_some function.
602 *
603 * @param s The stream to which the data is to be written. The type must support
604 * the SyncWriteStream concept.
605 *
606 * @param buffers The dynamic buffer sequence from which data will be written.
607 * Successfully written data is automatically consumed from the buffers.
608 *
609 * @param ec Set to indicate what error occurred, if any.
610 *
611 * @returns The number of bytes transferred.
612 *
613 * @note This overload is equivalent to calling:
614 * @code boost::asio::write(
615 * s, buffers,
616 * boost::asio::transfer_all(), ec); @endcode
617 */
618template <typename SyncWriteStream, typename DynamicBuffer_v2>
619std::size_t write(SyncWriteStream& s, DynamicBuffer_v2 buffers,
620 boost::system::error_code& ec,
621 constraint_t<
622 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
623 > = 0);
624
625/// Write a certain amount of data to a stream before returning.
626/**
627 * This function is used to write a certain number of bytes of data to a stream.
628 * The call will block until one of the following conditions is true:
629 *
630 * @li All of the data in the supplied dynamic buffer sequence has been written.
631 *
632 * @li The completion_condition function object returns 0.
633 *
634 * This operation is implemented in terms of zero or more calls to the stream's
635 * write_some function.
636 *
637 * @param s The stream to which the data is to be written. The type must support
638 * the SyncWriteStream concept.
639 *
640 * @param buffers The dynamic buffer sequence from which data will be written.
641 * Successfully written data is automatically consumed from the buffers.
642 *
643 * @param completion_condition The function object to be called to determine
644 * whether the write operation is complete. The signature of the function object
645 * must be:
646 * @code std::size_t completion_condition(
647 * // Result of latest write_some operation.
648 * const boost::system::error_code& error,
649 *
650 * // Number of bytes transferred so far.
651 * std::size_t bytes_transferred
652 * ); @endcode
653 * A return value of 0 indicates that the write operation is complete. A
654 * non-zero return value indicates the maximum number of bytes to be written on
655 * the next call to the stream's write_some function.
656 *
657 * @returns The number of bytes transferred.
658 *
659 * @throws boost::system::system_error Thrown on failure.
660 */
661template <typename SyncWriteStream, typename DynamicBuffer_v2,
662 typename CompletionCondition>
663std::size_t write(SyncWriteStream& s, DynamicBuffer_v2 buffers,
664 CompletionCondition completion_condition,
665 constraint_t<
666 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
667 > = 0);
668
669/// Write a certain amount of data to a stream before returning.
670/**
671 * This function is used to write a certain number of bytes of data to a stream.
672 * The call will block until one of the following conditions is true:
673 *
674 * @li All of the data in the supplied dynamic buffer sequence has been written.
675 *
676 * @li The completion_condition function object returns 0.
677 *
678 * This operation is implemented in terms of zero or more calls to the stream's
679 * write_some function.
680 *
681 * @param s The stream to which the data is to be written. The type must support
682 * the SyncWriteStream concept.
683 *
684 * @param buffers The dynamic buffer sequence from which data will be written.
685 * Successfully written data is automatically consumed from the buffers.
686 *
687 * @param completion_condition The function object to be called to determine
688 * whether the write operation is complete. The signature of the function object
689 * must be:
690 * @code std::size_t completion_condition(
691 * // Result of latest write_some operation.
692 * const boost::system::error_code& error,
693 *
694 * // Number of bytes transferred so far.
695 * std::size_t bytes_transferred
696 * ); @endcode
697 * A return value of 0 indicates that the write operation is complete. A
698 * non-zero return value indicates the maximum number of bytes to be written on
699 * the next call to the stream's write_some function.
700 *
701 * @param ec Set to indicate what error occurred, if any.
702 *
703 * @returns The number of bytes written. If an error occurs, returns the total
704 * number of bytes successfully transferred prior to the error.
705 */
706template <typename SyncWriteStream, typename DynamicBuffer_v2,
707 typename CompletionCondition>
708std::size_t write(SyncWriteStream& s, DynamicBuffer_v2 buffers,
709 CompletionCondition completion_condition, boost::system::error_code& ec,
710 constraint_t<
711 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
712 > = 0);
713
714/*@}*/
715/**
716 * @defgroup async_write boost::asio::async_write
717 *
718 * @brief The @c async_write function is a composed asynchronous operation that
719 * writes a certain amount of data to a stream before completion.
720 */
721/*@{*/
722
723/// Start an asynchronous operation to write all of the supplied data to a
724/// stream.
725/**
726 * This function is used to asynchronously write a certain number of bytes of
727 * data to a stream. It is an initiating function for an @ref
728 * asynchronous_operation, and always returns immediately. The asynchronous
729 * operation will continue until one of the following conditions is true:
730 *
731 * @li All of the data in the supplied buffers has been written. That is, the
732 * bytes transferred is equal to the sum of the buffer sizes.
733 *
734 * @li An error occurred.
735 *
736 * This operation is implemented in terms of zero or more calls to the stream's
737 * async_write_some function, and is known as a <em>composed operation</em>. The
738 * program must ensure that the stream performs no other write operations (such
739 * as async_write, the stream's async_write_some function, or any other composed
740 * operations that perform writes) until this operation completes.
741 *
742 * @param s The stream to which the data is to be written. The type must support
743 * the AsyncWriteStream concept.
744 *
745 * @param buffers One or more buffers containing the data to be written.
746 * Although the buffers object may be copied as necessary, ownership of the
747 * underlying memory blocks is retained by the caller, which must guarantee
748 * that they remain valid until the completion handler is called.
749 *
750 * @param token The @ref completion_token that will be used to produce a
751 * completion handler, which will be called when the write completes.
752 * Potential completion tokens include @ref use_future, @ref use_awaitable,
753 * @ref yield_context, or a function object with the correct completion
754 * signature. The function signature of the completion handler must be:
755 * @code void handler(
756 * // Result of operation.
757 * const boost::system::error_code& error,
758 *
759 * // Number of bytes written from the buffers. If an error
760 * // occurred, this will be less than the sum of the buffer sizes.
761 * std::size_t bytes_transferred
762 * ); @endcode
763 * Regardless of whether the asynchronous operation completes immediately or
764 * not, the completion handler will not be invoked from within this function.
765 * On immediate completion, invocation of the handler will be performed in a
766 * manner equivalent to using boost::asio::post().
767 *
768 * @par Completion Signature
769 * @code void(boost::system::error_code, std::size_t) @endcode
770 *
771 * @par Example
772 * To write a single data buffer use the @ref buffer function as follows:
773 * @code
774 * boost::asio::async_write(s, boost::asio::buffer(data, size), handler);
775 * @endcode
776 * See the @ref buffer documentation for information on writing multiple
777 * buffers in one go, and how to use it with arrays, boost::array or
778 * std::vector.
779 *
780 * @par Per-Operation Cancellation
781 * This asynchronous operation supports cancellation for the following
782 * boost::asio::cancellation_type values:
783 *
784 * @li @c cancellation_type::terminal
785 *
786 * @li @c cancellation_type::partial
787 *
788 * if they are also supported by the @c AsyncWriteStream type's
789 * @c async_write_some operation.
790 */
791template <typename AsyncWriteStream, typename ConstBufferSequence,
792 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
793 std::size_t)) WriteToken
794 = default_completion_token_t<typename AsyncWriteStream::executor_type>>
795auto async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers,
796 WriteToken&& token
797 = default_completion_token_t<typename AsyncWriteStream::executor_type>(),
798 constraint_t<
799 is_const_buffer_sequence<ConstBufferSequence>::value
800 > = 0)
801 -> decltype(
802 async_initiate<WriteToken,
803 void (boost::system::error_code, std::size_t)>(
804 declval<detail::initiate_async_write<AsyncWriteStream>>(),
805 token, buffers, transfer_all()));
806
807/// Start an asynchronous operation to write a certain amount of data to a
808/// stream.
809/**
810 * This function is used to asynchronously write a certain number of bytes of
811 * data to a stream. It is an initiating function for an @ref
812 * asynchronous_operation, and always returns immediately. The asynchronous
813 * operation will continue until one of the following conditions is true:
814 *
815 * @li All of the data in the supplied buffers has been written. That is, the
816 * bytes transferred is equal to the sum of the buffer sizes.
817 *
818 * @li The completion_condition function object returns 0.
819 *
820 * This operation is implemented in terms of zero or more calls to the stream's
821 * async_write_some function, and is known as a <em>composed operation</em>. The
822 * program must ensure that the stream performs no other write operations (such
823 * as async_write, the stream's async_write_some function, or any other composed
824 * operations that perform writes) until this operation completes.
825 *
826 * @param s The stream to which the data is to be written. The type must support
827 * the AsyncWriteStream concept.
828 *
829 * @param buffers One or more buffers containing the data to be written.
830 * Although the buffers object may be copied as necessary, ownership of the
831 * underlying memory blocks is retained by the caller, which must guarantee
832 * that they remain valid until the completion handler is called.
833 *
834 * @param completion_condition The function object to be called to determine
835 * whether the write operation is complete. The signature of the function object
836 * must be:
837 * @code std::size_t completion_condition(
838 * // Result of latest async_write_some operation.
839 * const boost::system::error_code& error,
840 *
841 * // Number of bytes transferred so far.
842 * std::size_t bytes_transferred
843 * ); @endcode
844 * A return value of 0 indicates that the write operation is complete. A
845 * non-zero return value indicates the maximum number of bytes to be written on
846 * the next call to the stream's async_write_some function.
847 *
848 * @param token The @ref completion_token that will be used to produce a
849 * completion handler, which will be called when the write completes.
850 * Potential completion tokens include @ref use_future, @ref use_awaitable,
851 * @ref yield_context, or a function object with the correct completion
852 * signature. The function signature of the completion handler must be:
853 * @code void handler(
854 * // Result of operation.
855 * const boost::system::error_code& error,
856 *
857 * // Number of bytes written from the buffers. If an error
858 * // occurred, this will be less than the sum of the buffer sizes.
859 * std::size_t bytes_transferred
860 * ); @endcode
861 * Regardless of whether the asynchronous operation completes immediately or
862 * not, the completion handler will not be invoked from within this function.
863 * On immediate completion, invocation of the handler will be performed in a
864 * manner equivalent to using boost::asio::post().
865 *
866 * @par Completion Signature
867 * @code void(boost::system::error_code, std::size_t) @endcode
868 *
869 * @par Example
870 * To write a single data buffer use the @ref buffer function as follows:
871 * @code boost::asio::async_write(s,
872 * boost::asio::buffer(data, size),
873 * boost::asio::transfer_at_least(32),
874 * handler); @endcode
875 * See the @ref buffer documentation for information on writing multiple
876 * buffers in one go, and how to use it with arrays, boost::array or
877 * std::vector.
878 *
879 * @par Per-Operation Cancellation
880 * This asynchronous operation supports cancellation for the following
881 * boost::asio::cancellation_type values:
882 *
883 * @li @c cancellation_type::terminal
884 *
885 * @li @c cancellation_type::partial
886 *
887 * if they are also supported by the @c AsyncWriteStream type's
888 * @c async_write_some operation.
889 */
890template <typename AsyncWriteStream,
891 typename ConstBufferSequence, typename CompletionCondition,
892 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
893 std::size_t)) WriteToken>
894auto async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers,
895 CompletionCondition completion_condition,
896 WriteToken&& token,
897 constraint_t<
898 is_const_buffer_sequence<ConstBufferSequence>::value
899 > = 0)
900 -> decltype(
901 async_initiate<WriteToken,
902 void (boost::system::error_code, std::size_t)>(
903 declval<detail::initiate_async_write<AsyncWriteStream>>(),
904 token, buffers,
905 static_cast<CompletionCondition&&>(completion_condition)));
906
907#if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
908
909/// Start an asynchronous operation to write all of the supplied data to a
910/// stream.
911/**
912 * This function is used to asynchronously write a certain number of bytes of
913 * data to a stream. It is an initiating function for an @ref
914 * asynchronous_operation, and always returns immediately. The asynchronous
915 * operation will continue until one of the following conditions is true:
916 *
917 * @li All of the data in the supplied dynamic buffer sequence has been written.
918 *
919 * @li An error occurred.
920 *
921 * This operation is implemented in terms of zero or more calls to the stream's
922 * async_write_some function, and is known as a <em>composed operation</em>. The
923 * program must ensure that the stream performs no other write operations (such
924 * as async_write, the stream's async_write_some function, or any other composed
925 * operations that perform writes) until this operation completes.
926 *
927 * @param s The stream to which the data is to be written. The type must support
928 * the AsyncWriteStream concept.
929 *
930 * @param buffers The dynamic buffer sequence from which data will be written.
931 * Although the buffers object may be copied as necessary, ownership of the
932 * underlying memory blocks is retained by the caller, which must guarantee
933 * that they remain valid until the completion handler is called. Successfully
934 * written data is automatically consumed from the buffers.
935 *
936 * @param token The @ref completion_token that will be used to produce a
937 * completion handler, which will be called when the write completes.
938 * Potential completion tokens include @ref use_future, @ref use_awaitable,
939 * @ref yield_context, or a function object with the correct completion
940 * signature. The function signature of the completion handler must be:
941 * @code void handler(
942 * // Result of operation.
943 * const boost::system::error_code& error,
944 *
945 * // Number of bytes written from the buffers. If an error
946 * // occurred, this will be less than the sum of the buffer sizes.
947 * std::size_t bytes_transferred
948 * ); @endcode
949 * Regardless of whether the asynchronous operation completes immediately or
950 * not, the completion handler will not be invoked from within this function.
951 * On immediate completion, invocation of the handler will be performed in a
952 * manner equivalent to using boost::asio::post().
953 *
954 * @par Completion Signature
955 * @code void(boost::system::error_code, std::size_t) @endcode
956 *
957 * @par Per-Operation Cancellation
958 * This asynchronous operation supports cancellation for the following
959 * boost::asio::cancellation_type values:
960 *
961 * @li @c cancellation_type::terminal
962 *
963 * @li @c cancellation_type::partial
964 *
965 * if they are also supported by the @c AsyncWriteStream type's
966 * @c async_write_some operation.
967 */
968template <typename AsyncWriteStream, typename DynamicBuffer_v1,
969 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
970 std::size_t)) WriteToken
971 = default_completion_token_t<typename AsyncWriteStream::executor_type>>
972auto async_write(AsyncWriteStream& s, DynamicBuffer_v1&& buffers,
973 WriteToken&& token
974 = default_completion_token_t<typename AsyncWriteStream::executor_type>(),
975 constraint_t<
976 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
977 > = 0,
978 constraint_t<
979 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
980 > = 0)
981 -> decltype(
982 async_initiate<WriteToken,
983 void (boost::system::error_code, std::size_t)>(
984 declval<detail::initiate_async_write_dynbuf_v1<AsyncWriteStream>>(),
985 token, static_cast<DynamicBuffer_v1&&>(buffers),
986 transfer_all()));
987
988/// Start an asynchronous operation to write a certain amount of data to a
989/// stream.
990/**
991 * This function is used to asynchronously write a certain number of bytes of
992 * data to a stream. It is an initiating function for an @ref
993 * asynchronous_operation, and always returns immediately. The asynchronous
994 * operation will continue until one of the following conditions is true:
995 *
996 * @li All of the data in the supplied dynamic buffer sequence has been written.
997 *
998 * @li The completion_condition function object returns 0.
999 *
1000 * This operation is implemented in terms of zero or more calls to the stream's
1001 * async_write_some function, and is known as a <em>composed operation</em>. The
1002 * program must ensure that the stream performs no other write operations (such
1003 * as async_write, the stream's async_write_some function, or any other composed
1004 * operations that perform writes) until this operation completes.
1005 *
1006 * @param s The stream to which the data is to be written. The type must support
1007 * the AsyncWriteStream concept.
1008 *
1009 * @param buffers The dynamic buffer sequence from which data will be written.
1010 * Although the buffers object may be copied as necessary, ownership of the
1011 * underlying memory blocks is retained by the caller, which must guarantee
1012 * that they remain valid until the completion handler is called. Successfully
1013 * written data is automatically consumed from the buffers.
1014 *
1015 * @param completion_condition The function object to be called to determine
1016 * whether the write operation is complete. The signature of the function object
1017 * must be:
1018 * @code std::size_t completion_condition(
1019 * // Result of latest async_write_some operation.
1020 * const boost::system::error_code& error,
1021 *
1022 * // Number of bytes transferred so far.
1023 * std::size_t bytes_transferred
1024 * ); @endcode
1025 * A return value of 0 indicates that the write operation is complete. A
1026 * non-zero return value indicates the maximum number of bytes to be written on
1027 * the next call to the stream's async_write_some function.
1028 *
1029 * @param token The @ref completion_token that will be used to produce a
1030 * completion handler, which will be called when the write completes.
1031 * Potential completion tokens include @ref use_future, @ref use_awaitable,
1032 * @ref yield_context, or a function object with the correct completion
1033 * signature. The function signature of the completion handler must be:
1034 * @code void handler(
1035 * // Result of operation.
1036 * const boost::system::error_code& error,
1037 *
1038 * // Number of bytes written from the buffers. If an error
1039 * // occurred, this will be less than the sum of the buffer sizes.
1040 * std::size_t bytes_transferred
1041 * ); @endcode
1042 * Regardless of whether the asynchronous operation completes immediately or
1043 * not, the completion handler will not be invoked from within this function.
1044 * On immediate completion, invocation of the handler will be performed in a
1045 * manner equivalent to using boost::asio::post().
1046 *
1047 * @par Completion Signature
1048 * @code void(boost::system::error_code, std::size_t) @endcode
1049 *
1050 * @par Per-Operation Cancellation
1051 * This asynchronous operation supports cancellation for the following
1052 * boost::asio::cancellation_type values:
1053 *
1054 * @li @c cancellation_type::terminal
1055 *
1056 * @li @c cancellation_type::partial
1057 *
1058 * if they are also supported by the @c AsyncWriteStream type's
1059 * @c async_write_some operation.
1060 */
1061template <typename AsyncWriteStream,
1062 typename DynamicBuffer_v1, typename CompletionCondition,
1063 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1064 std::size_t)) WriteToken>
1065auto async_write(AsyncWriteStream& s, DynamicBuffer_v1&& buffers,
1066 CompletionCondition completion_condition, WriteToken&& token,
1067 constraint_t<
1068 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
1069 > = 0,
1070 constraint_t<
1071 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
1072 > = 0)
1073 -> decltype(
1074 async_initiate<WriteToken,
1075 void (boost::system::error_code, std::size_t)>(
1076 declval<detail::initiate_async_write_dynbuf_v1<AsyncWriteStream>>(),
1077 token, static_cast<DynamicBuffer_v1&&>(buffers),
1078 static_cast<CompletionCondition&&>(completion_condition)));
1079
1080#if !defined(BOOST_ASIO_NO_EXTENSIONS)
1081#if !defined(BOOST_ASIO_NO_IOSTREAM)
1082
1083/// Start an asynchronous operation to write all of the supplied data to a
1084/// stream.
1085/**
1086 * This function is used to asynchronously write a certain number of bytes of
1087 * data to a stream. It is an initiating function for an @ref
1088 * asynchronous_operation, and always returns immediately. The asynchronous
1089 * operation will continue until one of the following conditions is true:
1090 *
1091 * @li All of the data in the supplied basic_streambuf has been written.
1092 *
1093 * @li An error occurred.
1094 *
1095 * This operation is implemented in terms of zero or more calls to the stream's
1096 * async_write_some function, and is known as a <em>composed operation</em>. The
1097 * program must ensure that the stream performs no other write operations (such
1098 * as async_write, the stream's async_write_some function, or any other composed
1099 * operations that perform writes) until this operation completes.
1100 *
1101 * @param s The stream to which the data is to be written. The type must support
1102 * the AsyncWriteStream concept.
1103 *
1104 * @param b A basic_streambuf object from which data will be written. Ownership
1105 * of the streambuf is retained by the caller, which must guarantee that it
1106 * remains valid until the completion handler is called.
1107 *
1108 * @param token The @ref completion_token that will be used to produce a
1109 * completion handler, which will be called when the write completes.
1110 * Potential completion tokens include @ref use_future, @ref use_awaitable,
1111 * @ref yield_context, or a function object with the correct completion
1112 * signature. The function signature of the completion handler must be:
1113 * @code void handler(
1114 * // Result of operation.
1115 * const boost::system::error_code& error,
1116 *
1117 * // Number of bytes written from the buffers. If an error
1118 * // occurred, this will be less than the sum of the buffer sizes.
1119 * std::size_t bytes_transferred
1120 * ); @endcode
1121 * Regardless of whether the asynchronous operation completes immediately or
1122 * not, the completion handler will not be invoked from within this function.
1123 * On immediate completion, invocation of the handler will be performed in a
1124 * manner equivalent to using boost::asio::post().
1125 *
1126 * @par Completion Signature
1127 * @code void(boost::system::error_code, std::size_t) @endcode
1128 *
1129 * @par Per-Operation Cancellation
1130 * This asynchronous operation supports cancellation for the following
1131 * boost::asio::cancellation_type values:
1132 *
1133 * @li @c cancellation_type::terminal
1134 *
1135 * @li @c cancellation_type::partial
1136 *
1137 * if they are also supported by the @c AsyncWriteStream type's
1138 * @c async_write_some operation.
1139 */
1140template <typename AsyncWriteStream, typename Allocator,
1141 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1142 std::size_t)) WriteToken
1143 = default_completion_token_t<typename AsyncWriteStream::executor_type>>
1144auto async_write(AsyncWriteStream& s, basic_streambuf<Allocator>& b,
1145 WriteToken&& token
1146 = default_completion_token_t<typename AsyncWriteStream::executor_type>())
1147 -> decltype(
1148 async_initiate<WriteToken,
1149 void (boost::system::error_code, std::size_t)>(
1150 declval<detail::initiate_async_write_dynbuf_v1<AsyncWriteStream>>(),
1151 token, basic_streambuf_ref<Allocator>(b), transfer_all()));
1152
1153/// Start an asynchronous operation to write a certain amount of data to a
1154/// stream.
1155/**
1156 * This function is used to asynchronously write a certain number of bytes of
1157 * data to a stream. It is an initiating function for an @ref
1158 * asynchronous_operation, and always returns immediately. The asynchronous
1159 * operation will continue until one of the following conditions is true:
1160 *
1161 * @li All of the data in the supplied basic_streambuf has been written.
1162 *
1163 * @li The completion_condition function object returns 0.
1164 *
1165 * This operation is implemented in terms of zero or more calls to the stream's
1166 * async_write_some function, and is known as a <em>composed operation</em>. The
1167 * program must ensure that the stream performs no other write operations (such
1168 * as async_write, the stream's async_write_some function, or any other composed
1169 * operations that perform writes) until this operation completes.
1170 *
1171 * @param s The stream to which the data is to be written. The type must support
1172 * the AsyncWriteStream concept.
1173 *
1174 * @param b A basic_streambuf object from which data will be written. Ownership
1175 * of the streambuf is retained by the caller, which must guarantee that it
1176 * remains valid until the completion handler is called.
1177 *
1178 * @param completion_condition The function object to be called to determine
1179 * whether the write operation is complete. The signature of the function object
1180 * must be:
1181 * @code std::size_t completion_condition(
1182 * // Result of latest async_write_some operation.
1183 * const boost::system::error_code& error,
1184 *
1185 * // Number of bytes transferred so far.
1186 * std::size_t bytes_transferred
1187 * ); @endcode
1188 * A return value of 0 indicates that the write operation is complete. A
1189 * non-zero return value indicates the maximum number of bytes to be written on
1190 * the next call to the stream's async_write_some function.
1191 *
1192 * @param token The @ref completion_token that will be used to produce a
1193 * completion handler, which will be called when the write completes.
1194 * Potential completion tokens include @ref use_future, @ref use_awaitable,
1195 * @ref yield_context, or a function object with the correct completion
1196 * signature. The function signature of the completion handler must be:
1197 * @code void handler(
1198 * // Result of operation.
1199 * const boost::system::error_code& error,
1200 *
1201 * // Number of bytes written from the buffers. If an error
1202 * // occurred, this will be less than the sum of the buffer sizes.
1203 * std::size_t bytes_transferred
1204 * ); @endcode
1205 * Regardless of whether the asynchronous operation completes immediately or
1206 * not, the completion handler will not be invoked from within this function.
1207 * On immediate completion, invocation of the handler will be performed in a
1208 * manner equivalent to using boost::asio::post().
1209 *
1210 * @par Completion Signature
1211 * @code void(boost::system::error_code, std::size_t) @endcode
1212 *
1213 * @par Per-Operation Cancellation
1214 * This asynchronous operation supports cancellation for the following
1215 * boost::asio::cancellation_type values:
1216 *
1217 * @li @c cancellation_type::terminal
1218 *
1219 * @li @c cancellation_type::partial
1220 *
1221 * if they are also supported by the @c AsyncWriteStream type's
1222 * @c async_write_some operation.
1223 */
1224template <typename AsyncWriteStream,
1225 typename Allocator, typename CompletionCondition,
1226 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1227 std::size_t)) WriteToken>
1228auto async_write(AsyncWriteStream& s, basic_streambuf<Allocator>& b,
1229 CompletionCondition completion_condition, WriteToken&& token)
1230 -> decltype(
1231 async_initiate<WriteToken,
1232 void (boost::system::error_code, std::size_t)>(
1233 declval<detail::initiate_async_write_dynbuf_v1<AsyncWriteStream>>(),
1234 token, basic_streambuf_ref<Allocator>(b),
1235 static_cast<CompletionCondition&&>(completion_condition)));
1236
1237#endif // !defined(BOOST_ASIO_NO_IOSTREAM)
1238#endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
1239#endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
1240
1241/// Start an asynchronous operation to write all of the supplied data to a
1242/// stream.
1243/**
1244 * This function is used to asynchronously write a certain number of bytes of
1245 * data to a stream. It is an initiating function for an @ref
1246 * asynchronous_operation, and always returns immediately. The asynchronous
1247 * operation will continue until one of the following conditions is true:
1248 *
1249 * @li All of the data in the supplied dynamic buffer sequence has been written.
1250 *
1251 * @li An error occurred.
1252 *
1253 * This operation is implemented in terms of zero or more calls to the stream's
1254 * async_write_some function, and is known as a <em>composed operation</em>. The
1255 * program must ensure that the stream performs no other write operations (such
1256 * as async_write, the stream's async_write_some function, or any other composed
1257 * operations that perform writes) until this operation completes.
1258 *
1259 * @param s The stream to which the data is to be written. The type must support
1260 * the AsyncWriteStream concept.
1261 *
1262 * @param buffers The dynamic buffer sequence from which data will be written.
1263 * Although the buffers object may be copied as necessary, ownership of the
1264 * underlying memory blocks is retained by the caller, which must guarantee
1265 * that they remain valid until the completion handler is called. Successfully
1266 * written data is automatically consumed from the buffers.
1267 *
1268 * @param token The @ref completion_token that will be used to produce a
1269 * completion handler, which will be called when the write completes.
1270 * Potential completion tokens include @ref use_future, @ref use_awaitable,
1271 * @ref yield_context, or a function object with the correct completion
1272 * signature. The function signature of the completion handler must be:
1273 * @code void handler(
1274 * // Result of operation.
1275 * const boost::system::error_code& error,
1276 *
1277 * // Number of bytes written from the buffers. If an error
1278 * // occurred, this will be less than the sum of the buffer sizes.
1279 * std::size_t bytes_transferred
1280 * ); @endcode
1281 * Regardless of whether the asynchronous operation completes immediately or
1282 * not, the completion handler will not be invoked from within this function.
1283 * On immediate completion, invocation of the handler will be performed in a
1284 * manner equivalent to using boost::asio::post().
1285 *
1286 * @par Completion Signature
1287 * @code void(boost::system::error_code, std::size_t) @endcode
1288 *
1289 * @par Per-Operation Cancellation
1290 * This asynchronous operation supports cancellation for the following
1291 * boost::asio::cancellation_type values:
1292 *
1293 * @li @c cancellation_type::terminal
1294 *
1295 * @li @c cancellation_type::partial
1296 *
1297 * if they are also supported by the @c AsyncWriteStream type's
1298 * @c async_write_some operation.
1299 */
1300template <typename AsyncWriteStream, typename DynamicBuffer_v2,
1301 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1302 std::size_t)) WriteToken
1303 = default_completion_token_t<typename AsyncWriteStream::executor_type>>
1304auto async_write(AsyncWriteStream& s, DynamicBuffer_v2 buffers,
1305 WriteToken&& token
1306 = default_completion_token_t<typename AsyncWriteStream::executor_type>(),
1307 constraint_t<
1308 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1309 > = 0)
1310 -> decltype(
1311 async_initiate<WriteToken,
1312 void (boost::system::error_code, std::size_t)>(
1313 declval<detail::initiate_async_write_dynbuf_v2<AsyncWriteStream>>(),
1314 token, static_cast<DynamicBuffer_v2&&>(buffers),
1315 transfer_all()));
1316
1317/// Start an asynchronous operation to write a certain amount of data to a
1318/// stream.
1319/**
1320 * This function is used to asynchronously write a certain number of bytes of
1321 * data to a stream. It is an initiating function for an @ref
1322 * asynchronous_operation, and always returns immediately. The asynchronous
1323 * operation will continue until one of the following conditions is true:
1324 *
1325 * @li All of the data in the supplied dynamic buffer sequence has been written.
1326 *
1327 * @li The completion_condition function object returns 0.
1328 *
1329 * This operation is implemented in terms of zero or more calls to the stream's
1330 * async_write_some function, and is known as a <em>composed operation</em>. The
1331 * program must ensure that the stream performs no other write operations (such
1332 * as async_write, the stream's async_write_some function, or any other composed
1333 * operations that perform writes) until this operation completes.
1334 *
1335 * @param s The stream to which the data is to be written. The type must support
1336 * the AsyncWriteStream concept.
1337 *
1338 * @param buffers The dynamic buffer sequence from which data will be written.
1339 * Although the buffers object may be copied as necessary, ownership of the
1340 * underlying memory blocks is retained by the caller, which must guarantee
1341 * that they remain valid until the completion handler is called. Successfully
1342 * written data is automatically consumed from the buffers.
1343 *
1344 * @param completion_condition The function object to be called to determine
1345 * whether the write operation is complete. The signature of the function object
1346 * must be:
1347 * @code std::size_t completion_condition(
1348 * // Result of latest async_write_some operation.
1349 * const boost::system::error_code& error,
1350 *
1351 * // Number of bytes transferred so far.
1352 * std::size_t bytes_transferred
1353 * ); @endcode
1354 * A return value of 0 indicates that the write operation is complete. A
1355 * non-zero return value indicates the maximum number of bytes to be written on
1356 * the next call to the stream's async_write_some function.
1357 *
1358 * @param token The @ref completion_token that will be used to produce a
1359 * completion handler, which will be called when the write completes.
1360 * Potential completion tokens include @ref use_future, @ref use_awaitable,
1361 * @ref yield_context, or a function object with the correct completion
1362 * signature. The function signature of the completion handler must be:
1363 * @code void handler(
1364 * // Result of operation.
1365 * const boost::system::error_code& error,
1366 *
1367 * // Number of bytes written from the buffers. If an error
1368 * // occurred, this will be less than the sum of the buffer sizes.
1369 * std::size_t bytes_transferred
1370 * ); @endcode
1371 * Regardless of whether the asynchronous operation completes immediately or
1372 * not, the completion handler will not be invoked from within this function.
1373 * On immediate completion, invocation of the handler will be performed in a
1374 * manner equivalent to using boost::asio::post().
1375 *
1376 * @par Completion Signature
1377 * @code void(boost::system::error_code, std::size_t) @endcode
1378 *
1379 * @par Per-Operation Cancellation
1380 * This asynchronous operation supports cancellation for the following
1381 * boost::asio::cancellation_type values:
1382 *
1383 * @li @c cancellation_type::terminal
1384 *
1385 * @li @c cancellation_type::partial
1386 *
1387 * if they are also supported by the @c AsyncWriteStream type's
1388 * @c async_write_some operation.
1389 */
1390template <typename AsyncWriteStream,
1391 typename DynamicBuffer_v2, typename CompletionCondition,
1392 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1393 std::size_t)) WriteToken>
1394auto async_write(AsyncWriteStream& s, DynamicBuffer_v2 buffers,
1395 CompletionCondition completion_condition,
1396 WriteToken&& token,
1397 constraint_t<
1398 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1399 > = 0)
1400 -> decltype(
1401 async_initiate<WriteToken,
1402 void (boost::system::error_code, std::size_t)>(
1403 declval<detail::initiate_async_write_dynbuf_v2<AsyncWriteStream>>(),
1404 token, static_cast<DynamicBuffer_v2&&>(buffers),
1405 static_cast<CompletionCondition&&>(completion_condition)));
1406
1407/*@}*/
1408
1409} // namespace asio
1410} // namespace boost
1411
1412#include <boost/asio/detail/pop_options.hpp>
1413
1414#include <boost/asio/impl/write.hpp>
1415
1416#endif // BOOST_ASIO_WRITE_HPP
1417

source code of boost/libs/asio/include/boost/asio/write.hpp