In Boost.Asio, a fixed length buffer is represented by one of the two classes: asio::mutable_buffer or asio::const_buffer. Both these classes represent a contiguous block of memory that is specified by the address of the first byte of the block and its size in bytes. As the names of these classes suggest, asio::mutable_buffer represents a writable buffer, whereas asio::const_buffer represents a read-only one.

However, neither the asio::mutable_buffer nor asio::const_buffer classes are used in Boost.Asio I/O functions and methods directly. Instead, the MutableBufferSequence and ConstBufferSequence concepts are introduced.

The MutableBufferSequence concept specifies an object that represents a collection of the asio::mutable_buffer objects. Correspondingly, the ConstBufferSequence concept specifies an object that represents a collection of the asio::const_buffer objects. Boost.Asio functions and methods that perform I/O operations accept objects that satisfy the requirements of either the MutableBufferSequence or ConstBufferSequence concept as their arguments that represent buffers.

Although in most use cases, a single buffer is involved in a single I/O operation, in some specific circumstances (for example, in a memory-constrained environment), a developer may want to use a composite buffer that comprises multiple smaller simple buffers distributed over the process's address space. Boost.Asio I/O functions and methods are designed to work with composite buffers that are represented as a collection of buffers that fulfill the requirements of either the MutableBufferSequence or ConstBufferSequence concept.

For instance, an object of the std::vector<asio::mutable_buffer> class satisfies the requirements of the MutableBufferSequence concept, and therefore, it can be used to represent a composite buffer in I/O-related functions and methods.

So, now we know that if we have a buffer that is represented as an object of the asio::mutable_buffer or asio::const_buffer class, we still can't use it with I/O-related functions or methods provided by Boost.Asio. The buffer must be represented as an object, satisfying the requirements of either the MutableBufferSequence or ConstBufferSequence concept, respectively. To do this, we for example could create a collection of buffer objects consisting of a single buffer by instantiating an object of the std::vector<asio::mutable_buffer> class and placing our buffer object into it. Now that the buffer is part of the collection, satisfying the MutableBufferSequence requirements can be used in I/O operations.

However, although this method is fine to create composite buffers consisting of two or more simple buffers, it looks overly complex when it comes to such simple tasks as representing a single simple buffer so that it can be used with Boost.Asio I/O functions or methods. Fortunately, Boost.Asio provides us with a way to simplify the usage of single buffers with I/O-related functions and methods.

The asio::buffer() free function has 28 overloads that accept a variety of representations of a buffer and return an object of either the asio::mutable_buffers_1 or asio::const_buffers_1 classes. If the buffer argument passed to the asio::buffer() function is a read-only type, the function returns an object of the asio::const_buffers_1 class; otherwise, an object of the asio::mutable_buffers_1 class is returned.

The asio::mutable_buffers_1 and asio::const_buffers_1 classes are adapters of the asio::mutable_buffer and asio::const_buffer classes, respectively. They provide an interface and behavior that satisfy the requirements of the MutableBufferSequence and ConstBufferSequence concepts, which allows us to pass these adapters as arguments to Boost.Asio I/O functions and methods.

Let's consider two algorithms and corresponding code samples that describe how to prepare a memory buffer that can be used with Boost.Asio I/O operations. The first algorithm deals with buffers intended to be used for an output operation and the second one is used for an input operation.

#include <boost/asio.hpp>
#include <iostream>

using namespace boost;

int main()
{
  std::string buf; // 'buf' is the raw buffer. 
  buf = "Hello";   // Step 1 and 2 in single line.

  // Step 3. Creating buffer representation that satisfies 
  // ConstBufferSequence concept requirements.
  asio::const_buffers_1 output_buf = asio::buffer(buf);

  // Step 4. 'output_buf' is the representation of the
  // buffer 'buf' that can be used in Boost.Asio output
  // operations.

  return 0;
}

#include <boost/asio.hpp>
#include <iostream>
#include <memory> // For std::unique_ptr<>

using namespace boost;

int main()
{
  // We expect to receive a block of data no more than 20 bytes 
  // long. 
  const size_t BUF_SIZE_BYTES = 20;

  // Step 1. Allocating the buffer. 
  std::unique_ptr<char[]> buf(new char[BUF_SIZE_BYTES]);

  // Step 2. Creating buffer representation that satisfies 
  // MutableBufferSequence concept requirements.
  asio::mutable_buffers_1 input_buf =
    asio::buffer(static_cast<void*>(buf.get()),
     BUF_SIZE_BYTES);

  // Step 3. 'input_buf' is the representation of the buffer
  // 'buf' that can be used in Boost.Asio input operations.
  
  return 0;
}

Both the samples look quite simple and straightforward; however, they contain some subtleties, which are important to understand so that we can properly use buffers with Boost.Asio. In this section, we'll see how each sample works in detail.

template<typename ConstBufferSequence>
std::size_t send(const ConstBufferSequence & buffers);

asio::const_buffer asio_buf(buf.c_str(), buf.length());
std::vector<asio::const_buffer> buffers_sequence;
buffers_sequence.push_back(asio_buf);

asio::const_buffers_1 output_buf = asio::buffer(buf);