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:AsyncRandomAccessWriteDevice Buffer-oriented asynchronous
9random-access write device requirements]
10
11In the table below, `a` denotes an asynchronous write stream object, `o`
12denotes an offset of type `boost::uint64_t`, `cb` denotes an object satisfying
13[link boost_asio.reference.ConstBufferSequence constant buffer sequence]
14requirements, and `h` denotes an object satisfying [link
15boost_asio.reference.WriteHandler write handler] requirements.
16
17[table Buffer-oriented asynchronous random-access write device requirements
18  [[operation] [type] [semantics, pre/post-conditions]]
19  [
20    [`a.get_executor()`]
21    [A type satisfying the [link boost_asio.reference.Executor1 Executor requirements].]
22    [Returns the associated I/O executor.]
23  ]
24  [
25    [`a.async_write_some_at(o, cb, h);`]
26    [`void`]
27    [
28      Initiates an asynchronous operation to write one or more bytes of data to
29      the device `a` at offset `o`. The operation is performed via the
30      `io_service` object `a.get_io_service()` and behaves according to [link
31      boost_asio.reference.asynchronous_operations asynchronous operation]
32      requirements.[br]
33      [br]
34      The constant buffer sequence `cb` specifies memory where the data to be
35      written is located. The `async_write_some_at` operation shall always
36      write a buffer in the sequence completely before proceeding to the
37      next.[br]
38      [br]
39      The implementation shall maintain one or more copies of `cb` until such
40      time as the write operation no longer requires access to the memory
41      specified by the buffers in the sequence. The program must ensure the
42      memory is valid until:[br]
43      [br]
44      [mdash] the last copy of `cb` is destroyed, or[br]
45      [br]
46      [mdash] the handler for the asynchronous write operation is invoked,[br]
47      [br]
48      whichever comes first.[br]
49      [br]
50      If the total size of all buffers in the sequence `cb` is `0`, the
51      asynchronous write operation shall complete immediately and pass `0` as
52      the argument to the handler that specifies the number of bytes written.
53    ]
54  ]
55]
56
57[endsect]
58