experimental::basic

experimental::basic_channel

A channel for messages.

template<
    typename Executor,
    typename Traits,
    typename... Signatures>
class basic_channel

Types

Name	Description
rebind_executor	Rebinds the channel type to another executor.
executor_type	The type of the executor associated with the channel.
traits_type	The traits type associated with the channel.

Member Functions

Name	Description
async_receive	Asynchronously receive a message.
async_send	Asynchronously send a message.
basic_channel [constructor]	Construct a basic_channel. — Construct and open a basic_channel. — Move-construct a basic_channel from another.
cancel	Cancel all asynchronous operations waiting on the channel.
capacity	Get the capacity of the channel's buffer.
close	Close the channel.
get_executor	Get the executor associated with the object.
is_open	Determine whether the channel is open.
operator=	Move-assign a basic_channel from another.
ready	Determine whether a message can be received without blocking.
reset	Reset the channel to its initial state.
try_receive	Try to receive a message without blocking.
try_send	Try to send a message without blocking.
try_send_n	Try to send a number of messages without blocking.
try_send_n_via_dispatch	Try to send a number of messages without blocking, using dispatch semantics to call the receive operations' completion handlers.
try_send_via_dispatch	Try to send a message without blocking, using dispatch semantics to call the receive operation's completion handler.
~basic_channel [destructor]	Destructor.

The experimental::basic_channel class template is used for sending messages between different parts of the same application. A message is defined as a collection of arguments to be passed to a completion handler, and the set of messages supported by a channel is specified by its Traits and Signatures... template parameters. Messages may be sent and received using asynchronous or non-blocking synchronous operations.

Unless customising the traits, applications will typically use the experimental::channel alias template. For example:

void send_loop(int i, steady_timer& timer,
    channel<void(error_code, int)>& ch)
{
  if (i < 10)
  {
    timer.expires_after(chrono::seconds(1));
    timer.async_wait(
        [i, &timer, &ch](error_code error)
        {
          if (!error)
          {
            ch.async_send(error_code(), i,
                [i, &timer, &ch](error_code error)
                {
                  if (!error)
                  {
                    send_loop(i + 1, timer, ch);
                  }
                });
          }
        });
  }
  else
  {
    ch.close();
  }
}

void receive_loop(channel<void(error_code, int)>& ch)
{
  ch.async_receive(
      [&ch](error_code error, int i)
      {
        if (!error)
        {
          std::cout << "Received " << i << "\n";
          receive_loop(ch);
        }
      });
}

Thread Safety

Distinct objects: Safe.

Shared objects: Unsafe.

The experimental::basic_channel class template is not thread-safe, and would typically be used for passing messages between application code that runs on the same thread or in the same strand. Consider using experimental::basic_concurrent_channel, and its alias template experimental::concurrent_channel, to pass messages between code running in different threads.

Requirements

Header: boost/asio/experimental/basic_channel.hpp

Convenience header: None