title: When do I call boost::asio::streambuf::consume() and boost::asio::streambuf::commit()?
body: <p>I'm trying to understand the <code>boost::asio::streambuf::consume()</code> and <code>boost::asio::streambuf::commit()</code> calls. In the docs, we have the examples, </p>
  
  <pre><code>boost::asio::streambuf b;
  std::ostream os(&amp;b);
  os &lt;&lt; "Hello, World!\n";
  
  // try sending some data in input sequence
  size_t n = sock.send(b.data());
  
  b.consume(n); // sent data is removed from input sequence
  </code></pre>
  
  <p>and </p>
  
  <pre><code>boost::asio::streambuf b;
  
  // reserve 512 bytes in output sequence
  boost::asio::streambuf::mutable_buffers_type bufs = b.prepare(512);
  
  size_t n = sock.receive(bufs);
  
  // received data is "committed" from output sequence to input sequence
  b.commit(n);
  
  std::istream is(&amp;b);
  std::string s;
  is &gt;&gt; s;
  </code></pre>
  
  <p>I understand these two calls as much as I understand what the documentation says about them - call <code>consume()</code> to remove characters from the input sequence inside the <code>boost::asio::streambuf</code>, and call <code>commit()</code> to move characters from <code>boost::asio::streambuf</code>'s output sequence to its input sequence. Fair enough.</p>
  
  <p>When do I <em>actually</em> call these? Looking at the <code>boost::asio::read_until()</code> source, we have</p>
  
  <pre><code>template &lt;typename SyncReadStream, typename Allocator&gt;
  std::size_t read_until(SyncReadStream&amp; s,
      boost::asio::basic_streambuf&lt;Allocator&gt;&amp; b, char delim,
      boost::system::error_code&amp; ec)
  {
    std::size_t search_position = 0;
    for (;;)
    {
      // Determine the range of the data to be searched.
      typedef typename boost::asio::basic_streambuf&lt;
        Allocator&gt;::const_buffers_type const_buffers_type;
      typedef boost::asio::buffers_iterator&lt;const_buffers_type&gt; iterator;
      const_buffers_type buffers = b.data();
      iterator begin = iterator::begin(buffers);
      iterator start_pos = begin + search_position;
      iterator end = iterator::end(buffers);
  
      // Look for a match.
      iterator iter = std::find(start_pos, end, delim);
      if (iter != end)
      {
        // Found a match. We're done.
        ec = boost::system::error_code();
        return iter - begin + 1;
      }
      else
      {
        // No match. Next search can start with the new data.
        search_position = end - begin;
      }
  
      // Check if buffer is full.
      if (b.size() == b.max_size())
      {
        ec = error::not_found;
        return 0;
      }
  
      // Need more data.
      std::size_t bytes_to_read = read_size_helper(b, 65536);
      b.commit(s.read_some(b.prepare(bytes_to_read), ec));
      if (ec)
        return 0;
    }
  }
  </code></pre>
  
  <p>You can see that, as the documentation says, <code>boost::asio::read_until()</code> is implemented in terms of <code>SyncReadStream</code>'s <code>read_some()</code>. </p>
  
  <p>To me, that says that</p>
  
  <ol>
  <li><code>SyncReadStream::read_some()</code> does NOT call <code>boost::asio::streambuf::commit()</code></li>
  <li><code>boost::asio::read_until()</code> DOES call <code>boost::asio::streambuf::commit()</code></li>
  <li>Neither of these seem to be documented - neither in <code>boost::asio::read_until()</code>'s documentation, nor in <code>SyncReadStream</code>'s docs.</li>
  <li>I don't know whether I'm supposed to be calling <code>boost::asio::streambuf::commit()</code> at all? </li>
  </ol>
  
  <p>With my synchronous code I certainly don't seem to need it, not when I'm calling the free functions <code>boost::asio::read()</code> and <code>boost::asio::read_until()</code>. I have it in my async code in my handlers mostly because the examples I used had it, but I'm not sure about calling it then, either. When I try to use a <code>boost::asio::streambuf</code> with <code>stringstream</code>'s and <code>std::string</code>'s, <code>commit()</code> doesn't seem to play a role - nothing gets halted or stuck without calling <code>commit()</code> on the <code>streambuf</code>.</p>
  
  <p>Can anyone sort this out for me?</p>