If your application must record data, generate web pages or write logs without slowing down, you might benefit from an asynchronous wrapper for std::ostream, which was specifically optimized for latency.

It: * is almost a drop-in replacement for std::ostream in this regard, * acts as AsyncWriteStream with Boost.Asio (but it works without Asio too), * uses Boost.Asio background thread(s) (but again, it can work without Asio too).

```

// EXAMPLE

// if you don't have it yet, create a service and spawn a background thread // (you don't have to use Boost.Asio -- you can write your own async_ostream::service) boost::asio::io_service service; boost::asio::io_service::work background_thread_return_prevention(service); boost::thread bg(boost::bind(&boost::asio::io_service::work, &service));

// say, we have some ostream that we have to write into std::ofstream output("hello.world");

// wrap that ostream into an asynchronous wrapper async_ostream::stream async_output(output, service);

// use it as you would use a regular std::ostream async_output << "Hello world!" << std::endl << "I am using async_ostream and two plus two = " << 4 << std::endl; // the whole line above only takes 580 cycles (= 200 nanoseconds)! // to compare, doing the same with std::ofstream takes 16,000 cycles (and 2,700 cycles if std::endl are replaced with \n) // it can be done in 80 cycles (i.e. <30 nanos) -- please feel free to read the ExamplesAndPerformance page

// you can also use an async_ostream::stream as a first argument to any signature of boost::asio::async_write boost::asio::async_write( async_output, your_choice_of_buffers_with_unformatted_char_star_data_and_size, your_choice_of_write_handler);

```

For asynchronous reading example, see Asynchrnonous Reading.

This library is supposed to work with all Sinks and Devices from Boost.Iostreams, and the author highly recommends Boost.Iostreams for most purposes that involve input and output streams (formatted and not).

Performance

Because all the expensive work (especially, formatting!) happens on a background thread, writing into an async-ostream wrapper is almost always much faster than into a corresponding std::ostream. Depending on what's being written, and when it's written we see a latency decrease factor of 200, 10 or worst case 1.5 (which happens on some platforms with "cold" writing of very small data types such as double). Please refer to the "ExamplesAndPerformance" wiki page or just run "make test" yourself.

So far I only tested the library on two platforms: * GCC 4.6 + Linux 3.3.8-gentoo + Intel Westmere, * MSVC 11 + Windows 7 + Intel Core-i7, so it would be fantastic if you have more platforms to test it on (just run "make test" and publish the results here).

The performance gain gets even higher with "smarter" streams that take longer to write into, e.g. as those that you get out of boost::iostreams::basic_gzip_compressor. And notable exceptions are std::string and char* which don't experience any performance improvement because they are formatted already.

Installation

The async-ostream library depends on Boost libraries quite seriously. So it must either be downloaded together with pre-built Boost or Boost must be installed separately.

Step 1: you have two options to download the library * if you don't have Boost, but have a GCC 4.7 or Microsoft Visual Studio 2012, download the library together with pre-built Boost 1.54: http://async-ostream.googlecode.com/svn/async_ostream_0_4_w_boost.tar.gz * if you already have Boost and/or want to use some other compiler (or if you are not comfortable linking with somebody else's unverified binary code), download source-code-only from here: http://async-ostream.googlecode.com/svn/async_ostream_0_4_no_boost.tar.gz, and change the values of BOOST_DIR and BOOST_LIBPATH in makefile.base file

Step 2: unpack the downloaded file, and then you also have two options * if you have make utility, you can type: "make libs" (to make the library), "make test" (to run the tests) or "make install" (to install the library into your /usr/lib directory). * if you have Visual Studio 2012 you can open async_ostream_tests.sln file and build both the library and the tests.

Acknowledgements

I would like to thank: * Rob Douglas for inspiration in the design of the library (the set of tricks to make it act as a drop-in replacement of std::ostream) here, * Roland Conybeare for ideas with "teeth" of the library (avoidance of dynamic allocation, which otherwise is the main bottleneck), * Bjorn Reese for the idea to re-use the thread(s) running boost::asio::io_service instead of adding new thread(s)