Random access handle service requirements

| Home | Libraries | People | FAQ | More

### Random access handle service requirements

A random access handle service must meet the requirements for a handle service, as well as the additional requirements listed below.

In the table below, `X` denotes a random access handle service class, `a` denotes a value of type `X`, `b` denotes a value of type `X::implementation_type`, `ec` denotes a value of type `error_code`, `o` denotes an offset of type boost::uint64_t, `mb` denotes a value satisfying mutable buffer sequence requirements, `rh` denotes a value meeting `ReadHandler` requirements, `cb` denotes a value satisfying constant buffer sequence requirements, and `wh` denotes a value meeting `WriteHandler` requirements.

Table 20. RandomAccessHandleService requirements

expression | return type | assertion/note pre/post-condition
--- | --- | ---

`a.read_some_at(b, o, mb, ec);`

`size_t`

pre: `a.is_open(b)`.
Reads one or more bytes of data from a handle `b` at offset `o`.
The mutable buffer sequence `mb` specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.
If successful, returns the number of bytes read. Otherwise returns `0`. If the total size of all buffers in the sequence `mb` is `0`, the function shall return `0` immediately.

`a.async_read_some_at(b, o, mb, rh);`

`void`

pre: `a.is_open(b)`.
Initiates an asynchronous operation to read one or more bytes of data from a handle `b` at offset `o`. The operation is performed via the `io_service` object `a.get_io_service()` and behaves according to asynchronous operation requirements.
The mutable buffer sequence `mb` specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.
The implementation shall maintain one or more copies of `mb` until such time as the read operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:
— the last copy of `mb` is destroyed, or
— the handler for the asynchronous operation is invoked,
whichever comes first. If the total size of all buffers in the sequence `mb` is `0`, the asynchronous read operation shall complete immediately and pass `0` as the argument to the handler that specifies the number of bytes read.
If the operation completes successfully, the `ReadHandler` object `rh` is invoked with the number of bytes transferred. Otherwise it is invoked with `0`.

`a.write_some_at(b, o, cb, ec);`

`size_t`

pre: `a.is_open(b)`.
Writes one or more bytes of data to a handle `b` at offset `o`.
The constant buffer sequence `cb` specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.
If successful, returns the number of bytes written. Otherwise returns `0`. If the total size of all buffers in the sequence `cb` is `0`, the function shall return `0` immediately.

`a.async_write_some_at(b, o, cb, wh);`

`void`

pre: `a.is_open(b)`.
Initiates an asynchronous operation to write one or more bytes of data to a handle `b` at offset `o`. The operation is performed via the `io_service` object `a.get_io_service()` and behaves according to asynchronous operation requirements.
The constant buffer sequence `cb` specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.
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:
— the last copy of `cb` is destroyed, or
— the handler for the asynchronous operation is invoked,
whichever comes first. If the total size of all buffers in the sequence `cb` is `0`, the asynchronous operation shall complete immediately and pass `0` as the argument to the handler that specifies the number of bytes read.
If the operation completes successfully, the `WriteHandler` object `wh` is invoked with the number of bytes transferred. Otherwise it is invoked with `0`.