The urdl::read_stream class allows applications to use Urdl's functionality in conjunction with Boost.Asio.

To synchronously open a URL, we may use:

// For urdl::read_stream.
#include <urdl/read_stream.hpp>

...

boost::asio::io_service io_service;

...

// An urdl::read_stream must always have an associated io_service.
urdl::read_stream stream(io_service);

// Open the URL synchronously. Throws boost::system::system_error on failure.
stream.open("http://somehost/path");

...

// Alternatively, open the URL synchronously without throwing on error.
boost::system::error_code ec;
stream.open("http://somehost/path", ec);

To asynchronously open a URL, we can write:

void open_handler(const boost::system::error_code& ec)
{
  if (ec)
  {
    // URL successfully opened.
    ...
  }
  else
  {
    std::cerr << "Unable to open URL: ";
    std::cerr << is.error().message() << std::endl;
  }
}

...

stream.async_open("http://somehost/path", open_handler);

and the callback function open_handler will be invoked once the asynchronous operation completes.

The urdl::read_stream class meets Boost.Asio's SyncReadStream and AsyncReadStream type requirements. This means we can use it with the synchronous functions boost::asio::read and boost::asio::read_until:

boost::array<char, 512> data;
boost::asio::read(stream, boost::asio::buffer(data));

...

boost::asio::streambuf buffer;
boost::asio::read_until(stream, buffer, "\r\n");

or with the asynchronous functions boost::asio::async_read and boost::asio::async_read_until:

void read_handler(const boost::system::error_code& ec, std::size_t length)
{
  ...
}

...

boost::array<char, 512> data;
boost::asio::async_read(stream, boost::asio::buffer(data), read_handler);

...

boost::asio::streambuf buffer;
boost::asio::async_read_until(stream, buffer, "\r\n", read_handler);

The asynchronous functions on the urdl::read_stream class allow concurrent access to multiple URLs without requiring additional threads. Furthermore, we can perform the operations concurrently with any of the other asynchronous facilities provided by Boost.Asio (sockets, timers and so on).