summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/asio/src/doc/requirements/AsyncRandomAccessWriteDevice.qbk
blob: bd9ecbd834bacc745abe5cd6ac83b7359dfb6e5e (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
[/
 / 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:AsyncRandomAccessWriteDevice Buffer-oriented asynchronous
random-access write device requirements]

In the table below, `a` denotes an asynchronous write stream object, `o`
denotes an offset of type `boost::uint64_t`, `cb` denotes an object satisfying
[link asio.reference.ConstBufferSequence constant buffer sequence]
requirements, and `h` denotes an object satisfying [link
asio.reference.WriteHandler write handler] requirements.

[table Buffer-oriented asynchronous random-access write device requirements
  [[operation] [type] [semantics, pre/post-conditions]]
  [
    [`a.get_executor()`]
    [A type satisfying the [link asio.reference.Executor1 Executor requirements].]
    [Returns the associated I/O executor.]
  ]
  [
    [`a.async_write_some_at(o, cb, h);`]
    [`void`]
    [
      Initiates an asynchronous operation to write one or more bytes of data to
      the device `a` at offset `o`. The operation is performed via the
      `io_service` object `a.get_io_service()` and behaves according to [link
      asio.reference.asynchronous_operations asynchronous operation]
      requirements.\n
      \n
      The constant buffer sequence `cb` specifies memory where the data to be
      written is located. The `async_write_some_at` operation shall always
      write a buffer in the sequence completely before proceeding to the
      next.\n
      \n
      The implementation shall maintain one or more copies of `cb` until such
      time as the write operation no longer requires access to the memory
      specified by the buffers in the sequence. The program must ensure the
      memory is valid until:\n
      \n
      [mdash] the last copy of `cb` is destroyed, or\n
      \n
      [mdash] the handler for the asynchronous write operation is invoked,\n
      \n
      whichever comes first.\n
      \n
      If the total size of all buffers in the sequence `cb` is `0`, the
      asynchronous write operation shall complete immediately and pass `0` as
      the argument to the handler that specifies the number of bytes written.
    ]
  ]
]

[endsect]