c++ - When do I call boost::asio::streambuf::consume() and boost::asio::streambuf::commit()? -

i'm trying understand boost::asio::streambuf::consume() , boost::asio::streambuf::commit() calls. in docs, have examples,

boost::asio::streambuf b; std::ostream os(&b); os << "hello, world!\n";  // try sending data in input sequence size_t n = sock.send(b.data());  b.consume(n); // sent data removed input sequence 

and

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 "committed" output sequence input sequence b.commit(n);  std::istream is(&b); std::string s; >> s; 

i understand these 2 calls as understand documentation says them - call consume() remove characters input sequence inside boost::asio::streambuf, , call commit() move characters boost::asio::streambuf's output sequence input sequence. fair enough.

when actually call these? looking @ boost::asio::read_until() source, have

template <typename syncreadstream, typename allocator> std::size_t read_until(syncreadstream& s,     boost::asio::basic_streambuf<allocator>& b, char delim,     boost::system::error_code& ec) {   std::size_t search_position = 0;   (;;)   {     // determine range of data searched.     typedef typename boost::asio::basic_streambuf<       allocator>::const_buffers_type const_buffers_type;     typedef boost::asio::buffers_iterator<const_buffers_type> iterator;     const_buffers_type buffers = b.data();     iterator begin = iterator::begin(buffers);     iterator start_pos = begin + search_position;     iterator end = iterator::end(buffers);      // match.     iterator iter = std::find(start_pos, end, delim);     if (iter != end)     {       // found match. we're done.       ec = boost::system::error_code();       return iter - begin + 1;     }     else     {       // no match. next search can start new data.       search_position = end - begin;     }      // check if buffer 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;   } } 

you can see that, documentation says, boost::asio::read_until() implemented in terms of syncreadstream's read_some().

to me, says that

1. syncreadstream::read_some() not call boost::asio::streambuf::commit()
2. boost::asio::read_until() call boost::asio::streambuf::commit()
3. neither of these seem documented - neither in boost::asio::read_until()'s documentation, nor in syncreadstream's docs.
4. i don't know whether i'm supposed calling boost::asio::streambuf::commit() @ all?

with synchronous code don't seem need it, not when i'm calling free functions boost::asio::read() , boost::asio::read_until(). have in async code in handlers because examples used had it, i'm not sure calling then, either. when try use boost::asio::streambuf stringstream's , std::string's, commit() doesn't seem play role - nothing gets halted or stuck without calling commit() on streambuf.

can sort out me?

asio defines number of auxiliary free functions (read_xxx) accept asio::streambuf, , care prepare , commit it.

on other hand, if you'd use asio::streambuf lower-level functions accept model of mutablebuffersequence concept, have call streambuf::prepare(), returns objects meets mutablebuffersequence concept, pass object buffer, , after function fills - call commit().

in both cases, after you've read n bytes of data streambuf, have call consume(n) - in order consume input sequence.