net_ts.qbk

[/
 / Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com)
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]

[section:net_ts Networking TS compatibility]

Boost.Asio now provides the interfaces and functionality specified by the "C++
Extensions for Networking" Technical Specification. In addition to access via
the usual Boost.Asio header files, this functionality may be accessed through special
headers that correspond to the header files defined in the TS. These are listed
in the table below:

[table
  [[Networking TS header][Boost.Asio header]]
  [[`#include <buffer>`][`#include <boost/asio/ts/buffer.hpp>`]]
  [[`#include <executor>`][`#include <boost/asio/ts/executor.hpp>`]]
  [[`#include <internet>`][`#include <boost/asio/ts/internet.hpp>`]]
  [[`#include <io_context>`][`#include <boost/asio/ts/io_context.hpp>`]]
  [[`#include <net>`][`#include <boost/asio/ts/net.hpp>`]]
  [[`#include <netfwd>`][`#include <boost/asio/ts/netfwd.hpp>`]]
  [[`#include <socket>`][`#include <boost/asio/ts/socket.hpp>`]]
  [[`#include <timer>`][`#include <boost/asio/ts/timer.hpp>`]]
]

In some cases the new Networking TS compatible interfaces supersede older Boost.Asio
facilities. In these cases the older interfaces have been deprecated. The table
below shows the new Networking TS interfaces and the facilities they replace:

[table
  [[New interface][Old interface][Notes]]
  [
    [[link boost_asio.reference.io_context `io_context`]]
    [[link boost_asio.reference.io_service `io_service`]]
    [The name `io_service` is retained as a typedef.]
  ]
  [
    [[link boost_asio.reference.dispatch `dispatch`]]
    [[link boost_asio.reference.io_context.dispatch `io_service::dispatch`]]
    [The `dispatch` free function can be used to submit functions to any [link
    boost_asio.reference.Executor1 Executor] or [link boost_asio.reference.ExecutionContext
    ExecutionContext].]
  ]
  [
    [[link boost_asio.reference.post `post`]]
    [[link boost_asio.reference.io_context.post `io_service::post`]]
    [The `post` free function can be used to submit functions to any [link
    boost_asio.reference.Executor1 Executor] or [link boost_asio.reference.ExecutionContext
    ExecutionContext].]
  ]
  [
    [[link boost_asio.reference.defer `defer`]]
    [[link boost_asio.reference.io_context.post `io_service::post`] when the [link
    boost_asio.reference.asio_handler_is_continuation `asio_handler_is_continuation`]
    hook returns true]
    [The `defer` free function can be used to submit functions to any [link
    boost_asio.reference.Executor1 Executor] or [link boost_asio.reference.ExecutionContext
    ExecutionContext].]
  ]
  [
    [[link boost_asio.reference.io_context.poll `io_context::poll`]]
    [[link boost_asio.reference.io_context.poll `io_service::poll`] overload that
    takes `error_code&`]
    [The `error_code` overload is not required.]
  ]
  [
    [[link boost_asio.reference.io_context.poll_one `io_context::poll_one`]]
    [[link boost_asio.reference.io_context.poll_one `io_service::poll_one`] overload
    that takes `error_code&`]
    [The `error_code` overload is not required.]
  ]
  [
    [[link boost_asio.reference.io_context.run `io_context::run`]]
    [[link boost_asio.reference.io_context.run `io_service::run`] overload that takes
    `error_code&`]
    [The `error_code` overload is not required.]
  ]
  [
    [[link boost_asio.reference.io_context.run_one `io_context::run_one`]]
    [[link boost_asio.reference.io_context.run_one `io_service::run_one`] overload
    that takes `error_code&`]
    [The `error_code` overload is not required.]
  ]
  [
    [[link boost_asio.reference.io_context.run_for `io_context::run_for`],
    [link boost_asio.reference.io_context.run_until `io_context::run_until`],
    [link boost_asio.reference.io_context.run_one_for `io_context::run_one_for`], and
    [link boost_asio.reference.io_context.run_one_until `io_context::run_one_until`]]
    []
    [These functions add the ability to run an `io_context` for a limited time.]
  ]
  [
    [[link boost_asio.reference.io_context.restart `io_context::restart`]]
    [[link boost_asio.reference.io_context.reset `io_service::reset`]]
    []
  ]
  [
    [[link boost_asio.reference.io_context.io_context `io_context`] constructor
    `concurrency_hint` parameter is type `int`]
    [[link boost_asio.reference.io_context.io_context `io_context`] constructor
    `concurrency_hint` parameter is type `std::size_t`]
    [The old constructor has not been retained as a deprecated overload.]
  ]
  [
    [[link boost_asio.reference.execution_context `execution_context`], [link
    boost_asio.reference.execution_context__service `execution_context::service`],
    and [link boost_asio.reference.execution_context__id `execution_context::id`]]
    [[link boost_asio.reference.io_context `io_service`], [link
    boost_asio.reference.io_context__service `io_service::service`], and [link
    boost_asio.reference.execution_context__id `io_service::id`]]
    [The service-related functionality has been moved to the
    `execution_context` base class. This may also be used as a base for
    creating custom execution contexts.]
  ]
  [
    [[link boost_asio.reference.execution_context.make_service `make_service`]]
    [[link boost_asio.reference.execution_context.add_service `add_service`]]
    []
  ]
  [
    [[link boost_asio.reference.strand `strand`]]
    [[link boost_asio.reference.io_context__strand `io_service::strand`]]
    [This template works with any valid executor, and is itself a valid
    executor.]
  ]
  [
    [[link boost_asio.reference.executor_work_guard `executor_work_guard`] and [link
    boost_asio.reference.make_work_guard `make_work_guard`]]
    [[link boost_asio.reference.io_context__work `io_service::work`]]
    [Work tracking is now covered by the [link boost_asio.reference.Executor1
    Executor] requirements. These templates work with any valid executor.]
  ]
  [
    [[link boost_asio.reference.executor_binder `executor_binder`] and [link
    boost_asio.reference.bind_executor `bind_executor`]]
    [[link boost_asio.reference.io_context.wrap `io_service::wrap`] and
    [link boost_asio.reference.io_context__strand.wrap `io_service::strand::wrap`]]
    [These templates work with any valid executor.]
  ]
  [
    [[link boost_asio.reference.async_result `async_result`] with `CompletionToken`
    and `Signature` template parameters]
    [`handler_type` and single parameter `async_result`]
    [The `async_result` trait is now the single point of customisation for
    asynchronous operation completion handlers and return type.]
  ]
  [
    [[link boost_asio.reference.associated_executor `associated_executor`] and [link
    boost_asio.reference.get_associated_executor `get_associated_executor`]]
    [[link boost_asio.reference.asio_handler_invoke `asio_handler_invoke`]]
    [The handler invocation hook has been replaced by the new [link
    boost_asio.reference.Executor1 Executor] requirements and the associated executor
    traits.]
  ]
  [
    [[link boost_asio.reference.associated_allocator `associated_allocator`] and
    [link boost_asio.reference.get_associated_allocator `get_associated_allocator`]]
    [[link boost_asio.reference.asio_handler_allocate `asio_handler_allocate`] and
    [link boost_asio.reference.asio_handler_deallocate `asio_handler_deallocate`]]
    [The handler allocation hooks have been replaced by the standard Allocator
    requirements and the associated allocator traits.]
  ]
  [
    [[link boost_asio.reference.const_buffer.data `const_buffer::data`] and [link
    boost_asio.reference.mutable_buffer.data `mutable_buffer::data`]]
    [[link boost_asio.reference.buffer_cast `buffer_cast`]]
    []
  ]
  [
    [[link boost_asio.reference.const_buffer.size `const_buffer::size`] and [link
    boost_asio.reference.mutable_buffer.size `mutable_buffer::size`]]
    [[link boost_asio.reference.buffer_size `buffer_size`] for single buffers]
    [`buffer_size` is not deprecated for single buffers as `const_buffer` and
    `mutable_buffer` now satisfy the buffer sequence requirements]
  ]
  [
    [[link boost_asio.reference.const_buffer `const_buffer`]]
    [[link boost_asio.reference.const_buffers_1 `const_buffers_1`]]
    [The [link boost_asio.reference.ConstBufferSequence ConstBufferSequence]
    requirements have been modified such that `const_buffer` now satisfies
    them.]
  ]
  [
    [[link boost_asio.reference.mutable_buffer `mutable_buffer`]]
    [[link boost_asio.reference.mutable_buffers_1 `mutable_buffers_1`]]
    [The [link boost_asio.reference.MutableBufferSequence MutableBufferSequence]
    requirements have been modified such that `mutable_buffer` now satisfies
    them.]
  ]
  [
    [[link boost_asio.reference.basic_socket.get_executor
    `basic_socket::get_executor`] (and corresponding member for I/O objects
    such as timers, serial ports, etc.)]
    [[link boost_asio.reference.basic_io_object.get_io_service
    `basic_io_object::get_io_service`]]
    [Use `get_executor().context()` to obtain the associated `io_context`.]
  ]
  [
    [[link boost_asio.reference.socket_base.max_listen_connections
    `socket_base::max_listen_connections`]]
    [[link boost_asio.reference.socket_base.max_connections
    `socket_base::max_connections`]]
    []
  ]
  [
    [[link boost_asio.reference.socket_base.wait_type `socket_base::wait_type`],
    [link boost_asio.reference.basic_socket.wait `basic_socket::wait`], [link
    boost_asio.reference.basic_socket.async_wait `basic_socket::async_wait`], [link
    boost_asio.reference.basic_socket_acceptor.wait `basic_socket_acceptor::wait`],
    and [link boost_asio.reference.basic_socket_acceptor.async_wait
    `basic_socket_acceptor::async_wait`]]
    [[link boost_asio.reference.null_buffers `null_buffers`]]
    [Operations for reactive I/O.]
  ]
  [
    [[link boost_asio.reference.basic_socket_acceptor.accept
    `basic_socket_acceptor::accept`] returns a socket]
    [[link boost_asio.reference.basic_socket_acceptor.accept
    `basic_socket_acceptor::accept`] takes a socket by reference]
    [Uses move support so requires C++11 or later. To accept a connection into
    a socket object on a different `io_context`, pass the destination context
    to `accept`.]
  ]
  [
    [[link boost_asio.reference.basic_socket_acceptor.async_accept
    `basic_socket_acceptor::async_accept`] passes socket to handler]
    [[link boost_asio.reference.basic_socket_acceptor.async_accept
    `basic_socket_acceptor::async_accept`] takes a socket by reference]
    [Uses move support so requires C++11 or later. To accept a connection into
    a socket object on a different `io_context`, pass the destination context
    to `async_accept`.]
  ]
  [
    [[link boost_asio.reference.connect `connect`] overloads that take a range]
    [[link boost_asio.reference.connect `connect`] overloads that take a single
    iterator]
    [The [link boost_asio.reference.ip__basic_resolver.resolve
    `ip::basic_resolver::resolve`] function now returns a range. When the
    `resolve` function's result is passed directly to `connect`, the range
    overload will be selected.]
  ]
  [
    [[link boost_asio.reference.async_connect `async_connect`] overloads that take a
    range]
    [[link boost_asio.reference.async_connect `async_connect`] overloads that take a
    single iterator]
    [The [link boost_asio.reference.ip__basic_resolver.resolve
    `ip::basic_resolver::resolve`] function now returns a range. When the
    `resolve` function's result is passed directly to `async_connect`, the
    range overload will be selected.]
  ]
  [
    [[link boost_asio.reference.basic_socket_streambuf.duration
    `basic_socket_streambuf::duration`]]
    [[link boost_asio.reference.basic_socket_streambuf.duration_type
    `basic_socket_streambuf::duration_type`]]
    []
  ]
  [
    [[link boost_asio.reference.basic_socket_streambuf.time_point
    `basic_socket_streambuf::time_point`]]
    [[link boost_asio.reference.basic_socket_streambuf.time_type
    `basic_socket_streambuf::time_type`]]
    []
  ]
  [
    [[link boost_asio.reference.basic_socket_streambuf.expiry
    `basic_socket_streambuf::expiry`]]
    [[link boost_asio.reference.basic_socket_streambuf.expires_at
    `basic_socket_streambuf::expires_at`] and [link
    boost_asio.reference.basic_socket_streambuf.expires_from_now
    `basic_socket_streambuf::expires_from_now`] getters]
    []
  ]
  [
    [[link boost_asio.reference.basic_socket_streambuf.expires_after
    `basic_socket_streambuf::expires_after`]]
    [[link boost_asio.reference.basic_socket_streambuf.expires_from_now
    `basic_socket_streambuf::expires_from_now`] setter]
    []
  ]
  [
    [[link boost_asio.reference.basic_socket_streambuf.error
    `basic_socket_streambuf::error`]]
    [[link boost_asio.reference.basic_socket_streambuf.puberror
    `basic_socket_streambuf::puberror`]]
    []
  ]
  [
    [[link boost_asio.reference.basic_socket_iostream.duration
    `basic_socket_iostream::duration`]]
    [[link boost_asio.reference.basic_socket_iostream.duration_type
    `basic_socket_iostream::duration_type`]]
    []
  ]
  [
    [[link boost_asio.reference.basic_socket_iostream.time_point
    `basic_socket_iostream::time_point`]]
    [[link boost_asio.reference.basic_socket_iostream.time_type
    `basic_socket_iostream::time_type`]]
    []
  ]
  [
    [[link boost_asio.reference.basic_socket_iostream.expiry
    `basic_socket_iostream::expiry`]]
    [[link boost_asio.reference.basic_socket_iostream.expires_at
    `basic_socket_iostream::expires_at`] and [link
    boost_asio.reference.basic_socket_iostream.expires_from_now
    `basic_socket_iostream::expires_from_now`] getters]
    []
  ]
  [
    [[link boost_asio.reference.basic_socket_iostream.expires_after
    `basic_socket_iostream::expires_after`]]
    [[link boost_asio.reference.basic_socket_iostream.expires_from_now
    `basic_socket_iostream::expires_from_now`] setter]
    []
  ]
  [
    [[link boost_asio.reference.basic_waitable_timer.cancel
    `basic_waitable_timer::cancel`]]
    [[link boost_asio.reference.basic_waitable_timer.cancel
    `basic_waitable_timer::cancel`] overload that takes `error_code&`]
    [The `error_code` overload is not required.]
  ]
  [
    [[link boost_asio.reference.basic_waitable_timer.cancel_one
    `basic_waitable_timer::cancel_one`]]
    [[link boost_asio.reference.basic_waitable_timer.cancel_one
    `basic_waitable_timer::cancel_one`] overload that takes `error_code&`]
    [The `error_code` overload is not required.]
  ]
  [
    [[link boost_asio.reference.basic_waitable_timer.expires_at
    `basic_waitable_timer::expires_at`] setter]
    [[link boost_asio.reference.basic_waitable_timer.expires_at
    `basic_waitable_timer::expires_at`] setter that takes `error_code&`]
    [The `error_code` overload is not required.]
  ]
  [
    [[link boost_asio.reference.basic_waitable_timer.expiry
    `basic_waitable_timer::expiry`]]
    [[link boost_asio.reference.basic_waitable_timer.expires_at
    `basic_waitable_timer::expires_at`] and [link
    boost_asio.reference.basic_waitable_timer.expires_from_now
    `basic_waitable_timer::expires_from_now`] getters]
    []
  ]
  [
    [[link boost_asio.reference.basic_waitable_timer.expires_after
    `basic_waitable_timer::expires_after`]]
    [[link boost_asio.reference.basic_waitable_timer.expires_from_now
    `basic_waitable_timer::expires_from_now`] setter]
    []
  ]
  [
    [[link boost_asio.reference.ip__address.make_address `ip::make_address`]]
    [[link boost_asio.reference.ip__address.from_string `ip::address::from_string`]]
    []
  ]
  [
    [[link boost_asio.reference.ip__address_v4.make_address_v4 `ip::make_address_v4`]]
    [[link boost_asio.reference.ip__address_v4.from_string
    `ip::address_v4::from_string`] and [link
    boost_asio.reference.ip__address_v6.to_v4 `ip::address_v6::to_v4`]]
    []
  ]
  [
    [[link boost_asio.reference.ip__address_v6.make_address_v6 `ip::make_address_v6`]]
    [[link boost_asio.reference.ip__address_v6.from_string
    `ip::address_v6::from_string`] and [link
    boost_asio.reference.ip__address_v6.v4_mapped `ip::address_v6::v4_mapped`]]
    []
  ]
  [
    [[link boost_asio.reference.ip__address.to_string `ip::address::to_string`]]
    [[link boost_asio.reference.ip__address.to_string `ip::address::to_string`] that
    takes `error_code&`]
    [The `error_code` overload is not required.]
  ]
  [
    [[link boost_asio.reference.ip__address_v4.to_string `ip::address_v4::to_string`]]
    [[link boost_asio.reference.ip__address_v4.to_string `ip::address_v4::to_string`]
    that takes `error_code&`]
    [The `error_code` overload is not required.]
  ]
  [
    [[link boost_asio.reference.ip__address_v6.to_string `ip::address_v6::to_string`]]
    [[link boost_asio.reference.ip__address_v6.to_string `ip::address_v6::to_string`]
    that takes `error_code&`]
    [The `error_code` overload is not required.]
  ]
  [
    [No replacement]
    [[link boost_asio.reference.ip__address_v6.is_v4_compatible
    `ip::address_v6::is_v4_compatible`] and [link
    boost_asio.reference.ip__address_v6.v4_compatible
    `ip::address_v6::v4_compatible`]]
    []
  ]
  [
    [[link boost_asio.reference.ip__network_v4 `ip::network_v4`]]
    [[link boost_asio.reference.ip__address_v4.broadcast `ip::address_v4::broadcast`],
    [link boost_asio.reference.ip__address_v4.is_class_a `ip::address_v4::is_class_a`],
    [link boost_asio.reference.ip__address_v4.is_class_b `ip::address_v4::is_class_b`],
    [link boost_asio.reference.ip__address_v4.is_class_c `ip::address_v4::is_class_c`],
    and [link boost_asio.reference.ip__address_v4.netmask `ip::address_v4::netmask`]]
    [The `network_v4` class adds the ability to manipulate IPv4 network
    addresses using CIDR notation.]
  ]
  [
    [[link boost_asio.reference.ip__network_v6 `ip::network_v6`]]
    []
    [The `network_v6` class adds the ability to manipulate IPv6 network
    addresses using CIDR notation.]
  ]
  [
    [[link boost_asio.reference.ip__basic_address_iterator_lt__address_v4__gt_
    `ip::address_v4_iterator`] and [link
    boost_asio.reference.ip__basic_address_range_lt__address_v4__gt_
    `ip::address_v4_range`]]
    []
    [The `ip::address_v4_iterator` and `address_v4_range` classes add the
    ability to iterate over all, or a subset of, IPv4 addresses.]
  ]
  [
    [[link boost_asio.reference.ip__basic_address_iterator_lt__address_v6__gt_
    `ip::address_v6_iterator`] and [link
    boost_asio.reference.ip__basic_address_range_lt__address_v6__gt_
    `ip::address_v6_range`]]
    []
    [The `ip::address_v6_iterator` and `address_v6_range` classes add the
    ability to iterate over all, or a subset of, IPv6 addresses.]
  ]
  [
    [[link boost_asio.reference.ip__basic_resolver.results_type
    `ip::basic_resolver::results_type`]]
    [[link boost_asio.reference.ip__basic_resolver.iterator
    `ip::basic_resolver::iterator`]]
    [Resolvers now produce ranges rather than single iterators.]
  ]
  [
    [[link boost_asio.reference.ip__basic_resolver.resolve
    `ip::basic_resolver::resolve`] overloads taking hostname and service as
    arguments]
    [[link boost_asio.reference.ip__basic_resolver.resolve
    `ip::basic_resolver::resolve`] overloads taking a [link
    boost_asio.reference.ip__basic_resolver.query `ip::basic_resolver::query`]]
    []
  ]
  [
    [[link boost_asio.reference.ip__basic_resolver.resolve
    `ip::basic_resolver::resolve`] returns a range]
    [[link boost_asio.reference.ip__basic_resolver.resolve
    `ip::basic_resolver::resolve`] returns a single iterator]
    []
  ]
  [
    [[link boost_asio.reference.ip__basic_resolver.async_resolve
    `ip::basic_resolver::async_resolve`] overloads taking hostname and service
    as arguments]
    [[link boost_asio.reference.ip__basic_resolver.async_resolve
    `ip::basic_resolver::async_resolve`] overloads taking a [link
    boost_asio.reference.ip__basic_resolver.query `ip::basic_resolver::query`]]
    []
  ]
  [
    [[link boost_asio.reference.ip__basic_resolver.async_resolve
    `ip::basic_resolver::async_resolve`] calls the handler with a range]
    [[link boost_asio.reference.ip__basic_resolver.async_resolve
    `ip::basic_resolver::async_resolve`] calls the handler with a single
    iterator]
    []
  ]
]

[endsect]