Reference - 1.63.0

Requirements on asynchronous operations

In Boost.Asio, an asynchronous operation is initiated by a function that is named with the prefix async_. These functions will be referred to as initiating functions.

All initiating functions in Boost.Asio take a function object meeting handler requirements as the final parameter. These handlers accept as their first parameter an lvalue of type const error_code.

Implementations of asynchronous operations in Boost.Asio may call the application programming interface (API) provided by the operating system. If such an operating system API call results in an error, the handler will be invoked with a const error_code lvalue that evaluates to true. Otherwise the handler will be invoked with a const error_code lvalue that evaluates to false.

Unless otherwise noted, when the behaviour of an asynchronous operation is defined "as if" implemented by a POSIX function, the handler will be invoked with a value of type error_code that corresponds to the failure condition described by POSIX for that function, if any. Otherwise the handler will be invoked with an implementation-defined error_code value that reflects the operating system error.

Asynchronous operations will not fail with an error condition that indicates interruption by a signal (POSIX EINTR). Asynchronous operations will not fail with any error condition associated with non-blocking operations (POSIX EWOULDBLOCK, EAGAIN or EINPROGRESS; Windows WSAEWOULDBLOCK or WSAEINPROGRESS).

All asynchronous operations have an associated io_service object. Where the initiating function is a member function, the associated io_service is that returned by the get_io_service() member function on the same object. Where the initiating function is not a member function, the associated io_service is that returned by the get_io_service() member function of the first argument to the initiating function.

Arguments to initiating functions will be treated as follows:

— If the parameter is declared as a const reference or by-value, the program is not required to guarantee the validity of the argument after the initiating function completes. The implementation may make copies of the argument, and all copies will be destroyed no later than immediately after invocation of the handler.

— If the parameter is declared as a non-const reference, const pointer or non-const pointer, the program must guarantee the validity of the argument until the handler is invoked.

The library implementation is only permitted to make calls to an initiating function's arguments' copy constructors or destructors from a thread that satisfies one of the following conditions:

— The thread is executing any member function of the associated io_service object.

— The thread is executing the destructor of the associated io_service object.

— The thread is executing one of the io_service service access functions use_service, add_service or has_service, where the first argument is the associated io_service object.

— The thread is executing any member function, constructor or destructor of an object of a class defined in this clause, where the object's get_io_service() member function returns the associated io_service object.

— The thread is executing any function defined in this clause, where any argument to the function has an get_io_service() member function that returns the associated io_service object.

The io_service object associated with an asynchronous operation will have unfinished work, as if by maintaining the existence of one or more objects of class io_service::work constructed using the io_service, until immediately after the handler for the asynchronous operation has been invoked.

When an asynchronous operation is complete, the handler for the operation will be invoked as if by:

Constructing a bound completion handler bch for the handler, as described below.
Calling ios.post(bch) to schedule the handler for deferred invocation, where ios is the associated io_service.

This implies that the handler must not be called directly from within the initiating function, even if the asynchronous operation completes immediately.

A bound completion handler is a handler object that contains a copy of a user-supplied handler, where the user-supplied handler accepts one or more arguments. The bound completion handler does not accept any arguments, and contains values to be passed as arguments to the user-supplied handler. The bound completion handler forwards the asio_handler_allocate(), asio_handler_deallocate(), and asio_handler_invoke() calls to the corresponding functions for the user-supplied handler. A bound completion handler meets the requirements for a completion handler.

For example, a bound completion handler for a ReadHandler may be implemented as follows:

template<class ReadHandler>
struct bound_read_handler
{
  bound_read_handler(ReadHandler handler, const error_code& ec, size_t s)
    : handler_(handler), ec_(ec), s_(s)
  {
  }

  void operator()()
  {
    handler_(ec_, s_);
  }

  ReadHandler handler_;
  const error_code ec_;
  const size_t s_;
};

template<class ReadHandler>
void* asio_handler_allocate(size_t size,
                            bound_read_handler<ReadHandler>* this_handler)
{
  using boost::asio::asio_handler_allocate;
  return asio_handler_allocate(size, &this_handler->handler_);
}

template<class ReadHandler>
void asio_handler_deallocate(void* pointer, std::size_t size,
                             bound_read_handler<ReadHandler>* this_handler)
{
  using boost::asio::asio_handler_deallocate;
  asio_handler_deallocate(pointer, size, &this_handler->handler_);
}

template<class F, class ReadHandler>
void asio_handler_invoke(const F& f,
                         bound_read_handler<ReadHandler>* this_handler)
{
  using boost::asio::asio_handler_invoke;
  asio_handler_invoke(f, &this_handler->handler_);
}

If the thread that initiates an asynchronous operation terminates before the associated handler is invoked, the behaviour is implementation-defined. Specifically, on Windows versions prior to Vista, unfinished operations are cancelled when the initiating thread exits.

The handler argument to an initiating function defines a handler identity. That is, the original handler argument and any copies of the handler argument will be considered equivalent. If the implementation needs to allocate storage for an asynchronous operation, the implementation will perform asio_handler_allocate(size, &h), where size is the required size in bytes, and h is the handler. The implementation will perform asio_handler_deallocate(p, size, &h), where p is a pointer to the storage, to deallocate the storage prior to the invocation of the handler via asio_handler_invoke. Multiple storage blocks may be allocated for a single asynchronous operation.

Return type of an initiating function

By default, initiating functions return void. This is always the case when the handler is a function pointer, C++11 lambda, or a function object produced by boost::bind or std::bind.

For other types, the return type may be customised via a two-step process:

A specialisation of the handler_type template, which is used to determine the true handler type based on the asynchronous operation's handler's signature.
A specialisation of the async_result template, which is used both to determine the return type and to extract the return value from the handler.

These two templates have been specialised to provide support for stackful coroutines and the C++11 std::future class.

As an example, consider what happens when enabling std::future support by using the boost::asio::use_future special value, as in:

std::future<std::size_t> length =
  my_socket.async_read_some(my_buffer, boost::asio::use_future);

When a handler signature has the form:

void handler(error_code ec, result_type result);

the initiating function returns a std::future templated on result_type. In the above async_read_some example, this is std::size_t. If the asynchronous operation fails, the error_code is converted into a system_error exception and passed back to the caller through the future.

Where a handler signature has the form:

void handler(error_code ec);

the initiating function instead returns std::future<void>.

Accept handler requirements

An accept handler must meet the requirements for a handler. A value h of an accept handler class should work correctly in the expression h(ec), where ec is an lvalue of type const error_code.

Examples

A free function as an accept handler:

void accept_handler(
    const boost::system::error_code& ec)
{
  ...
}

An accept handler function object:

struct accept_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec)
  {
    ...
  }
  ...
};

A non-static class member function adapted to an accept handler using bind():

void my_class::accept_handler(
    const boost::system::error_code& ec)
{
  ...
}
...
acceptor.async_accept(...,
    boost::bind(&my_class::accept_handler,
      this, boost::asio::placeholders::error));

Buffer-oriented asynchronous random-access read device requirements

In the table below, a denotes an asynchronous random access read device object, o denotes an offset of type boost::uint64_t, mb denotes an object satisfying mutable buffer sequence requirements, and h denotes an object satisfying read handler requirements.

Table 7.1. Buffer-oriented asynchronous random-access read device requirements

operation	type	semantics, pre/post-conditions
`a.get_io_service();`	`io_service&`	Returns the `io_service` object through which the `async_read_some_at` handler `h` will be invoked.
`a.async_read_some_at(o, mb, h);`	`void`	Initiates an asynchronous operation to read one or more bytes of data from the device `a` at the 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 `async_read_some_at` 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 read 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.

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 constant buffer sequence requirements, and h denotes an object satisfying write handler requirements.

Table 7.2. Buffer-oriented asynchronous random-access write device requirements

operation	type	semantics, pre/post-conditions
`a.get_io_service();`	`io_service&`	Returns the `io_service` object through which the `async_write_some_at` handler `h` will be invoked.
`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 asynchronous operation requirements. 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. 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 write operation is invoked, whichever comes first. 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.

Buffer-oriented asynchronous read stream requirements

In the table below, a denotes an asynchronous read stream object, mb denotes an object satisfying mutable buffer sequence requirements, and h denotes an object satisfying read handler requirements.

Table 7.3. Buffer-oriented asynchronous read stream requirements

operation	type	semantics, pre/post-conditions
`a.get_io_service();`	`io_service&`	Returns the `io_service` object through which the `async_read_some` handler `h` will be invoked.
`a.async_read_some(mb, h);`	`void`	Initiates an asynchronous operation to read one or more bytes of data from the stream `a`. 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 `async_read_some` 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 read 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.

Buffer-oriented asynchronous write stream requirements

In the table below, a denotes an asynchronous write stream object, cb denotes an object satisfying constant buffer sequence requirements, and h denotes an object satisfying write handler requirements.

Table 7.4. Buffer-oriented asynchronous write stream requirements

operation	type	semantics, pre/post-conditions
`a.get_io_service();`	`io_service&`	Returns the `io_service` object through which the `async_write_some` handler `h` will be invoked.
`a.async_write_some(cb, h);`	`void`	Initiates an asynchronous operation to write one or more bytes of data to the stream `a`. 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 `async_write_some` 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 write operation is invoked, whichever comes first. 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.

Buffered handshake handler requirements

A buffered handshake handler must meet the requirements for a handler. A value h of a buffered handshake handler class should work correctly in the expression h(ec, s), where ec is an lvalue of type const error_code and s is an lvalue of type const size_t.

Examples

A free function as a buffered handshake handler:

void handshake_handler(
    const boost::system::error_code& ec,
    std::size_t bytes_transferred)
{
  ...
}

A buffered handshake handler function object:

struct handshake_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec,
      std::size_t bytes_transferred)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a buffered handshake handler using bind():

void my_class::handshake_handler(
    const boost::system::error_code& ec,
    std::size_t bytes_transferred)
{
  ...
}
...
socket.async_handshake(...,
    boost::bind(&my_class::handshake_handler,
      this, boost::asio::placeholders::error,
      boost::asio::placeholders::bytes_transferred));

Completion handler requirements

A completion handler must meet the requirements for a handler. A value h of a completion handler class should work correctly in the expression h().

Examples

A free function as a completion handler:

void completion_handler()
{
  ...
}

A completion handler function object:

struct completion_handler
{
  ...
  void operator()()
  {
    ...
  }
  ...
};

A non-static class member function adapted to a completion handler using bind():

void my_class::completion_handler()
{
  ...
}
...
my_io_service.post(boost::bind(&my_class::completion_handler, this));

Composed connect handler requirements

A composed connect handler must meet the requirements for a handler. A value h of a composed connect handler class should work correctly in the expression h(ec, i), where ec is an lvalue of type const error_code and i is an lvalue of the type Iterator used in the corresponding connect() or async_connect()` function.

Examples

A free function as a composed connect handler:

void connect_handler(
    const boost::system::error_code& ec,
    boost::asio::ip::tcp::resolver::iterator iterator)
{
  ...
}

A composed connect handler function object:

struct connect_handler
{
  ...
  template <typename Iterator>
  void operator()(
      const boost::system::error_code& ec,
      Iterator iterator)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a composed connect handler using bind():

void my_class::connect_handler(
    const boost::system::error_code& ec,
    boost::asio::ip::tcp::resolver::iterator iterator)
{
  ...
}
...
boost::asio::async_connect(...,
    boost::bind(&my_class::connect_handler,
      this, boost::asio::placeholders::error,
      boost::asio::placeholders::iterator));

Connect handler requirements

A connect handler must meet the requirements for a handler. A value h of a connect handler class should work correctly in the expression h(ec), where ec is an lvalue of type const error_code.

Examples

A free function as a connect handler:

void connect_handler(
    const boost::system::error_code& ec)
{
  ...
}

A connect handler function object:

struct connect_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a connect handler using bind():

void my_class::connect_handler(
    const boost::system::error_code& ec)
{
  ...
}
...
socket.async_connect(...,
    boost::bind(&my_class::connect_handler,
      this, boost::asio::placeholders::error));

Constant buffer sequence requirements

In the table below, X denotes a class containing objects of type T, a denotes a value of type X and u denotes an identifier.

Table 7.5. ConstBufferSequence requirements

expression	return type	assertion/note pre/post-condition
`X::value_type`	`T`	`T` meets the requirements for ConvertibleToConstBuffer.
`X::const_iterator`	iterator type pointing to `T`	`const_iterator` meets the requirements for bidirectional iterators (C++ Std, 24.1.4).
`X(a);`		post: `equal_const_buffer_seq(a, X(a))` where the binary predicate `equal_const_buffer_seq` is defined as bool equal_const_buffer_seq( const X& x1, const X& x2) { return distance(x1.begin(), x1.end()) == distance(x2.begin(), x2.end()) && equal(x1.begin(), x1.end(), x2.begin(), equal_buffer); } and the binary predicate `equal_buffer` is defined as bool equal_buffer( const X::value_type& v1, const X::value_type& v2) { const_buffer b1(v1); const_buffer b2(v2); return buffer_cast<const void>(b1) == buffer_cast<const void>(b2) && buffer_size(b1) == buffer_size(b2); }
`X u(a);`		post: distance(a.begin(), a.end()) == distance(u.begin(), u.end()) && equal(a.begin(), a.end(), u.begin(), equal_buffer) where the binary predicate `equal_buffer` is defined as bool equal_buffer( const X::value_type& v1, const X::value_type& v2) { const_buffer b1(v1); const_buffer b2(v2); return buffer_cast<const void>(b1) == buffer_cast<const void>(b2) && buffer_size(b1) == buffer_size(b2); }
`(&a)->~X();`	`void`	note: the destructor is applied to every element of `a`; all the memory is deallocated.
`a.begin();`	`const_iterator` or convertible to `const_iterator`
`a.end();`	`const_iterator` or convertible to `const_iterator`

Convertible to const buffer requirements

A type that meets the requirements for convertibility to a const buffer must meet the requirements of CopyConstructible types (C++ Std, 20.1.3), and the requirements of Assignable types (C++ Std, 23.1).

In the table below, X denotes a class meeting the requirements for convertibility to a const buffer, a and b denote values of type X, and u, v and w denote identifiers.

Table 7.6. ConvertibleToConstBuffer requirements

expression	postcondition
const_buffer u(a); const_buffer v(a);	buffer_cast<const void>(u) == buffer_cast<const void>(v) && buffer_size(u) == buffer_size(v)
const_buffer u(a); const_buffer v = a;	buffer_cast<const void>(u) == buffer_cast<const void>(v) && buffer_size(u) == buffer_size(v)
const_buffer u(a); const_buffer v; v = a;	buffer_cast<const void>(u) == buffer_cast<const void>(v) && buffer_size(u) == buffer_size(v)
const_buffer u(a); const X& v = a; const_buffer w(v);	buffer_cast<const void>(u) == buffer_cast<const void>(w) && buffer_size(u) == buffer_size(w)
const_buffer u(a); X v(a); const_buffer w(v);	buffer_cast<const void>(u) == buffer_cast<const void>(w) && buffer_size(u) == buffer_size(w)
const_buffer u(a); X v = a; const_buffer w(v);	buffer_cast<const void>(u) == buffer_cast<const void>(w) && buffer_size(u) == buffer_size(w)
const_buffer u(a); X v(b); v = a; const_buffer w(v);	buffer_cast<const void>(u) == buffer_cast<const void>(w) && buffer_size(u) == buffer_size(w)

expression

postcondition

const_buffer u(a);
const_buffer v(a);

buffer_cast<const void*>(u) == buffer_cast<const void*>(v)
  && buffer_size(u) == buffer_size(v)

const_buffer u(a);
const_buffer v = a;

buffer_cast<const void*>(u) == buffer_cast<const void*>(v)
  && buffer_size(u) == buffer_size(v)

const_buffer u(a);
const_buffer v; v = a;

buffer_cast<const void*>(u) == buffer_cast<const void*>(v)
  && buffer_size(u) == buffer_size(v)

const_buffer u(a);
const X& v = a;
const_buffer w(v);

buffer_cast<const void*>(u) == buffer_cast<const void*>(w)
  && buffer_size(u) == buffer_size(w)

const_buffer u(a);
X v(a);
const_buffer w(v);

buffer_cast<const void*>(u) == buffer_cast<const void*>(w)
  && buffer_size(u) == buffer_size(w)

const_buffer u(a);
X v = a;
const_buffer w(v);

buffer_cast<const void*>(u) == buffer_cast<const void*>(w)
  && buffer_size(u) == buffer_size(w)

const_buffer u(a);
X v(b); v = a;
const_buffer w(v);

buffer_cast<const void*>(u) == buffer_cast<const void*>(w)
  && buffer_size(u) == buffer_size(w)

Convertible to mutable buffer requirements

A type that meets the requirements for convertibility to a mutable buffer must meet the requirements of CopyConstructible types (C++ Std, 20.1.3), and the requirements of Assignable types (C++ Std, 23.1).

In the table below, X denotes a class meeting the requirements for convertibility to a mutable buffer, a and b denote values of type X, and u, v and w denote identifiers.

Table 7.7. ConvertibleToMutableBuffer requirements

expression

postcondition

mutable_buffer u(a);
mutable_buffer v(a);

buffer_cast<void*>(u) == buffer_cast<void*>(v)
  && buffer_size(u) == buffer_size(v)

mutable_buffer u(a);
mutable_buffer v = a;

buffer_cast<void*>(u) == buffer_cast<void*>(v)
  && buffer_size(u) == buffer_size(v)

mutable_buffer u(a);
mutable_buffer v; v = a;

buffer_cast<void*>(u) == buffer_cast<void*>(v)
  && buffer_size(u) == buffer_size(v)

mutable_buffer u(a);
const X& v = a;
mutable_buffer w(v);

buffer_cast<void*>(u) == buffer_cast<void*>(w)
  && buffer_size(u) == buffer_size(w)

mutable_buffer u(a);
X v(a);
mutable_buffer w(v);

buffer_cast<void*>(u) == buffer_cast<void*>(w)
  && buffer_size(u) == buffer_size(w)

mutable_buffer u(a);
X v = a;
mutable_buffer w(v);

buffer_cast<void*>(u) == buffer_cast<void*>(w)
  && buffer_size(u) == buffer_size(w)

mutable_buffer u(a);
X v(b); v = a;
mutable_buffer w(v);

buffer_cast<void*>(u) == buffer_cast<void*>(w)
  && buffer_size(u) == buffer_size(w)

Datagram socket service requirements

A datagram socket service must meet the requirements for a socket service, as well as the additional requirements listed below.

In the table below, X denotes a datagram socket service class for protocol Protocol, a denotes a value of type X, b denotes a value of type X::implementation_type, e denotes a value of type Protocol::endpoint, ec denotes a value of type error_code, f denotes a value of type socket_base::message_flags, 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 7.8. DatagramSocketService requirements

expression	return type	assertion/note pre/post-condition
`a.receive(b, mb, f, ec);`	`size_t`	pre: `a.is_open(b)`. Reads one or more bytes of data from a connected socket `b`. 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`.
`a.async_receive(b, mb, f, rh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to read one or more bytes of data from a connected socket `b`. 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 operation completes successfully, the `ReadHandler` object `rh` is invoked with the number of bytes transferred. Otherwise it is invoked with `0`.
`a.receive_from(b, mb, e, f, ec);`	`size_t`	pre: `a.is_open(b)`. Reads one or more bytes of data from an unconnected socket `b`. 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`.
`a.async_receive_from(b, mb, e, f, rh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to read one or more bytes of data from an unconnected socket `b`. 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. The program must ensure the object `e` is valid until the handler for the asynchronous operation is invoked. If the operation completes successfully, the `ReadHandler` object `rh` is invoked with the number of bytes transferred. Otherwise it is invoked with `0`.
`a.send(b, cb, f, ec);`	`size_t`	pre: `a.is_open(b)`. Writes one or more bytes of data to a connected socket `b`. 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`.
`a.async_send(b, cb, f, wh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to write one or more bytes of data to a connected socket `b`. 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 operation completes successfully, the `WriteHandler` object `wh` is invoked with the number of bytes transferred. Otherwise it is invoked with `0`.
const typename Protocol::endpoint& u = e; a.send_to(b, cb, u, f, ec);	`size_t`	pre: `a.is_open(b)`. Writes one or more bytes of data to an unconnected socket `b`. 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`.
const typename Protocol::endpoint& u = e; a.async_send(b, cb, u, f, wh);	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to write one or more bytes of data to an unconnected socket `b`. 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 operation completes successfully, the `WriteHandler` object `wh` is invoked with the number of bytes transferred. Otherwise it is invoked with `0`.

Descriptor service requirements

A descriptor service must meet the requirements for an I/O object service with support for movability, as well as the additional requirements listed below.

In the table below, X denotes a descriptor service class, a and ao denote values of type X, b and c denote values of type X::implementation_type, n denotes a value of type X::native_handle_type, ec denotes a value of type error_code, i denotes a value meeting IoControlCommand requirements, and u and v denote identifiers.

Table 7.9. DescriptorService requirements

expression	return type	assertion/note pre/post-condition
`X::native_handle_type`		The implementation-defined native representation of a descriptor. Must satisfy the requirements of `CopyConstructible` types (C++ Std, 20.1.3), and the requirements of `Assignable` types (C++ Std, 23.1).
`a.construct(b);`		From IoObjectService requirements. post: `!a.is_open(b)`.
`a.destroy(b);`		From IoObjectService requirements. Implicitly cancels asynchronous operations, as if by calling `a.close(b, ec)`.
a.move_construct(b, c);		From IoObjectService requirements. The underlying native representation is moved from `c` to `b`.
a.move_assign(b, ao, c);		From IoObjectService requirements. Implicitly cancels asynchronous operations associated with `b`, as if by calling `a.close(b, ec)`. Then the underlying native representation is moved from `c` to `b`.
a.assign(b, n, ec);	`error_code`	pre: `!a.is_open(b)`. post: `!!ec \|\| a.is_open(b)`.
a.is_open(b);	`bool`
const X& u = a; const X::implementation_type& v = b; u.is_open(v);	`bool`
a.close(b, ec);	`error_code`	If `a.is_open()` is true, causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code `error::operation_aborted`. post: `!a.is_open(b)`.
a.native_handle(b);	`X::native_handle_type`
a.cancel(b, ec);	`error_code`	pre: `a.is_open(b)`. Causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code `error::operation_aborted`.
a.io_control(b, i, ec);	`error_code`	pre: `a.is_open(b)`.

Endpoint requirements

An endpoint must meet the requirements of CopyConstructible types (C++ Std, 20.1.3), and the requirements of Assignable types (C++ Std, 23.1).

In the table below, X denotes an endpoint class, a denotes a value of type X, s denotes a size in bytes, and u denotes an identifier.

Table 7.10. Endpoint requirements

expression	type	assertion/note pre/post-conditions
`X::protocol_type`	type meeting protocol requirements
`X u;`
`X();`
`a.protocol();`	`protocol_type`
`a.data();`	a pointer	Returns a pointer suitable for passing as the address argument to POSIX functions such as `accept()`, `getpeername()`, `getsockname()` and `recvfrom()`. The implementation shall perform a `reinterpret_cast` on the pointer to convert it to `sockaddr*`.
`const X& u = a; u.data();`	a pointer	Returns a pointer suitable for passing as the address argument to POSIX functions such as `connect()`, or as the dest_addr argument to POSIX functions such as `sendto()`. The implementation shall perform a `reinterpret_cast` on the pointer to convert it to `const sockaddr*`.
`a.size();`	`size_t`	Returns a value suitable for passing as the address_len argument to POSIX functions such as `connect()`, or as the dest_len argument to POSIX functions such as `sendto()`, after appropriate integer conversion has been performed.
`a.resize(s);`		post: `a.size() == s` Passed the value contained in the address_len argument to POSIX functions such as `accept()`, `getpeername()`, `getsockname()` and `recvfrom()`, after successful completion of the function. Permitted to throw an exception if the protocol associated with the endpoint object `a` does not support the specified size.
`a.capacity();`	`size_t`	Returns a value suitable for passing as the address_len argument to POSIX functions such as `accept()`, `getpeername()`, `getsockname()` and `recvfrom()`, after appropriate integer conversion has been performed.

Gettable serial port option requirements

In the table below, X denotes a serial port option class, a denotes a value of X, ec denotes a value of type error_code, and s denotes a value of implementation-defined type storage (where storage is the type DCB on Windows and termios on POSIX platforms), and u denotes an identifier.

Table 7.11. GettableSerialPortOption requirements

expression	type	assertion/note pre/post-conditions
`const` `storage``& u = s;` `a.load(u, ec);`	`error_code`	Retrieves the value of the serial port option from the storage. If successful, sets `ec` such that `!ec` is true. If an error occurred, sets `ec` such that `!!ec` is true. Returns `ec`.

Gettable socket option requirements

In the table below, X denotes a socket option class, a denotes a value of X, p denotes a value that meets the protocol requirements, and u denotes an identifier.

Table 7.12. GettableSocketOption requirements

expression	type	assertion/note pre/post-conditions
`a.level(p);`	`int`	Returns a value suitable for passing as the level argument to POSIX `getsockopt()` (or equivalent).
`a.name(p);`	`int`	Returns a value suitable for passing as the option_name argument to POSIX `getsockopt()` (or equivalent).
`a.data(p);`	a pointer, convertible to `void*`	Returns a pointer suitable for passing as the option_value argument to POSIX `getsockopt()` (or equivalent).
`a.size(p);`	`size_t`	Returns a value suitable for passing as the option_len argument to POSIX `getsockopt()` (or equivalent), after appropriate integer conversion has been performed.
`a.resize(p, s);`		post: `a.size(p) == s`. Passed the value contained in the option_len argument to POSIX `getsockopt()` (or equivalent) after successful completion of the function. Permitted to throw an exception if the socket option object `a` does not support the specified size.

Handlers

A handler must meet the requirements of CopyConstructible types (C++ Std, 20.1.3).

In the table below, X denotes a handler class, h denotes a value of X, p denotes a pointer to a block of allocated memory of type void*, s denotes the size for a block of allocated memory, and f denotes a function object taking no arguments.

Table 7.13. Handler requirements

expression

return type

assertion/note
pre/post-conditions

using boost::asio::asio_handler_allocate;
asio_handler_allocate(s, &h);

void*

Returns a pointer to a block of memory of size s. The pointer must satisfy the same alignment requirements as a pointer returned by ::operator new(). Throws bad_alloc on failure.

The asio_handler_allocate() function is located using argument-dependent lookup. The function boost::asio::asio_handler_allocate() serves as a default if no user-supplied function is available.

using boost::asio::asio_handler_deallocate;
asio_handler_deallocate(p, s, &h);

Frees a block of memory associated with a pointer p, of at least size s, that was previously allocated using asio_handler_allocate().

The asio_handler_deallocate() function is located using argument-dependent lookup. The function boost::asio::asio_handler_deallocate() serves as a default if no user-supplied function is available.

using boost::asio::asio_handler_invoke;
asio_handler_invoke(f, &h);

Causes the function object f to be executed as if by calling f().

The asio_handler_invoke() function is located using argument-dependent lookup. The function boost::asio::asio_handler_invoke() serves as a default if no user-supplied function is available.

Handle service requirements

A handle service must meet the requirements for an I/O object service with support for movability, as well as the additional requirements listed below.

In the table below, X denotes a handle service class, a and ao denote values of type X, b and c denote values of type X::implementation_type, n denotes a value of type X::native_handle_type, ec denotes a value of type error_code, and u and v denote identifiers.

Table 7.14. HandleService requirements

expression	return type	assertion/note pre/post-condition
`X::native_handle_type`		The implementation-defined native representation of a handle. Must satisfy the requirements of `CopyConstructible` types (C++ Std, 20.1.3), and the requirements of `Assignable` types (C++ Std, 23.1).
`a.construct(b);`		From IoObjectService requirements. post: `!a.is_open(b)`.
`a.destroy(b);`		From IoObjectService requirements. Implicitly cancels asynchronous operations, as if by calling `a.close(b, ec)`.
a.move_construct(b, c);		From IoObjectService requirements. The underlying native representation is moved from `c` to `b`.
a.move_assign(b, ao, c);		From IoObjectService requirements. Implicitly cancels asynchronous operations associated with `b`, as if by calling `a.close(b, ec)`. Then the underlying native representation is moved from `c` to `b`.
a.assign(b, n, ec);	`error_code`	pre: `!a.is_open(b)`. post: `!!ec \|\| a.is_open(b)`.
a.is_open(b);	`bool`
const X& u = a; const X::implementation_type& v = b; u.is_open(v);	`bool`
a.close(b, ec);	`error_code`	If `a.is_open()` is true, causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code `error::operation_aborted`. post: `!a.is_open(b)`.
a.native_handle(b);	`X::native_handle_type`
a.cancel(b, ec);	`error_code`	pre: `a.is_open(b)`. Causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code `error::operation_aborted`.

SSL handshake handler requirements

A handshake handler must meet the requirements for a handler. A value h of a handshake handler class should work correctly in the expression h(ec), where ec is an lvalue of type const error_code.

Examples

A free function as a handshake handler:

void handshake_handler(
    const boost::system::error_code& ec)
{
  ...
}

A handshake handler function object:

struct handshake_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a handshake handler using bind():

void my_class::handshake_handler(
    const boost::system::error_code& ec)
{
  ...
}
...
ssl_stream.async_handshake(...,
    boost::bind(&my_class::handshake_handler,
      this, boost::asio::placeholders::error));

Internet protocol requirements

An internet protocol must meet the requirements for a protocol as well as the additional requirements listed below.

In the table below, X denotes an internet protocol class, a denotes a value of type X, and b denotes a value of type X.

Table 7.15. InternetProtocol requirements

expression	return type	assertion/note pre/post-conditions
`X::resolver`	`ip::basic_resolver<X>`	The type of a resolver for the protocol.
`X::v4()`	`X`	Returns an object representing the IP version 4 protocol.
`X::v6()`	`X`	Returns an object representing the IP version 6 protocol.
`a == b`	convertible to `bool`	Returns whether two protocol objects are equal.
`a != b`	convertible to `bool`	Returns `!(a == b)`.

I/O control command requirements

In the table below, X denotes an I/O control command class, a denotes a value of X, and u denotes an identifier.

Table 7.16. IoControlCommand requirements

expression	type	assertion/note pre/post-conditions
`a.name();`	`int`	Returns a value suitable for passing as the request argument to POSIX `ioctl()` (or equivalent).
`a.data();`	a pointer, convertible to `void*`

I/O object service requirements

An I/O object service must meet the requirements for a service, as well as the requirements listed below.

In the table below, X denotes an I/O object service class, a and ao denote values of type X, b and c denote values of type X::implementation_type, and u denotes an identifier.

Table 7.17. IoObjectService requirements

expression	return type	assertion/note pre/post-condition
`X::implementation_type`
`X::implementation_type u;`		note: `X::implementation_type` has a public default constructor and destructor.
a.construct(b);
a.destroy(b);		note: `destroy()` will only be called on a value that has previously been initialised with `construct()` or `move_construct()`.
a.move_construct(b, c);		note: only required for I/O objects that support movability.
a.move_assign(b, ao, c);		note: only required for I/O objects that support movability.

Mutable buffer sequence requirements

In the table below, X denotes a class containing objects of type T, a denotes a value of type X and u denotes an identifier.

Table 7.18. MutableBufferSequence requirements

expression	return type	assertion/note pre/post-condition
`X::value_type`	`T`	`T` meets the requirements for ConvertibleToMutableBuffer.
`X::const_iterator`	iterator type pointing to `T`	`const_iterator` meets the requirements for bidirectional iterators (C++ Std, 24.1.4).
`X(a);`		post: `equal_mutable_buffer_seq(a, X(a))` where the binary predicate `equal_mutable_buffer_seq` is defined as bool equal_mutable_buffer_seq( const X& x1, const X& x2) { return distance(x1.begin(), x1.end()) == distance(x2.begin(), x2.end()) && equal(x1.begin(), x1.end(), x2.begin(), equal_buffer); } and the binary predicate `equal_buffer` is defined as bool equal_buffer( const X::value_type& v1, const X::value_type& v2) { mutable_buffer b1(v1); mutable_buffer b2(v2); return buffer_cast<const void>(b1) == buffer_cast<const void>(b2) && buffer_size(b1) == buffer_size(b2); }
`X u(a);`		post: distance(a.begin(), a.end()) == distance(u.begin(), u.end()) && equal(a.begin(), a.end(), u.begin(), equal_buffer) where the binary predicate `equal_buffer` is defined as bool equal_buffer( const X::value_type& v1, const X::value_type& v2) { mutable_buffer b1(v1); mutable_buffer b2(v2); return buffer_cast<const void>(b1) == buffer_cast<const void>(b2) && buffer_size(b1) == buffer_size(b2); }
`(&a)->~X();`	`void`	note: the destructor is applied to every element of `a`; all the memory is deallocated.
`a.begin();`	`const_iterator` or convertible to `const_iterator`
`a.end();`	`const_iterator` or convertible to `const_iterator`

Object handle service requirements

An object handle service must meet the requirements for a handle service, as well as the additional requirements listed below.

In the table below, X denotes an object 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, and wh denotes a value meeting WaitHandler requirements.

Table 7.19. ObjectHandleService requirements

expression	return type	assertion/note pre/post-condition
`a.wait(b, ec);`	`error_code`	pre: `a.is_open(b)`. Synchronously waits for the object represented by handle `b` to become signalled.
`a.async_wait(b, wh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to wait for the object represented by handle `b` to become signalled. The operation is performed via the `io_service` object `a.get_io_service()` and behaves according to asynchronous operation requirements.

Protocol requirements

A protocol must meet the requirements of CopyConstructible types (C++ Std, 20.1.3), and the requirements of Assignable types (C++ Std, 23.1).

In the table below, X denotes a protocol class, and a denotes a value of X.

Table 7.20. Protocol requirements

expression	return type	assertion/note pre/post-conditions
`X::endpoint`	type meeting endpoint requirements
`a.family()`	`int`	Returns a value suitable for passing as the domain argument to POSIX `socket()` (or equivalent).
`a.type()`	`int`	Returns a value suitable for passing as the type argument to POSIX `socket()` (or equivalent).
`a.protocol()`	`int`	Returns a value suitable for passing as the protocol argument to POSIX `socket()` (or equivalent).

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 7.21. 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`.

Raw socket service requirements

A raw socket service must meet the requirements for a socket service, as well as the additional requirements listed below.

In the table below, X denotes a raw socket service class for protocol Protocol, a denotes a value of type X, b denotes a value of type X::implementation_type, e denotes a value of type Protocol::endpoint, ec denotes a value of type error_code, f denotes a value of type socket_base::message_flags, 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 7.22. RawSocketService requirements

expression	return type	assertion/note pre/post-condition
`a.receive(b, mb, f, ec);`	`size_t`	pre: `a.is_open(b)`. Reads one or more bytes of data from a connected socket `b`. 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`.
`a.async_receive(b, mb, f, rh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to read one or more bytes of data from a connected socket `b`. 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 operation completes successfully, the `ReadHandler` object `rh` is invoked with the number of bytes transferred. Otherwise it is invoked with `0`.
`a.receive_from(b, mb, e, f, ec);`	`size_t`	pre: `a.is_open(b)`. Reads one or more bytes of data from an unconnected socket `b`. 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`.
`a.async_receive_from(b, mb, e, f, rh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to read one or more bytes of data from an unconnected socket `b`. 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. The program must ensure the object `e` is valid until the handler for the asynchronous operation is invoked. If the operation completes successfully, the `ReadHandler` object `rh` is invoked with the number of bytes transferred. Otherwise it is invoked with `0`.
`a.send(b, cb, f, ec);`	`size_t`	pre: `a.is_open(b)`. Writes one or more bytes of data to a connected socket `b`. 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`.
`a.async_send(b, cb, f, wh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to write one or more bytes of data to a connected socket `b`. 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 operation completes successfully, the `WriteHandler` object `wh` is invoked with the number of bytes transferred. Otherwise it is invoked with `0`.
const typename Protocol::endpoint& u = e; a.send_to(b, cb, u, f, ec);	`size_t`	pre: `a.is_open(b)`. Writes one or more bytes of data to an unconnected socket `b`. 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`.
const typename Protocol::endpoint& u = e; a.async_send(b, cb, u, f, wh);	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to write one or more bytes of data to an unconnected socket `b`. 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 operation completes successfully, the `WriteHandler` object `wh` is invoked with the number of bytes transferred. Otherwise it is invoked with `0`.

Read handler requirements

A read handler must meet the requirements for a handler. A value h of a read handler class should work correctly in the expression h(ec, s), where ec is an lvalue of type const error_code and s is an lvalue of type const size_t.

Examples

A free function as a read handler:

void read_handler(
    const boost::system::error_code& ec,
    std::size_t bytes_transferred)
{
  ...
}

A read handler function object:

struct read_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec,
      std::size_t bytes_transferred)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a read handler using bind():

void my_class::read_handler(
    const boost::system::error_code& ec,
    std::size_t bytes_transferred)
{
  ...
}
...
socket.async_read(...,
    boost::bind(&my_class::read_handler,
      this, boost::asio::placeholders::error,
      boost::asio::placeholders::bytes_transferred));

Resolve handler requirements

A resolve handler must meet the requirements for a handler. A value h of a resolve handler class should work correctly in the expression h(ec, i), where ec is an lvalue of type const error_code and i is an lvalue of type const ip::basic_resolver_iterator<InternetProtocol>. InternetProtocol is the template parameter of the resolver_service which is used to initiate the asynchronous operation.

Examples

A free function as a resolve handler:

void resolve_handler(
    const boost::system::error_code& ec,
    boost::asio::ip::tcp::resolver::iterator iterator)
{
  ...
}

A resolve handler function object:

struct resolve_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec,
      boost::asio::ip::tcp::resolver::iterator iterator)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a resolve handler using bind():

void my_class::resolve_handler(
    const boost::system::error_code& ec,
    boost::asio::ip::tcp::resolver::iterator iterator)
{
  ...
}
...
resolver.async_resolve(...,
    boost::bind(&my_class::resolve_handler,
      this, boost::asio::placeholders::error,
      boost::asio::placeholders::iterator));

Resolver service requirements

A resolver service must meet the requirements for an I/O object service, as well as the additional requirements listed below.

In the table below, X denotes a resolver service class for protocol InternetProtocol, a denotes a value of type X, b denotes a value of type X::implementation_type, q denotes a value of type ip::basic_resolver_query<InternetProtocol>, e denotes a value of type ip::basic_endpoint<InternetProtocol>, ec denotes a value of type error_code, and h denotes a value meeting ResolveHandler requirements.

Table 7.23. ResolverService requirements

expression	return type	assertion/note pre/post-condition
`a.destroy(b);`		From IoObjectService requirements. Implicitly cancels asynchronous resolve operations, as if by calling `a.cancel(b, ec)`.
a.cancel(b, ec);	`error_code`	Causes any outstanding asynchronous resolve operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code `error::operation_aborted`.
a.resolve(b, q, ec);	ip::basic_resolver_iterator< InternetProtocol>	On success, returns an iterator `i` such that `i != ip::basic_resolver_iterator<InternetProtocol>()`. Otherwise returns `ip::basic_resolver_iterator<InternetProtocol>()`.
a.async_resolve(b, q, h);		Initiates an asynchronous resolve operation that is performed via the `io_service` object `a.get_io_service()` and behaves according to asynchronous operation requirements. If the operation completes successfully, the `ResolveHandler` object `h` shall be invoked with an iterator object `i` such that the condition `i != ip::basic_resolver_iterator<InternetProtocol>()` holds. Otherwise it is invoked with `ip::basic_resolver_iterator<InternetProtocol>()`.
a.resolve(b, e, ec);	ip::basic_resolver_iterator< InternetProtocol>	On success, returns an iterator `i` such that `i != ip::basic_resolver_iterator<InternetProtocol>()`. Otherwise returns `ip::basic_resolver_iterator<InternetProtocol>()`.
a.async_resolve(b, e, h);		Initiates an asynchronous resolve operation that is performed via the `io_service` object `a.get_io_service()` and behaves according to asynchronous operation requirements. If the operation completes successfully, the `ResolveHandler` object `h` shall be invoked with an iterator object `i` such that the condition `i != ip::basic_resolver_iterator<InternetProtocol>()` holds. Otherwise it is invoked with `ip::basic_resolver_iterator<InternetProtocol>()`.

Sequenced packet socket service requirements

A sequenced packet socket service must meet the requirements for a socket service, as well as the additional requirements listed below.

In the table below, X denotes a stream socket 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, f denotes a value of type socket_base::message_flags, g denotes an lvalue of type socket_base::message_flags, 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 7.24. StreamSocketService requirements

expression	return type	assertion/note pre/post-condition
`a.receive(b, mb, f, g, ec);`	`size_t`	pre: `a.is_open(b)`. Reads one or more bytes of data from a connected socket `b`. 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, sets `g` to the flags associated with the received data, and returns the number of bytes read. Otherwise, sets `g` to `0` and returns `0`.
`a.async_receive(b, mb, f, g, rh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to read one or more bytes of data from a connected socket `b`. 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 operation completes successfully, sets `g` to the flags associated with the received data, then invokes the `ReadHandler` object `rh` with the number of bytes transferred. Otherwise, sets `g` to `0` and invokes `rh` with `0` bytes transferred.
`a.send(b, cb, f, ec);`	`size_t`	pre: `a.is_open(b)`. Writes one or more bytes of data to a connected socket `b`. 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`.
`a.async_send(b, cb, f, wh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to write one or more bytes of data to a connected socket `b`. 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 operation completes successfully, the `WriteHandler` object `wh` is invoked with the number of bytes transferred. Otherwise it is invoked with `0`.

Serial port service requirements

A serial port service must meet the requirements for an I/O object service with support for movability, as well as the additional requirements listed below.

In the table below, X denotes a serial port service class, a and ao denote values of type X, d denotes a serial port device name of type std::string, b and c denote values of type X::implementation_type, n denotes a value of type X::native_handle_type, ec denotes a value of type error_code, s denotes a value meeting SettableSerialPortOption requirements, g denotes a value meeting GettableSerialPortOption requirements, 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. and u and v denote identifiers.

Table 7.25. SerialPortService requirements

expression	return type	assertion/note pre/post-condition
`X::native_handle_type`		The implementation-defined native representation of a serial port. Must satisfy the requirements of `CopyConstructible` types (C++ Std, 20.1.3), and the requirements of `Assignable` types (C++ Std, 23.1).
`a.construct(b);`		From IoObjectService requirements. post: `!a.is_open(b)`.
`a.destroy(b);`		From IoObjectService requirements. Implicitly cancels asynchronous operations, as if by calling `a.close(b, ec)`.
a.move_construct(b, c);		From IoObjectService requirements. The underlying native representation is moved from `c` to `b`.
a.move_assign(b, ao, c);		From IoObjectService requirements. Implicitly cancels asynchronous operations associated with `b`, as if by calling `a.close(b, ec)`. Then the underlying native representation is moved from `c` to `b`.
const std::string& u = d; a.open(b, u, ec);	`error_code`	pre: `!a.is_open(b)`. post: `!!ec \|\| a.is_open(b)`.
a.assign(b, n, ec);	`error_code`	pre: `!a.is_open(b)`. post: `!!ec \|\| a.is_open(b)`.
a.is_open(b);	`bool`
const X& u = a; const X::implementation_type& v = b; u.is_open(v);	`bool`
a.close(b, ec);	`error_code`	If `a.is_open()` is true, causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code `error::operation_aborted`. post: `!a.is_open(b)`.
a.native_handle(b);	`X::native_handle_type`
a.cancel(b, ec);	`error_code`	pre: `a.is_open(b)`. Causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code `error::operation_aborted`.
a.set_option(b, s, ec);	`error_code`	pre: `a.is_open(b)`.
a.get_option(b, g, ec);	`error_code`	pre: `a.is_open(b)`.
const X& u = a; const X::implementation_type& v = b; u.get_option(v, g, ec);	`error_code`	pre: `a.is_open(b)`.
a.send_break(b, ec);	`error_code`	pre: `a.is_open(b)`.
`a.read_some(b, mb, ec);`	`size_t`	pre: `a.is_open(b)`. Reads one or more bytes of data from a serial port `b`. 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. If the operation completes due to graceful connection closure by the peer, the operation shall fail with `error::eof`.
`a.async_read_some(b, mb, rh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to read one or more bytes of data from a serial port `b`. 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 due to graceful connection closure by the peer, the operation shall fail with `error::eof`. 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(b, cb, ec);`	`size_t`	pre: `a.is_open(b)`. Writes one or more bytes of data to a serial port `b`. 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(b, cb, wh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to write one or more bytes of data to a serial port `b`. 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`.

Service requirements

A class is a service if it is publicly derived from another service, or if it is a class derived from io_service::service and contains a publicly-accessible declaration as follows:

static io_service::id id;

All services define a one-argument constructor that takes a reference to the io_service object that owns the service. This constructor is explicit, preventing its participation in automatic conversions. For example:

class my_service : public io_service::service
{
public:
  static io_service::id id;
  explicit my_service(io_service& ios);
private:
  virtual void shutdown_service();
  ...
};

A service's shutdown_service member function must cause all copies of user-defined handler objects that are held by the service to be destroyed.

Settable serial port option requirements

In the table below, X denotes a serial port option class, a denotes a value of X, ec denotes a value of type error_code, and s denotes a value of implementation-defined type storage (where storage is the type DCB on Windows and termios on POSIX platforms), and u denotes an identifier.

Table 7.26. SettableSerialPortOption requirements

expression	type	assertion/note pre/post-conditions
`const X& u = a;` `u.store(s, ec);`	`error_code`	Saves the value of the serial port option to the storage. If successful, sets `ec` such that `!ec` is true. If an error occurred, sets `ec` such that `!!ec` is true. Returns `ec`.

Settable socket option requirements

In the table below, X denotes a socket option class, a denotes a value of X, p denotes a value that meets the protocol requirements, and u denotes an identifier.

Table 7.27. SettableSocketOption requirements

expression	type	assertion/note pre/post-conditions
`a.level(p);`	`int`	Returns a value suitable for passing as the level argument to POSIX `setsockopt()` (or equivalent).
`a.name(p);`	`int`	Returns a value suitable for passing as the option_name argument to POSIX `setsockopt()` (or equivalent).
`const X& u = a; u.data(p);`	a pointer, convertible to `const void*`	Returns a pointer suitable for passing as the option_value argument to POSIX `setsockopt()` (or equivalent).
`a.size(p);`	`size_t`	Returns a value suitable for passing as the option_len argument to POSIX `setsockopt()` (or equivalent), after appropriate integer conversion has been performed.

SSL shutdown handler requirements

A shutdown handler must meet the requirements for a handler. A value h of a shutdown handler class should work correctly in the expression h(ec), where ec is an lvalue of type const error_code.

Examples

A free function as a shutdown handler:

void shutdown_handler(
    const boost::system::error_code& ec)
{
  ...
}

A shutdown handler function object:

struct shutdown_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a shutdown handler using bind():

void my_class::shutdown_handler(
    const boost::system::error_code& ec)
{
  ...
}
...
ssl_stream.async_shutdown(
    boost::bind(&my_class::shutdown_handler,
      this, boost::asio::placeholders::error));

Signal handler requirements

A signal handler must meet the requirements for a handler. A value h of a signal handler class should work correctly in the expression h(ec, n), where ec is an lvalue of type const error_code and n is an lvalue of type const int.

Examples

A free function as a signal handler:

void signal_handler(
    const boost::system::error_code& ec,
    int signal_number)
{
  ...
}

A signal handler function object:

struct signal_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec,
      int signal_number)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a signal handler using bind():

void my_class::signal_handler(
    const boost::system::error_code& ec,
    int signal_number)
{
  ...
}
...
my_signal_set.async_wait(
    boost::bind(&my_class::signal_handler,
      this, boost::asio::placeholders::error,
      boost::asio::placeholders::signal_number));

Signal set service requirements

A signal set service must meet the requirements for an I/O object service, as well as the additional requirements listed below.

In the table below, X denotes a signal set 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, n denotes a value of type int, and sh denotes a value meeting SignalHandler requirements.

Table 7.28. SignalSetService requirements

expression	return type	assertion/note pre/post-condition
`a.construct(b);`		From IoObjectService requirements.
`a.destroy(b);`		From IoObjectService requirements. Implicitly clears the registered signals as if by calling `a.clear(b, ec)`, then implicitly cancels outstanding asynchronous operations as if by calling `a.cancel(b, ec)`.
a.add(b, n, ec);	`error_code`
a.remove(b, n, ec);	`error_code`
a.clear(b, ec);	`error_code`
a.cancel(b, ec);	`error_code`
`a.async_wait(b, sh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to wait for the delivery of one of the signals registered for the signal set `b`. The operation is performed via the `io_service` object `a.get_io_service()` and behaves according to asynchronous operation requirements. If the operation completes successfully, the `SignalHandler` object `sh` is invoked with the number identifying the delivered signal. Otherwise it is invoked with `0`.

Socket acceptor service requirements

A socket acceptor service must meet the requirements for an I/O object service, as well as the additional requirements listed below.

In the table below, X denotes a socket acceptor service class for protocol Protocol, a and ao denote values of type X, b and c denote values of type X::implementation_type, p denotes a value of type Protocol, n denotes a value of type X::native_handle_type, e denotes a value of type Protocol::endpoint, ec denotes a value of type error_code, s denotes a value meeting SettableSocketOption requirements, g denotes a value meeting GettableSocketOption requirements, i denotes a value meeting IoControlCommand requirements, k denotes a value of type basic_socket<Protocol, SocketService> where SocketService is a type meeting socket service requirements, ah denotes a value meeting AcceptHandler requirements, and u and v denote identifiers.

Table 7.29. SocketAcceptorService requirements

expression	return type	assertion/note pre/post-condition
`X::native_handle_type`		The implementation-defined native representation of a socket acceptor. Must satisfy the requirements of `CopyConstructible` types (C++ Std, 20.1.3), and the requirements of `Assignable` types (C++ Std, 23.1).
`a.construct(b);`		From IoObjectService requirements. post: `!a.is_open(b)`.
`a.destroy(b);`		From IoObjectService requirements. Implicitly cancels asynchronous operations, as if by calling `a.close(b, ec)`.
a.move_construct(b, c);		From IoObjectService requirements. The underlying native representation is moved from `c` to `b`.
a.move_assign(b, ao, c);		From IoObjectService requirements. Implicitly cancels asynchronous operations associated with `b`, as if by calling `a.close(b, ec)`. Then the underlying native representation is moved from `c` to `b`.
a.open(b, p, ec);	`error_code`	pre: `!a.is_open(b)`. post: `!!ec \|\| a.is_open(b)`.
a.assign(b, p, n, ec);	`error_code`	pre: `!a.is_open(b)`. post: `!!ec \|\| a.is_open(b)`.
a.is_open(b);	`bool`
const X& u = a; const X::implementation_type& v = b; u.is_open(v);	`bool`
a.close(b, ec);	`error_code`	If `a.is_open()` is true, causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code `error::operation_aborted`. post: `!a.is_open(b)`.
a.native_handle(b);	`X::native_handle_type`
a.cancel(b, ec);	`error_code`	pre: `a.is_open(b)`. Causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code `error::operation_aborted`.
a.set_option(b, s, ec);	`error_code`	pre: `a.is_open(b)`.
a.get_option(b, g, ec);	`error_code`	pre: `a.is_open(b)`.
const X& u = a; const X::implementation_type& v = b; u.get_option(v, g, ec);	`error_code`	pre: `a.is_open(b)`.
a.io_control(b, i, ec);	`error_code`	pre: `a.is_open(b)`.
const typename Protocol::endpoint& u = e; a.bind(b, u, ec);	`error_code`	pre: `a.is_open(b)`.
a.local_endpoint(b, ec);	`Protocol::endpoint`	pre: `a.is_open(b)`.
const X& u = a; const X::implementation_type& v = b; u.local_endpoint(v, ec);	`Protocol::endpoint`	pre: `a.is_open(b)`.
a.accept(b, k, &e, ec);	`error_code`	pre: `a.is_open(b) && !k.is_open()`. post: `k.is_open()`
a.accept(b, k, 0, ec);	`error_code`	pre: `a.is_open(b) && !k.is_open()`. post: `k.is_open()`
a.async_accept(b, k, &e, ah);		pre: `a.is_open(b) && !k.is_open()`. Initiates an asynchronous accept operation that is performed via the `io_service` object `a.get_io_service()` and behaves according to asynchronous operation requirements. The program must ensure the objects `k` and `e` are valid until the handler for the asynchronous operation is invoked.
a.async_accept(b, k, 0, ah);		pre: `a.is_open(b) && !k.is_open()`. Initiates an asynchronous accept operation that is performed via the `io_service` object `a.get_io_service()` and behaves according to asynchronous operation requirements. The program must ensure the object `k` is valid until the handler for the asynchronous operation is invoked.

Socket service requirements

A socket service must meet the requirements for an I/O object service with support for movability, as well as the additional requirements listed below.

In the table below, X denotes a socket service class for protocol Protocol, a and ao denote values of type X, b and c denote values of type X::implementation_type, p denotes a value of type Protocol, n denotes a value of type X::native_handle_type, e denotes a value of type Protocol::endpoint, ec denotes a value of type error_code, s denotes a value meeting SettableSocketOption requirements, g denotes a value meeting GettableSocketOption requirements, i denotes a value meeting IoControlCommand requirements, h denotes a value of type socket_base::shutdown_type, ch denotes a value meeting ConnectHandler requirements, and u and v denote identifiers.

Table 7.30. SocketService requirements

expression	return type	assertion/note pre/post-condition
`X::native_handle_type`		The implementation-defined native representation of a socket. Must satisfy the requirements of `CopyConstructible` types (C++ Std, 20.1.3), and the requirements of `Assignable` types (C++ Std, 23.1).
`a.construct(b);`		From IoObjectService requirements. post: `!a.is_open(b)`.
`a.destroy(b);`		From IoObjectService requirements. Implicitly cancels asynchronous operations, as if by calling `a.close(b, ec)`.
a.move_construct(b, c);		From IoObjectService requirements. The underlying native representation is moved from `c` to `b`.
a.move_assign(b, ao, c);		From IoObjectService requirements. Implicitly cancels asynchronous operations associated with `b`, as if by calling `a.close(b, ec)`. Then the underlying native representation is moved from `c` to `b`.
a.open(b, p, ec);	`error_code`	pre: `!a.is_open(b)`. post: `!!ec \|\| a.is_open(b)`.
a.assign(b, p, n, ec);	`error_code`	pre: `!a.is_open(b)`. post: `!!ec \|\| a.is_open(b)`.
a.is_open(b);	`bool`
const X& u = a; const X::implementation_type& v = b; u.is_open(v);	`bool`
a.close(b, ec);	`error_code`	If `a.is_open()` is true, causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code `error::operation_aborted`. post: `!a.is_open(b)`.
a.native_handle(b);	`X::native_handle_type`
a.cancel(b, ec);	`error_code`	pre: `a.is_open(b)`. Causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code `error::operation_aborted`.
a.set_option(b, s, ec);	`error_code`	pre: `a.is_open(b)`.
a.get_option(b, g, ec);	`error_code`	pre: `a.is_open(b)`.
const X& u = a; const X::implementation_type& v = b; u.get_option(v, g, ec);	`error_code`	pre: `a.is_open(b)`.
a.io_control(b, i, ec);	`error_code`	pre: `a.is_open(b)`.
a.at_mark(b, ec);	`bool`	pre: `a.is_open(b)`.
const X& u = a; const X::implementation_type& v = b; u.at_mark(v, ec);	`bool`	pre: `a.is_open(b)`.
a.available(b, ec);	`size_t`	pre: `a.is_open(b)`.
const X& u = a; const X::implementation_type& v = b; u.available(v, ec);	`size_t`	pre: `a.is_open(b)`.
const typename Protocol::endpoint& u = e; a.bind(b, u, ec);	`error_code`	pre: `a.is_open(b)`.
a.shutdown(b, h, ec);	`error_code`	pre: `a.is_open(b)`.
a.local_endpoint(b, ec);	`Protocol::endpoint`	pre: `a.is_open(b)`.
const X& u = a; const X::implementation_type& v = b; u.local_endpoint(v, ec);	`Protocol::endpoint`	pre: `a.is_open(b)`.
a.remote_endpoint(b, ec);	`Protocol::endpoint`	pre: `a.is_open(b)`.
const X& u = a; const X::implementation_type& v = b; u.remote_endpoint(v, ec);	`Protocol::endpoint`	pre: `a.is_open(b)`.
const typename Protocol::endpoint& u = e; a.connect(b, u, ec);	`error_code`	pre: `a.is_open(b)`.
const typename Protocol::endpoint& u = e; a.async_connect(b, u, ch);		pre: `a.is_open(b)`. Initiates an asynchronous connect operation that is performed via the `io_service` object `a.get_io_service()` and behaves according to asynchronous operation requirements.

Stream descriptor service requirements

A stream descriptor service must meet the requirements for a descriptor service, as well as the additional requirements listed below.

In the table below, X denotes a stream descriptor 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, 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 7.31. StreamDescriptorService requirements

expression	return type	assertion/note pre/post-condition
`a.read_some(b, mb, ec);`	`size_t`	pre: `a.is_open(b)`. Reads one or more bytes of data from a descriptor `b`. 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. If the operation completes due to graceful connection closure by the peer, the operation shall fail with `error::eof`.
`a.async_read_some(b, mb, rh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to read one or more bytes of data from a descriptor `b`. 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 due to graceful connection closure by the peer, the operation shall fail with `error::eof`. 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(b, cb, ec);`	`size_t`	pre: `a.is_open(b)`. Writes one or more bytes of data to a descriptor `b`. 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(b, cb, wh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to write one or more bytes of data to a descriptor `b`. 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`.

Stream handle service requirements

A stream 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 stream 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, 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 7.32. StreamHandleService requirements

expression	return type	assertion/note pre/post-condition
`a.read_some(b, mb, ec);`	`size_t`	pre: `a.is_open(b)`. Reads one or more bytes of data from a handle `b`. 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. If the operation completes due to graceful connection closure by the peer, the operation shall fail with `error::eof`.
`a.async_read_some(b, mb, rh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to read one or more bytes of data from a handle `b`. 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 due to graceful connection closure by the peer, the operation shall fail with `error::eof`. 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(b, cb, ec);`	`size_t`	pre: `a.is_open(b)`. Writes one or more bytes of data to a handle `b`. 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(b, cb, wh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to write one or more bytes of data to a handle `b`. 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`.

Stream socket service requirements

A stream socket service must meet the requirements for a socket service, as well as the additional requirements listed below.

In the table below, X denotes a stream socket 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, f denotes a value of type socket_base::message_flags, 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 7.33. StreamSocketService requirements

expression	return type	assertion/note pre/post-condition
`a.receive(b, mb, f, ec);`	`size_t`	pre: `a.is_open(b)`. Reads one or more bytes of data from a connected socket `b`. 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. If the operation completes due to graceful connection closure by the peer, the operation shall fail with `error::eof`.
`a.async_receive(b, mb, f, rh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to read one or more bytes of data from a connected socket `b`. 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 due to graceful connection closure by the peer, the operation shall fail with `error::eof`. If the operation completes successfully, the `ReadHandler` object `rh` is invoked with the number of bytes transferred. Otherwise it is invoked with `0`.
`a.send(b, cb, f, ec);`	`size_t`	pre: `a.is_open(b)`. Writes one or more bytes of data to a connected socket `b`. 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_send(b, cb, f, wh);`	`void`	pre: `a.is_open(b)`. Initiates an asynchronous operation to write one or more bytes of data to a connected socket `b`. 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`.

Buffer-oriented synchronous random-access read device requirements

In the table below, a denotes a synchronous random-access read device object, o denotes an offset of type boost::uint64_t, mb denotes an object satisfying mutable buffer sequence requirements, and ec denotes an object of type error_code.

Table 7.34. Buffer-oriented synchronous random-access read device requirements

operation

type

semantics, pre/post-conditions

a.read_some_at(o, mb);

size_t

Equivalent to:

error_code ec;
size_t s = a.read_some_at(o, mb, ec);
if (ec) throw system_error(ec);
return s;

a.read_some_at(o, mb, ec);

size_t

Reads one or more bytes of data from the device a at offset o.

The mutable buffer sequence mb specifies memory where the data should be placed. The read_some_at operation shall always fill a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes read and sets ec such that !ec is true. If an error occurred, returns 0 and sets ec such that !!ec is true.

If the total size of all buffers in the sequence mb is 0, the function shall return 0 immediately.

Buffer-oriented synchronous random-access write device requirements

In the table below, a denotes a synchronous random-access write device object, o denotes an offset of type boost::uint64_t, cb denotes an object satisfying constant buffer sequence requirements, and ec denotes an object of type error_code.

Table 7.35. Buffer-oriented synchronous random-access write device requirements

operation

type

semantics, pre/post-conditions

a.write_some_at(o, cb);

size_t

Equivalent to:

error_code ec;
size_t s = a.write_some(o, cb, ec);
if (ec) throw system_error(ec);
return s;

a.write_some_at(o, cb, ec);

size_t

Writes one or more bytes of data to the device a at offset o.

The constant buffer sequence cb specifies memory where the data to be written is located. The write_some_at operation shall always write a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes written and sets ec such that !ec is true. If an error occurred, returns 0 and sets ec such that !!ec is true.

If the total size of all buffers in the sequence cb is 0, the function shall return 0 immediately.

Buffer-oriented synchronous read stream requirements

In the table below, a denotes a synchronous read stream object, mb denotes an object satisfying mutable buffer sequence requirements, and ec denotes an object of type error_code.

Table 7.36. Buffer-oriented synchronous read stream requirements

operation

type

semantics, pre/post-conditions

a.read_some(mb);

size_t

Equivalent to:

error_code ec;
size_t s = a.read_some(mb, ec);
if (ec) throw system_error(ec);
return s;

a.read_some(mb, ec);

size_t

Reads one or more bytes of data from the stream a.

The mutable buffer sequence mb specifies memory where the data should be placed. The read_some operation shall always fill a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes read and sets ec such that !ec is true. If an error occurred, returns 0 and sets ec such that !!ec is true.

If the total size of all buffers in the sequence mb is 0, the function shall return 0 immediately.

Buffer-oriented synchronous write stream requirements

In the table below, a denotes a synchronous write stream object, cb denotes an object satisfying constant buffer sequence requirements, and ec denotes an object of type error_code.

Table 7.37. Buffer-oriented synchronous write stream requirements

operation

type

semantics, pre/post-conditions

a.write_some(cb);

size_t

Equivalent to:

error_code ec;
size_t s = a.write_some(cb, ec);
if (ec) throw system_error(ec);
return s;

a.write_some(cb, ec);

size_t

Writes one or more bytes of data to the stream a.

The constant buffer sequence cb specifies memory where the data to be written is located. The write_some operation shall always write a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes written and sets ec such that !ec is true. If an error occurred, returns 0 and sets ec such that !!ec is true.

If the total size of all buffers in the sequence cb is 0, the function shall return 0 immediately.

Time traits requirements

In the table below, X denotes a time traits class for time type Time, t, t1, and t2 denote values of type Time, and d denotes a value of type X::duration_type.

Table 7.38. TimeTraits requirements

expression	return type	assertion/note pre/post-condition
`X::time_type`	`Time`	Represents an absolute time. Must support default construction, and meet the requirements for `CopyConstructible` and `Assignable`.
`X::duration_type`		Represents the difference between two absolute times. Must support default construction, and meet the requirements for `CopyConstructible` and `Assignable`. A duration can be positive, negative, or zero.
`X::now();`	`time_type`	Returns the current time.
`X::add(t, d);`	`time_type`	Returns a new absolute time resulting from adding the duration `d` to the absolute time `t`.
`X::subtract(t1, t2);`	`duration_type`	Returns the duration resulting from subtracting `t2` from `t1`.
`X::less_than(t1, t2);`	`bool`	Returns whether `t1` is to be treated as less than `t2`.
`X::to_posix_duration(d);`	`date_time::time_duration_type`	Returns the `date_time::time_duration_type` value that most closely represents the duration `d`.

Timer service requirements

A timer service must meet the requirements for an I/O object service, as well as the additional requirements listed below.

In the table below, X denotes a timer service class for time type Time and traits type TimeTraits, a denotes a value of type X, b denotes a value of type X::implementation_type, t denotes a value of type Time, d denotes a value of type TimeTraits::duration_type, e denotes a value of type error_code, and h denotes a value meeting WaitHandler requirements.

Table 7.39. TimerService requirements

expression	return type	assertion/note pre/post-condition
`a.destroy(b);`		From IoObjectService requirements. Implicitly cancels asynchronous wait operations, as if by calling `a.cancel(b, e)`.
a.cancel(b, e);	`size_t`	Causes any outstanding asynchronous wait operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code `error::operation_aborted`. Sets `e` to indicate success or failure. Returns the number of operations that were cancelled.
`a.expires_at(b);`	`Time`
a.expires_at(b, t, e);	`size_t`	Implicitly cancels asynchronous wait operations, as if by calling `a.cancel(b, e)`. Returns the number of operations that were cancelled. post: `a.expires_at(b) == t`.
`a.expires_from_now(b);`	`TimeTraits::duration_type`	Returns a value equivalent to `TimeTraits::subtract(a.expires_at(b), TimeTraits::now())`.
a.expires_from_now(b, d, e);	`size_t`	Equivalent to `a.expires_at(b, TimeTraits::add(TimeTraits::now(), d), e)`.
a.wait(b, e);	`error_code`	Sets `e` to indicate success or failure. Returns `e`. post: `!!e \|\| !TimeTraits::lt(TimeTraits::now(), a.expires_at(b))`.
a.async_wait(b, h);		Initiates an asynchronous wait operation that is performed via the `io_service` object `a.get_io_service()` and behaves according to asynchronous operation requirements. The handler shall be posted for execution only if the condition `!!ec \|\| !TimeTraits::lt(TimeTraits::now(), a.expires_at(b))` holds, where `ec` is the error code to be passed to the handler.

Waitable timer service requirements

A waitable timer service must meet the requirements for an I/O object service, as well as the additional requirements listed below.

In the table below, X denotes a waitable timer service class for clock type Clock, where Clock meets the C++11 clock type requirements, a denotes a value of type X, b denotes a value of type X::implementation_type, t denotes a value of type Clock::time_point, d denotes a value of type Clock::duration, e denotes a value of type error_code, and h denotes a value meeting WaitHandler requirements.

Table 7.40. WaitableTimerService requirements

expression	return type	assertion/note pre/post-condition
`a.destroy(b);`		From IoObjectService requirements. Implicitly cancels asynchronous wait operations, as if by calling `a.cancel(b, e)`.
a.cancel(b, e);	`size_t`	Causes any outstanding asynchronous wait operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code `error::operation_aborted`. Sets `e` to indicate success or failure. Returns the number of operations that were cancelled.
`a.expires_at(b);`	`Clock::time_point`
a.expires_at(b, t, e);	`size_t`	Implicitly cancels asynchronous wait operations, as if by calling `a.cancel(b, e)`. Returns the number of operations that were cancelled. post: `a.expires_at(b) == t`.
`a.expires_from_now(b);`	`Clock::duration`	Returns a value equivalent to `a.expires_at(b) - Clock::now()`.
a.expires_from_now(b, d, e);	`size_t`	Equivalent to `a.expires_at(b, Clock::now() + d, e)`.
a.wait(b, e);	`error_code`	Sets `e` to indicate success or failure. Returns `e`. post: `!!e \|\| !(Clock::now() < a.expires_at(b))`.
a.async_wait(b, h);		Initiates an asynchronous wait operation that is performed via the `io_service` object `a.get_io_service()` and behaves according to asynchronous operation requirements. The handler shall be posted for execution only if the condition `!!ec \|\| !(Clock::now() < a.expires_at(b))` holds, where `ec` is the error code to be passed to the handler.

Wait handler requirements

A wait handler must meet the requirements for a handler. A value h of a wait handler class should work correctly in the expression h(ec), where ec is an lvalue of type const error_code.

Examples

A free function as a wait handler:

void wait_handler(
    const boost::system::error_code& ec)
{
  ...
}

A wait handler function object:

struct wait_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a wait handler using bind():

void my_class::wait_handler(
    const boost::system::error_code& ec)
{
  ...
}
...
socket.async_wait(...,
    boost::bind(&my_class::wait_handler,
      this, boost::asio::placeholders::error));

Wait traits requirements

In the table below, X denotes a wait traits class for clock type Clock, where Clock meets the C++11 type requirements for a clock, and d denotes a value of type Clock::duration.

Table 7.41. WaitTraits requirements

expression	return type	assertion/note pre/post-condition
`X::to_wait_duration(d);`	`Clock::duration`	Returns the maximum duration to be used for an individual, implementation-defined wait operation.

Write handler requirements

A write handler must meet the requirements for a handler. A value h of a write handler class should work correctly in the expression h(ec, s), where ec is an lvalue of type const error_code and s is an lvalue of type const size_t.

Examples

A free function as a write handler:

void write_handler(
    const boost::system::error_code& ec,
    std::size_t bytes_transferred)
{
  ...
}

A write handler function object:

struct write_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec,
      std::size_t bytes_transferred)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a write handler using bind():

void my_class::write_handler(
    const boost::system::error_code& ec,
    std::size_t bytes_transferred)
{
  ...
}
...
socket.async_write(...,
    boost::bind(&my_class::write_handler,
      this, boost::asio::placeholders::error,
      boost::asio::placeholders::bytes_transferred));

add_service

template<
    typename Service>
void add_service(
    io_service & ios,
    Service * svc);

This function is used to add a service to the io_service.

Parameters

ios

The io_service object that owns the service.

svc

The service object. On success, ownership of the service object is transferred to the io_service. When the io_service object is destroyed, it will destroy the service object by performing:

delete static_cast<io_service::service*>(svc)

Exceptions

boost::asio::service_already_exists: Thrown if a service of the given type is already present in the io_service.
boost::asio::invalid_service_owner: Thrown if the service's owning io_service is not the io_service object specified by the ios parameter.

Requirements

Header: boost/asio/io_service.hpp

Convenience header: boost/asio.hpp

asio_handler_allocate

Default allocation function for handlers.

void * asio_handler_allocate(
    std::size_t size,
    ... );

Asynchronous operations may need to allocate temporary objects. Since asynchronous operations have a handler function object, these temporary objects can be said to be associated with the handler.

Implement asio_handler_allocate and asio_handler_deallocate for your own handlers to provide custom allocation for these temporary objects.

The default implementation of these allocation hooks uses operator new and operator delete.

Remarks

All temporary objects associated with a handler will be deallocated before the upcall to the handler is performed. This allows the same memory to be reused for a subsequent asynchronous operation initiated by the handler.

Example

class my_handler;

void* asio_handler_allocate(std::size_t size, my_handler* context)
{
  return ::operator new(size);
}

void asio_handler_deallocate(void* pointer, std::size_t size,
    my_handler* context)
{
  ::operator delete(pointer);
}

Requirements

Header: boost/asio/handler_alloc_hook.hpp

Convenience header: boost/asio.hpp

asio_handler_deallocate

Default deallocation function for handlers.

void asio_handler_deallocate(
    void * pointer,
    std::size_t size,
    ... );

Implement asio_handler_allocate and asio_handler_deallocate for your own handlers to provide custom allocation for the associated temporary objects.

The default implementation of these allocation hooks uses operator new and operator delete.

Requirements

Header: boost/asio/handler_alloc_hook.hpp

Convenience header: boost/asio.hpp

asio_handler_invoke

asio_handler_invoke (1 of 2 overloads)
asio_handler_invoke (2 of 2 overloads)

Default invoke function for handlers.

template<
    typename Function>
void asio_handler_invoke(
    Function & function,
    ... );
  » more...

template<
    typename Function>
void asio_handler_invoke(
    const Function & function,
    ... );
  » more...

Completion handlers for asynchronous operations are invoked by the io_service associated with the corresponding object (e.g. a socket or deadline_timer). Certain guarantees are made on when the handler may be invoked, in particular that a handler can only be invoked from a thread that is currently calling run() on the corresponding io_service object. Handlers may subsequently be invoked through other objects (such as io_service::strand objects) that provide additional guarantees.

When asynchronous operations are composed from other asynchronous operations, all intermediate handlers should be invoked using the same method as the final handler. This is required to ensure that user-defined objects are not accessed in a way that may violate the guarantees. This hooking function ensures that the invoked method used for the final handler is accessible at each intermediate step.

Implement asio_handler_invoke for your own handlers to specify a custom invocation strategy.

This default implementation invokes the function object like so:

function();

If necessary, the default implementation makes a copy of the function object so that the non-const operator() can be used.

Example

class my_handler;

template <typename Function>
void asio_handler_invoke(Function function, my_handler* context)
{
  context->strand_.dispatch(function);
}

Requirements

Header: boost/asio/handler_invoke_hook.hpp

Convenience header: boost/asio.hpp

asio_handler_invoke (1 of 2 overloads)

Default handler invocation hook used for non-const function objects.

template<
    typename Function>
void asio_handler_invoke(
    Function & function,
    ... );

asio_handler_invoke (2 of 2 overloads)

Default handler invocation hook used for const function objects.

template<
    typename Function>
void asio_handler_invoke(
    const Function & function,
    ... );

asio_handler_is_continuation

Default continuation function for handlers.

bool asio_handler_is_continuation(
    ... );

Asynchronous operations may represent a continuation of the asynchronous control flow associated with the current handler. The implementation can use this knowledge to optimise scheduling of the handler.

Implement asio_handler_is_continuation for your own handlers to indicate when a handler represents a continuation.

The default implementation of the continuation hook returns false.

Example

class my_handler;

bool asio_handler_is_continuation(my_handler* context)
{
  return true;
}

Requirements

Header: boost/asio/handler_continuation_hook.hpp

Convenience header: boost/asio.hpp

async_connect

async_connect (1 of 4 overloads)
async_connect (2 of 4 overloads)
async_connect (3 of 4 overloads)
async_connect (4 of 4 overloads)

Asynchronously establishes a socket connection by trying each endpoint in a sequence.

template<
    typename Protocol,
    typename SocketService,
    typename Iterator,
    typename ComposedConnectHandler>
void-or-deduced async_connect(
    basic_socket< Protocol, SocketService > & s,
    Iterator begin,
    ComposedConnectHandler handler);
  » more...

template<
    typename Protocol,
    typename SocketService,
    typename Iterator,
    typename ComposedConnectHandler>
void-or-deduced async_connect(
    basic_socket< Protocol, SocketService > & s,
    Iterator begin,
    Iterator end,
    ComposedConnectHandler handler);
  » more...

template<
    typename Protocol,
    typename SocketService,
    typename Iterator,
    typename ConnectCondition,
    typename ComposedConnectHandler>
void-or-deduced async_connect(
    basic_socket< Protocol, SocketService > & s,
    Iterator begin,
    ConnectCondition connect_condition,
    ComposedConnectHandler handler);
  » more...

template<
    typename Protocol,
    typename SocketService,
    typename Iterator,
    typename ConnectCondition,
    typename ComposedConnectHandler>
void-or-deduced async_connect(
    basic_socket< Protocol, SocketService > & s,
    Iterator begin,
    Iterator end,
    ConnectCondition connect_condition,
    ComposedConnectHandler handler);
  » more...

Requirements

Header: boost/asio/connect.hpp

Convenience header: boost/asio.hpp

async_connect (1 of 4 overloads)

Asynchronously establishes a socket connection by trying each endpoint in a sequence.

template<
    typename Protocol,
    typename SocketService,
    typename Iterator,
    typename ComposedConnectHandler>
void-or-deduced async_connect(
    basic_socket< Protocol, SocketService > & s,
    Iterator begin,
    ComposedConnectHandler handler);

This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's async_connect member function, once for each endpoint in the sequence, until a connection is successfully established.

Parameters

s

The socket to be connected. If the socket is already open, it will be closed.

begin

An iterator pointing to the start of a sequence of endpoints.

handler

The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation. if the sequence is empty, set to
  // boost::asio::error::not_found. Otherwise, contains the
  // error from the last connection attempt.
  const boost::system::error_code& error,

  // On success, an iterator denoting the successfully
  // connected endpoint. Otherwise, the end iterator.
  Iterator iterator
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Remarks

This overload assumes that a default constructed object of type Iterator represents the end of the sequence. This is a valid assumption for iterator types such as boost::asio::ip::tcp::resolver::iterator.

Example

tcp::resolver r(io_service);
tcp::resolver::query q("host", "service");
tcp::socket s(io_service);

// ...

r.async_resolve(q, resolve_handler);

// ...

void resolve_handler(
    const boost::system::error_code& ec,
    tcp::resolver::iterator i)
{
  if (!ec)
  {
    boost::asio::async_connect(s, i, connect_handler);
  }
}

// ...

void connect_handler(
    const boost::system::error_code& ec,
    tcp::resolver::iterator i)
{
  // ...
}

async_connect (2 of 4 overloads)

Asynchronously establishes a socket connection by trying each endpoint in a sequence.

template<
    typename Protocol,
    typename SocketService,
    typename Iterator,
    typename ComposedConnectHandler>
void-or-deduced async_connect(
    basic_socket< Protocol, SocketService > & s,
    Iterator begin,
    Iterator end,
    ComposedConnectHandler handler);

This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's async_connect member function, once for each endpoint in the sequence, until a connection is successfully established.

Parameters

s

The socket to be connected. If the socket is already open, it will be closed.

begin

An iterator pointing to the start of a sequence of endpoints.

end

An iterator pointing to the end of a sequence of endpoints.

handler

The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation. if the sequence is empty, set to
  // boost::asio::error::not_found. Otherwise, contains the
  // error from the last connection attempt.
  const boost::system::error_code& error,

  // On success, an iterator denoting the successfully
  // connected endpoint. Otherwise, the end iterator.
  Iterator iterator
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Example

tcp::resolver r(io_service);
tcp::resolver::query q("host", "service");
tcp::socket s(io_service);

// ...

r.async_resolve(q, resolve_handler);

// ...

void resolve_handler(
    const boost::system::error_code& ec,
    tcp::resolver::iterator i)
{
  if (!ec)
  {
    tcp::resolver::iterator end;
    boost::asio::async_connect(s, i, end, connect_handler);
  }
}

// ...

void connect_handler(
    const boost::system::error_code& ec,
    tcp::resolver::iterator i)
{
  // ...
}

async_connect (3 of 4 overloads)

Asynchronously establishes a socket connection by trying each endpoint in a sequence.

template<
    typename Protocol,
    typename SocketService,
    typename Iterator,
    typename ConnectCondition,
    typename ComposedConnectHandler>
void-or-deduced async_connect(
    basic_socket< Protocol, SocketService > & s,
    Iterator begin,
    ConnectCondition connect_condition,
    ComposedConnectHandler handler);

This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's async_connect member function, once for each endpoint in the sequence, until a connection is successfully established.

Parameters

s

The socket to be connected. If the socket is already open, it will be closed.

begin

An iterator pointing to the start of a sequence of endpoints.

connect_condition

A function object that is called prior to each connection attempt. The signature of the function object must be:

Iterator connect_condition(
    const boost::system::error_code& ec,
    Iterator next);

The ec parameter contains the result from the most recent connect operation. Before the first connection attempt, ec is always set to indicate success. The next parameter is an iterator pointing to the next endpoint to be tried. The function object should return the next iterator, but is permitted to return a different iterator so that endpoints may be skipped. The implementation guarantees that the function object will never be called with the end iterator.

handler

The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation. if the sequence is empty, set to
  // boost::asio::error::not_found. Otherwise, contains the
  // error from the last connection attempt.
  const boost::system::error_code& error,

  // On success, an iterator denoting the successfully
  // connected endpoint. Otherwise, the end iterator.
  Iterator iterator
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Remarks

This overload assumes that a default constructed object of type Iterator represents the end of the sequence. This is a valid assumption for iterator types such as boost::asio::ip::tcp::resolver::iterator.

Example

The following connect condition function object can be used to output information about the individual connection attempts:

struct my_connect_condition
{
  template <typename Iterator>
  Iterator operator()(
      const boost::system::error_code& ec,
      Iterator next)
  {
    if (ec) std::cout << "Error: " << ec.message() << std::endl;
    std::cout << "Trying: " << next->endpoint() << std::endl;
    return next;
  }
};

It would be used with the boost::asio::connect function as follows:

tcp::resolver r(io_service);
tcp::resolver::query q("host", "service");
tcp::socket s(io_service);

// ...

r.async_resolve(q, resolve_handler);

// ...

void resolve_handler(
    const boost::system::error_code& ec,
    tcp::resolver::iterator i)
{
  if (!ec)
  {
    boost::asio::async_connect(s, i,
        my_connect_condition(),
        connect_handler);
  }
}

// ...

void connect_handler(
    const boost::system::error_code& ec,
    tcp::resolver::iterator i)
{
  if (ec)
  {
    // An error occurred.
  }
  else
  {
    std::cout << "Connected to: " << i->endpoint() << std::endl;
  }
}

async_connect (4 of 4 overloads)

Asynchronously establishes a socket connection by trying each endpoint in a sequence.

template<
    typename Protocol,
    typename SocketService,
    typename Iterator,
    typename ConnectCondition,
    typename ComposedConnectHandler>
void-or-deduced async_connect(
    basic_socket< Protocol, SocketService > & s,
    Iterator begin,
    Iterator end,
    ConnectCondition connect_condition,
    ComposedConnectHandler handler);

This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's async_connect member function, once for each endpoint in the sequence, until a connection is successfully established.

Parameters

s

The socket to be connected. If the socket is already open, it will be closed.

begin

An iterator pointing to the start of a sequence of endpoints.

end

An iterator pointing to the end of a sequence of endpoints.

connect_condition

A function object that is called prior to each connection attempt. The signature of the function object must be:

Iterator connect_condition(
    const boost::system::error_code& ec,
    Iterator next);

The ec parameter contains the result from the most recent connect operation. Before the first connection attempt, ec is always set to indicate success. The next parameter is an iterator pointing to the next endpoint to be tried. The function object should return the next iterator, but is permitted to return a different iterator so that endpoints may be skipped. The implementation guarantees that the function object will never be called with the end iterator.

handler

The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation. if the sequence is empty, set to
  // boost::asio::error::not_found. Otherwise, contains the
  // error from the last connection attempt.
  const boost::system::error_code& error,

  // On success, an iterator denoting the successfully
  // connected endpoint. Otherwise, the end iterator.
  Iterator iterator
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Example

The following connect condition function object can be used to output information about the individual connection attempts:

struct my_connect_condition
{
  template <typename Iterator>
  Iterator operator()(
      const boost::system::error_code& ec,
      Iterator next)
  {
    if (ec) std::cout << "Error: " << ec.message() << std::endl;
    std::cout << "Trying: " << next->endpoint() << std::endl;
    return next;
  }
};

It would be used with the boost::asio::connect function as follows:

tcp::resolver r(io_service);
tcp::resolver::query q("host", "service");
tcp::socket s(io_service);

// ...

r.async_resolve(q, resolve_handler);

// ...

void resolve_handler(
    const boost::system::error_code& ec,
    tcp::resolver::iterator i)
{
  if (!ec)
  {
    tcp::resolver::iterator end;
    boost::asio::async_connect(s, i, end,
        my_connect_condition(),
        connect_handler);
  }
}

// ...

void connect_handler(
    const boost::system::error_code& ec,
    tcp::resolver::iterator i)
{
  if (ec)
  {
    // An error occurred.
  }
  else
  {
    std::cout << "Connected to: " << i->endpoint() << std::endl;
  }
}

async_read

async_read (1 of 4 overloads)
async_read (2 of 4 overloads)
async_read (3 of 4 overloads)
async_read (4 of 4 overloads)

Start an asynchronous operation to read a certain amount of data from a stream.

template<
    typename AsyncReadStream,
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_read(
    AsyncReadStream & s,
    const MutableBufferSequence & buffers,
    ReadHandler handler);
  » more...

template<
    typename AsyncReadStream,
    typename MutableBufferSequence,
    typename CompletionCondition,
    typename ReadHandler>
void-or-deduced async_read(
    AsyncReadStream & s,
    const MutableBufferSequence & buffers,
    CompletionCondition completion_condition,
    ReadHandler handler);
  » more...

template<
    typename AsyncReadStream,
    typename Allocator,
    typename ReadHandler>
void-or-deduced async_read(
    AsyncReadStream & s,
    basic_streambuf< Allocator > & b,
    ReadHandler handler);
  » more...

template<
    typename AsyncReadStream,
    typename Allocator,
    typename CompletionCondition,
    typename ReadHandler>
void-or-deduced async_read(
    AsyncReadStream & s,
    basic_streambuf< Allocator > & b,
    CompletionCondition completion_condition,
    ReadHandler handler);
  » more...

Requirements

Header: boost/asio/read.hpp

Convenience header: boost/asio.hpp

async_read (1 of 4 overloads)

Start an asynchronous operation to read a certain amount of data from a stream.

template<
    typename AsyncReadStream,
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_read(
    AsyncReadStream & s,
    const MutableBufferSequence & buffers,
    ReadHandler handler);

This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes.
An error occurred.

This operation is implemented in terms of zero or more calls to the stream's async_read_some function, and is known as a composed operation. The program must ensure that the stream performs no other read operations (such as async_read, the stream's async_read_some function, or any other composed operations that perform reads) until this operation completes.

Parameters

s

The stream from which the data is to be read. The type must support the AsyncReadStream concept.

buffers

One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the stream. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.

handler

The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  const boost::system::error_code& error, // Result of operation.

  std::size_t bytes_transferred           // Number of bytes copied into the
                                          // buffers. If an error occurred,
                                          // this will be the  number of
                                          // bytes successfully transferred
                                          // prior to the error.
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Example

To read into a single data buffer use the buffer function as follows:

boost::asio::async_read(s, boost::asio::buffer(data, size), handler);

See the buffer documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

Remarks

This overload is equivalent to calling:

boost::asio::async_read(
    s, buffers,
    boost::asio::transfer_all(),
    handler);

async_read (2 of 4 overloads)

Start an asynchronous operation to read a certain amount of data from a stream.

template<
    typename AsyncReadStream,
    typename MutableBufferSequence,
    typename CompletionCondition,
    typename ReadHandler>
void-or-deduced async_read(
    AsyncReadStream & s,
    const MutableBufferSequence & buffers,
    CompletionCondition completion_condition,
    ReadHandler handler);

This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes.
The completion_condition function object returns 0.

Parameters

s

The stream from which the data is to be read. The type must support the AsyncReadStream concept.

buffers

One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the stream. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.

completion_condition

The function object to be called to determine whether the read operation is complete. The signature of the function object must be:

std::size_t completion_condition(
  // Result of latest async_read_some operation.
  const boost::system::error_code& error,

  // Number of bytes transferred so far.
  std::size_t bytes_transferred
);

A return value of 0 indicates that the read operation is complete. A non-zero return value indicates the maximum number of bytes to be read on the next call to the stream's async_read_some function.

handler

The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  const boost::system::error_code& error, // Result of operation.

  std::size_t bytes_transferred           // Number of bytes copied into the
                                          // buffers. If an error occurred,
                                          // this will be the  number of
                                          // bytes successfully transferred
                                          // prior to the error.
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Example

To read into a single data buffer use the buffer function as follows:

boost::asio::async_read(s,
    boost::asio::buffer(data, size),
    boost::asio::transfer_at_least(32),
    handler);

See the buffer documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

async_read (3 of 4 overloads)

Start an asynchronous operation to read a certain amount of data from a stream.

template<
    typename AsyncReadStream,
    typename Allocator,
    typename ReadHandler>
void-or-deduced async_read(
    AsyncReadStream & s,
    basic_streambuf< Allocator > & b,
    ReadHandler handler);

This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The supplied buffer is full (that is, it has reached maximum size).
An error occurred.

This operation is implemented in terms of zero or more calls to the stream's async_read_some function, and is known as a composed operation. The program must ensure that the stream performs no other read operations (such as async_read, the stream's async_read_some function, or any other composed operations that perform reads) until this operation completes.

Parameters

s

The stream from which the data is to be read. The type must support the AsyncReadStream concept.

b

A basic_streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.

handler

The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  const boost::system::error_code& error, // Result of operation.

  std::size_t bytes_transferred           // Number of bytes copied into the
                                          // buffers. If an error occurred,
                                          // this will be the  number of
                                          // bytes successfully transferred
                                          // prior to the error.
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Remarks

This overload is equivalent to calling:

boost::asio::async_read(
    s, b,
    boost::asio::transfer_all(),
    handler);

async_read (4 of 4 overloads)

Start an asynchronous operation to read a certain amount of data from a stream.

template<
    typename AsyncReadStream,
    typename Allocator,
    typename CompletionCondition,
    typename ReadHandler>
void-or-deduced async_read(
    AsyncReadStream & s,
    basic_streambuf< Allocator > & b,
    CompletionCondition completion_condition,
    ReadHandler handler);

This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The supplied buffer is full (that is, it has reached maximum size).
The completion_condition function object returns 0.

This operation is implemented in terms of zero or more calls to the stream's async_read_some function, and is known as a composed operation. The program must ensure that the stream performs no other read operations (such as async_read, the stream's async_read_some function, or any other composed operations that perform reads) until this operation completes.

Parameters

s

The stream from which the data is to be read. The type must support the AsyncReadStream concept.

b

A basic_streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.

completion_condition

The function object to be called to determine whether the read operation is complete. The signature of the function object must be:

std::size_t completion_condition(
  // Result of latest async_read_some operation.
  const boost::system::error_code& error,

  // Number of bytes transferred so far.
  std::size_t bytes_transferred
);

A return value of 0 indicates that the read operation is complete. A non-zero return value indicates the maximum number of bytes to be read on the next call to the stream's async_read_some function.

handler

The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  const boost::system::error_code& error, // Result of operation.

  std::size_t bytes_transferred           // Number of bytes copied into the
                                          // buffers. If an error occurred,
                                          // this will be the  number of
                                          // bytes successfully transferred
                                          // prior to the error.
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

async_read_at

async_read_at (1 of 4 overloads)
async_read_at (2 of 4 overloads)
async_read_at (3 of 4 overloads)
async_read_at (4 of 4 overloads)

Start an asynchronous operation to read a certain amount of data at the specified offset.

template<
    typename AsyncRandomAccessReadDevice,
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_read_at(
    AsyncRandomAccessReadDevice & d,
    uint64_t offset,
    const MutableBufferSequence & buffers,
    ReadHandler handler);
  » more...

template<
    typename AsyncRandomAccessReadDevice,
    typename MutableBufferSequence,
    typename CompletionCondition,
    typename ReadHandler>
void-or-deduced async_read_at(
    AsyncRandomAccessReadDevice & d,
    uint64_t offset,
    const MutableBufferSequence & buffers,
    CompletionCondition completion_condition,
    ReadHandler handler);
  » more...

template<
    typename AsyncRandomAccessReadDevice,
    typename Allocator,
    typename ReadHandler>
void-or-deduced async_read_at(
    AsyncRandomAccessReadDevice & d,
    uint64_t offset,
    basic_streambuf< Allocator > & b,
    ReadHandler handler);
  » more...

template<
    typename AsyncRandomAccessReadDevice,
    typename Allocator,
    typename CompletionCondition,
    typename ReadHandler>
void-or-deduced async_read_at(
    AsyncRandomAccessReadDevice & d,
    uint64_t offset,
    basic_streambuf< Allocator > & b,
    CompletionCondition completion_condition,
    ReadHandler handler);
  » more...

Requirements

Header: boost/asio/read_at.hpp

Convenience header: boost/asio.hpp

async_read_at (1 of 4 overloads)

Start an asynchronous operation to read a certain amount of data at the specified offset.

template<
    typename AsyncRandomAccessReadDevice,
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_read_at(
    AsyncRandomAccessReadDevice & d,
    uint64_t offset,
    const MutableBufferSequence & buffers,
    ReadHandler handler);

This function is used to asynchronously read a certain number of bytes of data from a random access device at the specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes.
An error occurred.

This operation is implemented in terms of zero or more calls to the device's async_read_some_at function.

Parameters

d

The device from which the data is to be read. The type must support the AsyncRandomAccessReadDevice concept.

offset

The offset at which the data will be read.

buffers

One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the device. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.

handler

The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation.
  const boost::system::error_code& error,

  // Number of bytes copied into the buffers. If an error
  // occurred, this will be the number of bytes successfully
  // transferred prior to the error.
  std::size_t bytes_transferred
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Example

To read into a single data buffer use the buffer function as follows:

boost::asio::async_read_at(d, 42, boost::asio::buffer(data, size), handler);

See the buffer documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

Remarks

This overload is equivalent to calling:

boost::asio::async_read_at(
    d, 42, buffers,
    boost::asio::transfer_all(),
    handler);

async_read_at (2 of 4 overloads)

Start an asynchronous operation to read a certain amount of data at the specified offset.

template<
    typename AsyncRandomAccessReadDevice,
    typename MutableBufferSequence,
    typename CompletionCondition,
    typename ReadHandler>
void-or-deduced async_read_at(
    AsyncRandomAccessReadDevice & d,
    uint64_t offset,
    const MutableBufferSequence & buffers,
    CompletionCondition completion_condition,
    ReadHandler handler);

This function is used to asynchronously read a certain number of bytes of data from a random access device at the specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes.
The completion_condition function object returns 0.

Parameters

d

The device from which the data is to be read. The type must support the AsyncRandomAccessReadDevice concept.

offset

The offset at which the data will be read.

buffers

One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the device. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.

completion_condition

The function object to be called to determine whether the read operation is complete. The signature of the function object must be:

std::size_t completion_condition(
  // Result of latest async_read_some_at operation.
  const boost::system::error_code& error,

  // Number of bytes transferred so far.
  std::size_t bytes_transferred
);

A return value of 0 indicates that the read operation is complete. A non-zero return value indicates the maximum number of bytes to be read on the next call to the device's async_read_some_at function.

handler

The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation.
  const boost::system::error_code& error,

  // Number of bytes copied into the buffers. If an error
  // occurred, this will be the number of bytes successfully
  // transferred prior to the error.
  std::size_t bytes_transferred
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Example

To read into a single data buffer use the buffer function as follows:

boost::asio::async_read_at(d, 42,
    boost::asio::buffer(data, size),
    boost::asio::transfer_at_least(32),
    handler);

See the buffer documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

async_read_at (3 of 4 overloads)

Start an asynchronous operation to read a certain amount of data at the specified offset.

template<
    typename AsyncRandomAccessReadDevice,
    typename Allocator,
    typename ReadHandler>
void-or-deduced async_read_at(
    AsyncRandomAccessReadDevice & d,
    uint64_t offset,
    basic_streambuf< Allocator > & b,
    ReadHandler handler);

This function is used to asynchronously read a certain number of bytes of data from a random access device at the specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

An error occurred.

This operation is implemented in terms of zero or more calls to the device's async_read_some_at function.

Parameters

d

The device from which the data is to be read. The type must support the AsyncRandomAccessReadDevice concept.

offset

The offset at which the data will be read.

b

A basic_streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.

handler

The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation.
  const boost::system::error_code& error,

  // Number of bytes copied into the buffers. If an error
  // occurred, this will be the number of bytes successfully
  // transferred prior to the error.
  std::size_t bytes_transferred
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Remarks

This overload is equivalent to calling:

boost::asio::async_read_at(
    d, 42, b,
    boost::asio::transfer_all(),
    handler);

async_read_at (4 of 4 overloads)

Start an asynchronous operation to read a certain amount of data at the specified offset.

template<
    typename AsyncRandomAccessReadDevice,
    typename Allocator,
    typename CompletionCondition,
    typename ReadHandler>
void-or-deduced async_read_at(
    AsyncRandomAccessReadDevice & d,
    uint64_t offset,
    basic_streambuf< Allocator > & b,
    CompletionCondition completion_condition,
    ReadHandler handler);

This function is used to asynchronously read a certain number of bytes of data from a random access device at the specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The completion_condition function object returns 0.

This operation is implemented in terms of zero or more calls to the device's async_read_some_at function.

Parameters

d

The device from which the data is to be read. The type must support the AsyncRandomAccessReadDevice concept.

offset

The offset at which the data will be read.

b

A basic_streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.

completion_condition

The function object to be called to determine whether the read operation is complete. The signature of the function object must be:

std::size_t completion_condition(
  // Result of latest async_read_some_at operation.
  const boost::system::error_code& error,

  // Number of bytes transferred so far.
  std::size_t bytes_transferred
);

A return value of 0 indicates that the read operation is complete. A non-zero return value indicates the maximum number of bytes to be read on the next call to the device's async_read_some_at function.

handler

The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation.
  const boost::system::error_code& error,

  // Number of bytes copied into the buffers. If an error
  // occurred, this will be the number of bytes successfully
  // transferred prior to the error.
  std::size_t bytes_transferred
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

async_read_until

async_read_until (1 of 4 overloads)
async_read_until (2 of 4 overloads)
async_read_until (3 of 4 overloads)
async_read_until (4 of 4 overloads)

Start an asynchronous operation to read data into a streambuf until it contains a delimiter, matches a regular expression, or a function object indicates a match.

template<
    typename AsyncReadStream,
    typename Allocator,
    typename ReadHandler>
void-or-deduced async_read_until(
    AsyncReadStream & s,
    boost::asio::basic_streambuf< Allocator > & b,
    char delim,
    ReadHandler handler);
  » more...

template<
    typename AsyncReadStream,
    typename Allocator,
    typename ReadHandler>
void-or-deduced async_read_until(
    AsyncReadStream & s,
    boost::asio::basic_streambuf< Allocator > & b,
    const std::string & delim,
    ReadHandler handler);
  » more...

template<
    typename AsyncReadStream,
    typename Allocator,
    typename ReadHandler>
void-or-deduced async_read_until(
    AsyncReadStream & s,
    boost::asio::basic_streambuf< Allocator > & b,
    const boost::regex & expr,
    ReadHandler handler);
  » more...

template<
    typename AsyncReadStream,
    typename Allocator,
    typename MatchCondition,
    typename ReadHandler>
void-or-deduced async_read_until(
    AsyncReadStream & s,
    boost::asio::basic_streambuf< Allocator > & b,
    MatchCondition match_condition,
    ReadHandler handler,
    typename enable_if< is_match_condition< MatchCondition >::value >::type *  = 0);
  » more...

Requirements

Header: boost/asio/read_until.hpp

Convenience header: boost/asio.hpp

async_read_until (1 of 4 overloads)

Start an asynchronous operation to read data into a streambuf until it contains a specified delimiter.

template<
    typename AsyncReadStream,
    typename Allocator,
    typename ReadHandler>
void-or-deduced async_read_until(
    AsyncReadStream & s,
    boost::asio::basic_streambuf< Allocator > & b,
    char delim,
    ReadHandler handler);

This function is used to asynchronously read data into the specified streambuf until the streambuf's get area contains the specified delimiter. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The get area of the streambuf contains the specified delimiter.
An error occurred.

This operation is implemented in terms of zero or more calls to the stream's async_read_some function, and is known as a composed operation. If the streambuf's get area already contains the delimiter, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async_read, async_read_until, the stream's async_read_some function, or any other composed operations that perform reads) until this operation completes.

Parameters

s

The stream from which the data is to be read. The type must support the AsyncReadStream concept.

b

A streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.

delim

The delimiter character.

handler

The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation.
  const boost::system::error_code& error,

  // The number of bytes in the streambuf's get
  // area up to and including the delimiter.
  // 0 if an error occurred.
  std::size_t bytes_transferred
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Remarks

After a successful async_read_until operation, the streambuf may contain additional data beyond the delimiter. An application will typically leave that data in the streambuf for a subsequent async_read_until operation to examine.

Example

To asynchronously read data into a streambuf until a newline is encountered:

boost::asio::streambuf b;
...
void handler(const boost::system::error_code& e, std::size_t size)
{
  if (!e)
  {
    std::istream is(&b);
    std::string line;
    std::getline(is, line);
    ...
  }
}
...
boost::asio::async_read_until(s, b, '\n', handler);

After the async_read_until operation completes successfully, the buffer b contains the delimiter:

{ 'a', 'b', ..., 'c', '\n', 'd', 'e', ... }

The call to std::getline then extracts the data up to and including the delimiter, so that the string line contains:

{ 'a', 'b', ..., 'c', '\n' }

The remaining data is left in the buffer b as follows:

{ 'd', 'e', ... }

This data may be the start of a new line, to be extracted by a subsequent async_read_until operation.

async_read_until (2 of 4 overloads)

Start an asynchronous operation to read data into a streambuf until it contains a specified delimiter.

template<
    typename AsyncReadStream,
    typename Allocator,
    typename ReadHandler>
void-or-deduced async_read_until(
    AsyncReadStream & s,
    boost::asio::basic_streambuf< Allocator > & b,
    const std::string & delim,
    ReadHandler handler);

This function is used to asynchronously read data into the specified streambuf until the streambuf's get area contains the specified delimiter. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The get area of the streambuf contains the specified delimiter.
An error occurred.

This operation is implemented in terms of zero or more calls to the stream's async_read_some function, and is known as a composed operation. If the streambuf's get area already contains the delimiter, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async_read, async_read_until, the stream's async_read_some function, or any other composed operations that perform reads) until this operation completes.

Parameters

s

The stream from which the data is to be read. The type must support the AsyncReadStream concept.

b

A streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.

delim

The delimiter string.

handler

The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation.
  const boost::system::error_code& error,

  // The number of bytes in the streambuf's get
  // area up to and including the delimiter.
  // 0 if an error occurred.
  std::size_t bytes_transferred
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Remarks

After a successful async_read_until operation, the streambuf may contain additional data beyond the delimiter. An application will typically leave that data in the streambuf for a subsequent async_read_until operation to examine.

Example

To asynchronously read data into a streambuf until a newline is encountered:

boost::asio::streambuf b;
...
void handler(const boost::system::error_code& e, std::size_t size)
{
  if (!e)
  {
    std::istream is(&b);
    std::string line;
    std::getline(is, line);
    ...
  }
}
...
boost::asio::async_read_until(s, b, "\r\n", handler);

After the async_read_until operation completes successfully, the buffer b contains the delimiter:

{ 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... }

The call to std::getline then extracts the data up to and including the delimiter, so that the string line contains:

{ 'a', 'b', ..., 'c', '\r', '\n' }

The remaining data is left in the buffer b as follows:

{ 'd', 'e', ... }

This data may be the start of a new line, to be extracted by a subsequent async_read_until operation.

async_read_until (3 of 4 overloads)

Start an asynchronous operation to read data into a streambuf until some part of its data matches a regular expression.

template<
    typename AsyncReadStream,
    typename Allocator,
    typename ReadHandler>
void-or-deduced async_read_until(
    AsyncReadStream & s,
    boost::asio::basic_streambuf< Allocator > & b,
    const boost::regex & expr,
    ReadHandler handler);

This function is used to asynchronously read data into the specified streambuf until the streambuf's get area contains some data that matches a regular expression. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

A substring of the streambuf's get area matches the regular expression.
An error occurred.

This operation is implemented in terms of zero or more calls to the stream's async_read_some function, and is known as a composed operation. If the streambuf's get area already contains data that matches the regular expression, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async_read, async_read_until, the stream's async_read_some function, or any other composed operations that perform reads) until this operation completes.

Parameters

s

The stream from which the data is to be read. The type must support the AsyncReadStream concept.

b

A streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.

expr

The regular expression.

handler

The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation.
  const boost::system::error_code& error,

  // The number of bytes in the streambuf's get
  // area up to and including the substring
  // that matches the regular. expression.
  // 0 if an error occurred.
  std::size_t bytes_transferred
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Remarks

After a successful async_read_until operation, the streambuf may contain additional data beyond that which matched the regular expression. An application will typically leave that data in the streambuf for a subsequent async_read_until operation to examine.

Example

To asynchronously read data into a streambuf until a CR-LF sequence is encountered:

boost::asio::streambuf b;
...
void handler(const boost::system::error_code& e, std::size_t size)
{
  if (!e)
  {
    std::istream is(&b);
    std::string line;
    std::getline(is, line);
    ...
  }
}
...
boost::asio::async_read_until(s, b, boost::regex("\r\n"), handler);

After the async_read_until operation completes successfully, the buffer b contains the data which matched the regular expression:

{ 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... }

The call to std::getline then extracts the data up to and including the match, so that the string line contains:

{ 'a', 'b', ..., 'c', '\r', '\n' }

The remaining data is left in the buffer b as follows:

{ 'd', 'e', ... }

This data may be the start of a new line, to be extracted by a subsequent async_read_until operation.

async_read_until (4 of 4 overloads)

Start an asynchronous operation to read data into a streambuf until a function object indicates a match.

template<
    typename AsyncReadStream,
    typename Allocator,
    typename MatchCondition,
    typename ReadHandler>
void-or-deduced async_read_until(
    AsyncReadStream & s,
    boost::asio::basic_streambuf< Allocator > & b,
    MatchCondition match_condition,
    ReadHandler handler,
    typename enable_if< is_match_condition< MatchCondition >::value >::type *  = 0);

This function is used to asynchronously read data into the specified streambuf until a user-defined match condition function object, when applied to the data contained in the streambuf, indicates a successful match. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The match condition function object returns a std::pair where the second element evaluates to true.
An error occurred.

This operation is implemented in terms of zero or more calls to the stream's async_read_some function, and is known as a composed operation. If the match condition function object already indicates a match, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async_read, async_read_until, the stream's async_read_some function, or any other composed operations that perform reads) until this operation completes.

Parameters

s

The stream from which the data is to be read. The type must support the AsyncReadStream concept.

b

A streambuf object into which the data will be read.

match_condition

The function object to be called to determine whether a match exists. The signature of the function object must be:

pair<iterator, bool> match_condition(iterator begin, iterator end);

where iterator represents the type:

buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>

The iterator parameters begin and end define the range of bytes to be scanned to determine whether there is a match. The first member of the return value is an iterator marking one-past-the-end of the bytes that have been consumed by the match function. This iterator is used to calculate the begin parameter for any subsequent invocation of the match condition. The second member of the return value is true if a match has been found, false otherwise.

handler

The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation.
  const boost::system::error_code& error,

  // The number of bytes in the streambuf's get
  // area that have been fully consumed by the
  // match function. O if an error occurred.
  std::size_t bytes_transferred
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Remarks

After a successful async_read_until operation, the streambuf may contain additional data beyond that which matched the function object. An application will typically leave that data in the streambuf for a subsequent async_read_until operation to examine.

The default implementation of the is_match_condition type trait evaluates to true for function pointers and function objects with a result_type typedef. It must be specialised for other user-defined function objects.

Examples

To asynchronously read data into a streambuf until whitespace is encountered:

typedef boost::asio::buffers_iterator<
    boost::asio::streambuf::const_buffers_type> iterator;

std::pair<iterator, bool>
match_whitespace(iterator begin, iterator end)
{
  iterator i = begin;
  while (i != end)
    if (std::isspace(*i++))
      return std::make_pair(i, true);
  return std::make_pair(i, false);
}
...
void handler(const boost::system::error_code& e, std::size_t size);
...
boost::asio::streambuf b;
boost::asio::async_read_until(s, b, match_whitespace, handler);

To asynchronously read data into a streambuf until a matching character is found:

class match_char
{
public:
  explicit match_char(char c) : c_(c) {}

  template <typename Iterator>
  std::pair<Iterator, bool> operator()(
      Iterator begin, Iterator end) const
  {
    Iterator i = begin;
    while (i != end)
      if (c_ == *i++)
        return std::make_pair(i, true);
    return std::make_pair(i, false);
  }

private:
  char c_;
};

namespace asio {
  template <> struct is_match_condition<match_char>
    : public boost::true_type {};
} // namespace asio
...
void handler(const boost::system::error_code& e, std::size_t size);
...
boost::asio::streambuf b;
boost::asio::async_read_until(s, b, match_char('a'), handler);

async_result

async_result::async_result
async_result::get
async_result::type

An interface for customising the behaviour of an initiating function.

template<
    typename Handler>
class async_result

Types

Name	Description
type	The return type of the initiating function.

Member Functions

Name	Description
async_result	Construct an async result from a given handler.
get	Obtain the value to be returned from the initiating function.

This template may be specialised for user-defined handler types.

Requirements

Header: boost/asio/async_result.hpp

Convenience header: boost/asio.hpp

async_result::async_result

Construct an async result from a given handler.

async_result(
    Handler & );

When using a specalised async_result, the constructor has an opportunity to initialise some state associated with the handler, which is then returned from the initiating function.

async_result::get

Obtain the value to be returned from the initiating function.

type get();

async_result::type

The return type of the initiating function.

typedef void type;

Requirements

Header: boost/asio/async_result.hpp

Convenience header: boost/asio.hpp

async_write

async_write (1 of 4 overloads)
async_write (2 of 4 overloads)
async_write (3 of 4 overloads)
async_write (4 of 4 overloads)

Start an asynchronous operation to write a certain amount of data to a stream.

template<
    typename AsyncWriteStream,
    typename ConstBufferSequence,
    typename WriteHandler>
void-or-deduced async_write(
    AsyncWriteStream & s,
    const ConstBufferSequence & buffers,
    WriteHandler handler);
  » more...

template<
    typename AsyncWriteStream,
    typename ConstBufferSequence,
    typename CompletionCondition,
    typename WriteHandler>
void-or-deduced async_write(
    AsyncWriteStream & s,
    const ConstBufferSequence & buffers,
    CompletionCondition completion_condition,
    WriteHandler handler);
  » more...

template<
    typename AsyncWriteStream,
    typename Allocator,
    typename WriteHandler>
void-or-deduced async_write(
    AsyncWriteStream & s,
    basic_streambuf< Allocator > & b,
    WriteHandler handler);
  » more...

template<
    typename AsyncWriteStream,
    typename Allocator,
    typename CompletionCondition,
    typename WriteHandler>
void-or-deduced async_write(
    AsyncWriteStream & s,
    basic_streambuf< Allocator > & b,
    CompletionCondition completion_condition,
    WriteHandler handler);
  » more...

Requirements

Header: boost/asio/write.hpp

Convenience header: boost/asio.hpp

async_write (1 of 4 overloads)

Start an asynchronous operation to write all of the supplied data to a stream.

template<
    typename AsyncWriteStream,
    typename ConstBufferSequence,
    typename WriteHandler>
void-or-deduced async_write(
    AsyncWriteStream & s,
    const ConstBufferSequence & buffers,
    WriteHandler handler);

This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

All of the data in the supplied buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes.
An error occurred.

This operation is implemented in terms of zero or more calls to the stream's async_write_some function, and is known as a composed operation. The program must ensure that the stream performs no other write operations (such as async_write, the stream's async_write_some function, or any other composed operations that perform writes) until this operation completes.

Parameters

s

The stream to which the data is to be written. The type must support the AsyncWriteStream concept.

buffers

One or more buffers containing the data to be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.

handler

The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  const boost::system::error_code& error, // Result of operation.

  std::size_t bytes_transferred           // Number of bytes written from the
                                          // buffers. If an error occurred,
                                          // this will be less than the sum
                                          // of the buffer sizes.
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Example

To write a single data buffer use the buffer function as follows:

boost::asio::async_write(s, boost::asio::buffer(data, size), handler);

See the buffer documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

async_write (2 of 4 overloads)

Start an asynchronous operation to write a certain amount of data to a stream.

template<
    typename AsyncWriteStream,
    typename ConstBufferSequence,
    typename CompletionCondition,
    typename WriteHandler>
void-or-deduced async_write(
    AsyncWriteStream & s,
    const ConstBufferSequence & buffers,
    CompletionCondition completion_condition,
    WriteHandler handler);

This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

All of the data in the supplied buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes.
The completion_condition function object returns 0.

This operation is implemented in terms of zero or more calls to the stream's async_write_some function, and is known as a composed operation. The program must ensure that the stream performs no other write operations (such as async_write, the stream's async_write_some function, or any other composed operations that perform writes) until this operation completes.

Parameters

s

The stream to which the data is to be written. The type must support the AsyncWriteStream concept.

buffers

One or more buffers containing the data to be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.

completion_condition

The function object to be called to determine whether the write operation is complete. The signature of the function object must be:

std::size_t completion_condition(
  // Result of latest async_write_some operation.
  const boost::system::error_code& error,

  // Number of bytes transferred so far.
  std::size_t bytes_transferred
);

A return value of 0 indicates that the write operation is complete. A non-zero return value indicates the maximum number of bytes to be written on the next call to the stream's async_write_some function.

handler

The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  const boost::system::error_code& error, // Result of operation.

  std::size_t bytes_transferred           // Number of bytes written from the
                                          // buffers. If an error occurred,
                                          // this will be less than the sum
                                          // of the buffer sizes.
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Example

To write a single data buffer use the buffer function as follows:

boost::asio::async_write(s,
    boost::asio::buffer(data, size),
    boost::asio::transfer_at_least(32),
    handler);

See the buffer documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

async_write (3 of 4 overloads)

Start an asynchronous operation to write all of the supplied data to a stream.

template<
    typename AsyncWriteStream,
    typename Allocator,
    typename WriteHandler>
void-or-deduced async_write(
    AsyncWriteStream & s,
    basic_streambuf< Allocator > & b,
    WriteHandler handler);

This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

All of the data in the supplied basic_streambuf has been written.
An error occurred.

This operation is implemented in terms of zero or more calls to the stream's async_write_some function, and is known as a composed operation. The program must ensure that the stream performs no other write operations (such as async_write, the stream's async_write_some function, or any other composed operations that perform writes) until this operation completes.

Parameters

s

The stream to which the data is to be written. The type must support the AsyncWriteStream concept.

b

A basic_streambuf object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.

handler

The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  const boost::system::error_code& error, // Result of operation.

  std::size_t bytes_transferred           // Number of bytes written from the
                                          // buffers. If an error occurred,
                                          // this will be less than the sum
                                          // of the buffer sizes.
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

async_write (4 of 4 overloads)

Start an asynchronous operation to write a certain amount of data to a stream.

template<
    typename AsyncWriteStream,
    typename Allocator,
    typename CompletionCondition,
    typename WriteHandler>
void-or-deduced async_write(
    AsyncWriteStream & s,
    basic_streambuf< Allocator > & b,
    CompletionCondition completion_condition,
    WriteHandler handler);

This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

All of the data in the supplied basic_streambuf has been written.
The completion_condition function object returns 0.

This operation is implemented in terms of zero or more calls to the stream's async_write_some function, and is known as a composed operation. The program must ensure that the stream performs no other write operations (such as async_write, the stream's async_write_some function, or any other composed operations that perform writes) until this operation completes.

Parameters

s

The stream to which the data is to be written. The type must support the AsyncWriteStream concept.

b

A basic_streambuf object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.

completion_condition

The function object to be called to determine whether the write operation is complete. The signature of the function object must be:

std::size_t completion_condition(
  // Result of latest async_write_some operation.
  const boost::system::error_code& error,

  // Number of bytes transferred so far.
  std::size_t bytes_transferred
);

A return value of 0 indicates that the write operation is complete. A non-zero return value indicates the maximum number of bytes to be written on the next call to the stream's async_write_some function.

handler

The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  const boost::system::error_code& error, // Result of operation.

  std::size_t bytes_transferred           // Number of bytes written from the
                                          // buffers. If an error occurred,
                                          // this will be less than the sum
                                          // of the buffer sizes.
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

async_write_at

async_write_at (1 of 4 overloads)
async_write_at (2 of 4 overloads)
async_write_at (3 of 4 overloads)
async_write_at (4 of 4 overloads)

Start an asynchronous operation to write a certain amount of data at the specified offset.

template<
    typename AsyncRandomAccessWriteDevice,
    typename ConstBufferSequence,
    typename WriteHandler>
void-or-deduced async_write_at(
    AsyncRandomAccessWriteDevice & d,
    uint64_t offset,
    const ConstBufferSequence & buffers,
    WriteHandler handler);
  » more...

template<
    typename AsyncRandomAccessWriteDevice,
    typename ConstBufferSequence,
    typename CompletionCondition,
    typename WriteHandler>
void-or-deduced async_write_at(
    AsyncRandomAccessWriteDevice & d,
    uint64_t offset,
    const ConstBufferSequence & buffers,
    CompletionCondition completion_condition,
    WriteHandler handler);
  » more...

template<
    typename AsyncRandomAccessWriteDevice,
    typename Allocator,
    typename WriteHandler>
void-or-deduced async_write_at(
    AsyncRandomAccessWriteDevice & d,
    uint64_t offset,
    basic_streambuf< Allocator > & b,
    WriteHandler handler);
  » more...

template<
    typename AsyncRandomAccessWriteDevice,
    typename Allocator,
    typename CompletionCondition,
    typename WriteHandler>
void-or-deduced async_write_at(
    AsyncRandomAccessWriteDevice & d,
    uint64_t offset,
    basic_streambuf< Allocator > & b,
    CompletionCondition completion_condition,
    WriteHandler handler);
  » more...

Requirements

Header: boost/asio/write_at.hpp

Convenience header: boost/asio.hpp

async_write_at (1 of 4 overloads)

Start an asynchronous operation to write all of the supplied data at the specified offset.

template<
    typename AsyncRandomAccessWriteDevice,
    typename ConstBufferSequence,
    typename WriteHandler>
void-or-deduced async_write_at(
    AsyncRandomAccessWriteDevice & d,
    uint64_t offset,
    const ConstBufferSequence & buffers,
    WriteHandler handler);

This function is used to asynchronously write a certain number of bytes of data to a random access device at a specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

All of the data in the supplied buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes.
An error occurred.

This operation is implemented in terms of zero or more calls to the device's async_write_some_at function, and is known as a composed operation. The program must ensure that the device performs no overlapping write operations (such as async_write_at, the device's async_write_some_at function, or any other composed operations that perform writes) until this operation completes. Operations are overlapping if the regions defined by their offsets, and the numbers of bytes to write, intersect.

Parameters

d

The device to which the data is to be written. The type must support the AsyncRandomAccessWriteDevice concept.

offset

The offset at which the data will be written.

buffers

One or more buffers containing the data to be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.

handler

The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation.
  const boost::system::error_code& error,

  // Number of bytes written from the buffers. If an error
  // occurred, this will be less than the sum of the buffer sizes.
  std::size_t bytes_transferred
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Example

To write a single data buffer use the buffer function as follows:

boost::asio::async_write_at(d, 42, boost::asio::buffer(data, size), handler);

See the buffer documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

async_write_at (2 of 4 overloads)

Start an asynchronous operation to write a certain amount of data at the specified offset.

template<
    typename AsyncRandomAccessWriteDevice,
    typename ConstBufferSequence,
    typename CompletionCondition,
    typename WriteHandler>
void-or-deduced async_write_at(
    AsyncRandomAccessWriteDevice & d,
    uint64_t offset,
    const ConstBufferSequence & buffers,
    CompletionCondition completion_condition,
    WriteHandler handler);

This function is used to asynchronously write a certain number of bytes of data to a random access device at a specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

All of the data in the supplied buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes.
The completion_condition function object returns 0.

This operation is implemented in terms of zero or more calls to the device's async_write_some_at function, and is known as a composed operation. The program must ensure that the device performs no overlapping write operations (such as async_write_at, the device's async_write_some_at function, or any other composed operations that perform writes) until this operation completes. Operations are overlapping if the regions defined by their offsets, and the numbers of bytes to write, intersect.

Parameters

d

The device to which the data is to be written. The type must support the AsyncRandomAccessWriteDevice concept.

offset

The offset at which the data will be written.

buffers

One or more buffers containing the data to be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.

completion_condition

The function object to be called to determine whether the write operation is complete. The signature of the function object must be:

std::size_t completion_condition(
  // Result of latest async_write_some_at operation.
  const boost::system::error_code& error,

  // Number of bytes transferred so far.
  std::size_t bytes_transferred
);

A return value of 0 indicates that the write operation is complete. A non-zero return value indicates the maximum number of bytes to be written on the next call to the device's async_write_some_at function.

handler

The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation.
  const boost::system::error_code& error,

  // Number of bytes written from the buffers. If an error
  // occurred, this will be less than the sum of the buffer sizes.
  std::size_t bytes_transferred
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Example

To write a single data buffer use the buffer function as follows:

boost::asio::async_write_at(d, 42,
    boost::asio::buffer(data, size),
    boost::asio::transfer_at_least(32),
    handler);

See the buffer documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

async_write_at (3 of 4 overloads)

Start an asynchronous operation to write all of the supplied data at the specified offset.

template<
    typename AsyncRandomAccessWriteDevice,
    typename Allocator,
    typename WriteHandler>
void-or-deduced async_write_at(
    AsyncRandomAccessWriteDevice & d,
    uint64_t offset,
    basic_streambuf< Allocator > & b,
    WriteHandler handler);

This function is used to asynchronously write a certain number of bytes of data to a random access device at a specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

All of the data in the supplied basic_streambuf has been written.
An error occurred.

This operation is implemented in terms of zero or more calls to the device's async_write_some_at function, and is known as a composed operation. The program must ensure that the device performs no overlapping write operations (such as async_write_at, the device's async_write_some_at function, or any other composed operations that perform writes) until this operation completes. Operations are overlapping if the regions defined by their offsets, and the numbers of bytes to write, intersect.

Parameters

d

The device to which the data is to be written. The type must support the AsyncRandomAccessWriteDevice concept.

offset

The offset at which the data will be written.

b

A basic_streambuf object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.

handler

The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation.
  const boost::system::error_code& error,

  // Number of bytes written from the buffers. If an error
  // occurred, this will be less than the sum of the buffer sizes.
  std::size_t bytes_transferred
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

async_write_at (4 of 4 overloads)

Start an asynchronous operation to write a certain amount of data at the specified offset.

template<
    typename AsyncRandomAccessWriteDevice,
    typename Allocator,
    typename CompletionCondition,
    typename WriteHandler>
void-or-deduced async_write_at(
    AsyncRandomAccessWriteDevice & d,
    uint64_t offset,
    basic_streambuf< Allocator > & b,
    CompletionCondition completion_condition,
    WriteHandler handler);

This function is used to asynchronously write a certain number of bytes of data to a random access device at a specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

All of the data in the supplied basic_streambuf has been written.
The completion_condition function object returns 0.

This operation is implemented in terms of zero or more calls to the device's async_write_some_at function, and is known as a composed operation. The program must ensure that the device performs no overlapping write operations (such as async_write_at, the device's async_write_some_at function, or any other composed operations that perform writes) until this operation completes. Operations are overlapping if the regions defined by their offsets, and the numbers of bytes to write, intersect.

Parameters

d

The device to which the data is to be written. The type must support the AsyncRandomAccessWriteDevice concept.

offset

The offset at which the data will be written.

b

A basic_streambuf object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.

completion_condition

The function object to be called to determine whether the write operation is complete. The signature of the function object must be:

std::size_t completion_condition(
  // Result of latest async_write_some_at operation.
  const boost::system::error_code& error,

  // Number of bytes transferred so far.
  std::size_t bytes_transferred
);

A return value of 0 indicates that the write operation is complete. A non-zero return value indicates the maximum number of bytes to be written on the next call to the device's async_write_some_at function.

handler

The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation.
  const boost::system::error_code& error,

  // Number of bytes written from the buffers. If an error
  // occurred, this will be less than the sum of the buffer sizes.
  std::size_t bytes_transferred
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

basic_datagram_socket

basic_datagram_socket::assign
basic_datagram_socket::async_connect
basic_datagram_socket::async_receive
basic_datagram_socket::async_receive_from
basic_datagram_socket::async_send
basic_datagram_socket::async_send_to
basic_datagram_socket::at_mark
basic_datagram_socket::available
basic_datagram_socket::basic_datagram_socket
basic_datagram_socket::bind
basic_datagram_socket::broadcast
basic_datagram_socket::bytes_readable
basic_datagram_socket::cancel
basic_datagram_socket::close
basic_datagram_socket::connect
basic_datagram_socket::debug
basic_datagram_socket::do_not_route
basic_datagram_socket::enable_connection_aborted
basic_datagram_socket::endpoint_type
basic_datagram_socket::get_implementation
basic_datagram_socket::get_io_service
basic_datagram_socket::get_option
basic_datagram_socket::get_service
basic_datagram_socket::implementation
basic_datagram_socket::implementation_type
basic_datagram_socket::io_control
basic_datagram_socket::is_open
basic_datagram_socket::keep_alive
basic_datagram_socket::linger
basic_datagram_socket::local_endpoint
basic_datagram_socket::lowest_layer
basic_datagram_socket::lowest_layer_type
basic_datagram_socket::max_connections
basic_datagram_socket::message_do_not_route
basic_datagram_socket::message_end_of_record
basic_datagram_socket::message_flags
basic_datagram_socket::message_out_of_band
basic_datagram_socket::message_peek
basic_datagram_socket::native
basic_datagram_socket::native_handle
basic_datagram_socket::native_handle_type
basic_datagram_socket::native_non_blocking
basic_datagram_socket::native_type
basic_datagram_socket::non_blocking
basic_datagram_socket::non_blocking_io
basic_datagram_socket::open
basic_datagram_socket::operator=
basic_datagram_socket::protocol_type
basic_datagram_socket::receive
basic_datagram_socket::receive_buffer_size
basic_datagram_socket::receive_from
basic_datagram_socket::receive_low_watermark
basic_datagram_socket::remote_endpoint
basic_datagram_socket::reuse_address
basic_datagram_socket::send
basic_datagram_socket::send_buffer_size
basic_datagram_socket::send_low_watermark
basic_datagram_socket::send_to
basic_datagram_socket::service
basic_datagram_socket::service_type
basic_datagram_socket::set_option
basic_datagram_socket::shutdown
basic_datagram_socket::shutdown_type

Provides datagram-oriented socket functionality.

template<
    typename Protocol,
    typename DatagramSocketService = datagram_socket_service<Protocol>>
class basic_datagram_socket :
  public basic_socket< Protocol, DatagramSocketService >

Types

Name	Description
broadcast	Socket option to permit sending of broadcast messages.
bytes_readable	IO control command to get the amount of data that can be read without blocking.
debug	Socket option to enable socket-level debugging.
do_not_route	Socket option to prevent routing, use local interfaces only.
enable_connection_aborted	Socket option to report aborted connections on accept.
endpoint_type	The endpoint type.
implementation_type	The underlying implementation type of I/O object.
keep_alive	Socket option to send keep-alives.
linger	Socket option to specify whether the socket lingers on close if unsent data is present.
lowest_layer_type	A basic_socket is always the lowest layer.
message_flags	Bitmask type for flags that can be passed to send and receive operations.
native_handle_type	The native representation of a socket.
native_type	(Deprecated: Use native_handle_type.) The native representation of a socket.
non_blocking_io	(Deprecated: Use non_blocking().) IO control command to set the blocking mode of the socket.
protocol_type	The protocol type.
receive_buffer_size	Socket option for the receive buffer size of a socket.
receive_low_watermark	Socket option for the receive low watermark.
reuse_address	Socket option to allow the socket to be bound to an address that is already in use.
send_buffer_size	Socket option for the send buffer size of a socket.
send_low_watermark	Socket option for the send low watermark.
service_type	The type of the service that will be used to provide I/O operations.
shutdown_type	Different ways a socket may be shutdown.

Member Functions

Name	Description
assign	Assign an existing native socket to the socket.
async_connect	Start an asynchronous connect.
async_receive	Start an asynchronous receive on a connected socket.
async_receive_from	Start an asynchronous receive.
async_send	Start an asynchronous send on a connected socket.
async_send_to	Start an asynchronous send.
at_mark	Determine whether the socket is at the out-of-band data mark.
available	Determine the number of bytes available for reading.
basic_datagram_socket	Construct a basic_datagram_socket without opening it. Construct and open a basic_datagram_socket. Construct a basic_datagram_socket, opening it and binding it to the given local endpoint. Construct a basic_datagram_socket on an existing native socket. Move-construct a basic_datagram_socket from another. Move-construct a basic_datagram_socket from a socket of another protocol type.
bind	Bind the socket to the given local endpoint.
cancel	Cancel all asynchronous operations associated with the socket.
close	Close the socket.
connect	Connect the socket to the specified endpoint.
get_io_service	Get the io_service associated with the object.
get_option	Get an option from the socket.
io_control	Perform an IO control command on the socket.
is_open	Determine whether the socket is open.
local_endpoint	Get the local endpoint of the socket.
lowest_layer	Get a reference to the lowest layer. Get a const reference to the lowest layer.
native	(Deprecated: Use native_handle().) Get the native socket representation.
native_handle	Get the native socket representation.
native_non_blocking	Gets the non-blocking mode of the native socket implementation. Sets the non-blocking mode of the native socket implementation.
non_blocking	Gets the non-blocking mode of the socket. Sets the non-blocking mode of the socket.
open	Open the socket using the specified protocol.
operator=	Move-assign a basic_datagram_socket from another. Move-assign a basic_datagram_socket from a socket of another protocol type.
receive	Receive some data on a connected socket.
receive_from	Receive a datagram with the endpoint of the sender.
remote_endpoint	Get the remote endpoint of the socket.
send	Send some data on a connected socket.
send_to	Send a datagram to the specified endpoint.
set_option	Set an option on the socket.
shutdown	Disable sends or receives on the socket.

Protected Member Functions

Name	Description
get_implementation	Get the underlying implementation of the I/O object.
get_service	Get the service associated with the I/O object.

Data Members

Name	Description
max_connections	The maximum length of the queue of pending incoming connections.
message_do_not_route	Specify that the data should not be subject to routing.
message_end_of_record	Specifies that the data marks the end of a record.
message_out_of_band	Process out-of-band data.
message_peek	Peek at incoming data without removing it from the input queue.

Protected Data Members

Name	Description
implementation	(Deprecated: Use get_implementation().) The underlying implementation of the I/O object.
service	(Deprecated: Use get_service().) The service associated with the I/O object.

The basic_datagram_socket class template provides asynchronous and blocking datagram-oriented socket functionality.

Thread Safety

Distinct objects: Safe.

Shared objects: Unsafe.

Requirements

Header: boost/asio/basic_datagram_socket.hpp

Convenience header: boost/asio.hpp

basic_datagram_socket::assign

basic_datagram_socket::assign (1 of 2 overloads)
basic_datagram_socket::assign (2 of 2 overloads)

Assign an existing native socket to the socket.

void assign(
    const protocol_type & protocol,
    const native_handle_type & native_socket);
  » more...

boost::system::error_code assign(
    const protocol_type & protocol,
    const native_handle_type & native_socket,
    boost::system::error_code & ec);
  » more...

basic_datagram_socket::assign (1 of 2 overloads)

Inherited from basic_socket.

Assign an existing native socket to the socket.

void assign(
    const protocol_type & protocol,
    const native_handle_type & native_socket);

basic_datagram_socket::assign (2 of 2 overloads)

Inherited from basic_socket.

Assign an existing native socket to the socket.

boost::system::error_code assign(
    const protocol_type & protocol,
    const native_handle_type & native_socket,
    boost::system::error_code & ec);

basic_datagram_socket::async_connect

Inherited from basic_socket.

Start an asynchronous connect.

template<
    typename ConnectHandler>
void-or-deduced async_connect(
    const endpoint_type & peer_endpoint,
    ConnectHandler handler);

This function is used to asynchronously connect a socket to the specified remote endpoint. The function call always returns immediately.

The socket is automatically opened if it is not already open. If the connect fails, and the socket was automatically opened, the socket is not returned to the closed state.

Parameters

peer_endpoint

The remote endpoint to which the socket will be connected. Copies will be made of the endpoint object as required.

handler

The handler to be called when the connection operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  const boost::system::error_code& error // Result of operation
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Example

void connect_handler(const boost::system::error_code& error)
{
  if (!error)
  {
    // Connect succeeded.
  }
}

...

boost::asio::ip::tcp::socket socket(io_service);
boost::asio::ip::tcp::endpoint endpoint(
    boost::asio::ip::address::from_string("1.2.3.4"), 12345);
socket.async_connect(endpoint, connect_handler);

basic_datagram_socket::async_receive

basic_datagram_socket::async_receive (1 of 2 overloads)
basic_datagram_socket::async_receive (2 of 2 overloads)

Start an asynchronous receive on a connected socket.

template<
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_receive(
    const MutableBufferSequence & buffers,
    ReadHandler handler);
  » more...

template<
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_receive(
    const MutableBufferSequence & buffers,
    socket_base::message_flags flags,
    ReadHandler handler);
  » more...

basic_datagram_socket::async_receive (1 of 2 overloads)

Start an asynchronous receive on a connected socket.

template<
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_receive(
    const MutableBufferSequence & buffers,
    ReadHandler handler);

This function is used to asynchronously receive data from the datagram socket. The function call always returns immediately.

Parameters

buffers

One or more buffers into which the data will be received. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.

handler

The handler to be called when the receive operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  const boost::system::error_code& error, // Result of operation.
  std::size_t bytes_transferred           // Number of bytes received.
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Remarks

The async_receive operation can only be used with a connected socket. Use the async_receive_from function to receive data on an unconnected datagram socket.

Example

To receive into a single data buffer use the buffer function as follows:

socket.async_receive(boost::asio::buffer(data, size), handler);

See the buffer documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

basic_datagram_socket::async_receive (2 of 2 overloads)

Start an asynchronous receive on a connected socket.

template<
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_receive(
    const MutableBufferSequence & buffers,
    socket_base::message_flags flags,
    ReadHandler handler);

This function is used to asynchronously receive data from the datagram socket. The function call always returns immediately.

Parameters

buffers

One or more buffers into which the data will be received. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.

flags

Flags specifying how the receive call is to be made.

handler

The handler to be called when the receive operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  const boost::system::error_code& error, // Result of operation.
  std::size_t bytes_transferred           // Number of bytes received.
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Remarks

The async_receive operation can only be used with a connected socket. Use the async_receive_from function to receive data on an unconnected datagram socket.

basic_datagram_socket::async_receive_from

basic_datagram_socket::async_receive_from (1 of 2 overloads)
basic_datagram_socket::async_receive_from (2 of 2 overloads)

Start an asynchronous receive.

template<
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_receive_from(
    const MutableBufferSequence & buffers,
    endpoint_type & sender_endpoint,
    ReadHandler handler);
  » more...

template<
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_receive_from(
    const MutableBufferSequence & buffers,
    endpoint_type & sender_endpoint,
    socket_base::message_flags flags,
    ReadHandler handler);
  » more...

basic_datagram_socket::async_receive_from (1 of 2 overloads)

Start an asynchronous receive.

template<
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_receive_from(
    const MutableBufferSequence & buffers,
    endpoint_type & sender_endpoint,
    ReadHandler handler);

This function is used to asynchronously receive a datagram. The function call always returns immediately.

Parameters

buffers

One or more buffers into which the data will be received. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.

sender_endpoint

An endpoint object that receives the endpoint of the remote sender of the datagram. Ownership of the sender_endpoint object is retained by the caller, which must guarantee that it is valid until the handler is called.

handler

The handler to be called when the receive operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  const boost::system::error_code& error, // Result of operation.
  std::size_t bytes_transferred           // Number of bytes received.
);

Regardless of whether the asynchronous operation completes imme

Core

Classes

Class Templates

Free Functions

Special Values

Boost.Bind Placeholders

Error Codes

Type Traits

Type Requirements

Networking

Classes

Free Functions

Class Templates

Services

Socket Options

I/O Control Commands

Type Requirements

Timers

SSL

Serial Ports

Signal Handling

Classes

Class Templates

Services

Type Requirements

Classes

Class Templates

Type Requirements

Classes

Class Templates

Services

Serial Port Options

Type Requirements

Classes

Class Templates

Services

Type Requirements

POSIX-specific

Windows-specific

Classes

Free Functions

Class Templates

Services

Type Requirements

Classes

Class Templates

Services

Type Requirements