Status of proposed Boost.AFIO

There has been some interest in starting to use proposed GSoC Boost.AFIO (a batch, chainable asynchronous closure execution and asynchronous file i/o library extending Boost.ASIO) immediately before Boost GSoC 2013 is completed in September. Here are some quick notes on the library's present status:

• The pre_boost_import branch is considered stable, feature complete and ready for use using the POSIX compat backend only. To use it right now as if the Boost.AFIO master branch were ready, simply use a namespace alias to map the async_io namespace as boost::afio:

namespace boost { namespace afio = triplegit::async_io; }

Very little in terms of anything which would break source code compatibility is expected to change during the port of the existing code to Boost layout and naming. Right now that branch's current build and unit tests status on Travis CI is and its unit test code coverage is: . Click on either of the badges for details.

• The above branch requires, as an absolute minimum, variadic templates support in your compiler which means a certain minimum of C++11 support. GCC 4.6 or clang 3.x with libstdc++ 4.6 or better is absolutely plenty. For VS2012, you'll need the variadic template supporting experimental MSVC compiler or forthcoming VS2013. The build system on POSIX is scons which usually comes in your system's packages source - simply type 'scons --help' for compile options.

What is known to NOT work is libstdc++ 4.2 which is the standard C++ library supplied on FreeBSD. libcxx, its forthcoming replacement in FreeBSD 10, is as yet untested.

• Supported platforms are a subset of those for Boost.ASIO, so I duplicate here from http://www.boost.org/doc/libs/1_53_0/doc/html/boost_asio/using.html the expected platforms:

• Win32 and Win64 using Visual C++ 2013 (or VS2012 with Nov 2012 CTP compiler).

• Win32 using MinGW. Currently untested.

• Win32 using Cygwin. Currently untested.

• Linux (2.4 or 2.6 kernels) using g++ 4.6 or later (or clang++ 3.x).

• Solaris using g++ 4.6 or later (or clang++ 3.x). Currently untested.

• Mac OS X 10.4 using g++ 4.6 or later (or clang++ 3.x). Currently untested.

We also intend to add FreeBSD 10 or later as soon as it's ready.

The POSIX compat backend is straight POSIX: If your platform supports preadv() and pwritev() you're covered. If you can get a new enough compiler, I would expect that the other Boost.ASIO platforms AIX, HP-UX and Tru64 should all work. Despite having a sufficiently new compiler (GCC 4.6.2) and libstdc++ (4.6), BlackBerry 10 (QNX) is intentionally unsupported due to the wording of the excluded development legal agreement applied to one of the library's authors by his employer.

Right now the Windows IOCP backend corrupts data due to https://svn.boost.org/trac/boost/ticket/8669. You can force usage of the POSIX compat backend on Windows by defining USE_POSIX_ON_WIN32.

• Documentation is currently extremely sparse. Complete, though basic, doxygen API docs are available in the html directory. The unit tests are probably the best example of usage right now. That said usage is fairly intuitive:

using namespace triplegit::async_io;
using namespace std;

// Make a buffer to write from
vector<char> buffer(64, 'n');

// Make a dispatcher using the given thread pool and which only completes when data is definitely arrived into storage
auto dispatcher=triplegit::async_io::async_file_io_dispatcher(triplegit::async_io::process_threadpool(), triplegit::async_io::file_flags::OSSync);
std::cout << "\n\nTesting synchronous directory and file creation:\n";

// Schedule an asynchronous directory creation
auto mkdir(dispatcher->dir(async_path_op_req("testdir", file_flags::Create)));

// Schedule an asynchronous file creation and open to occur after the directory creation
auto mkfile(dispatcher->file(async_path_op_req(mkdir, "testdir/foo", file_flags::Create|file_flags::ReadWrite)));

// Schedule an asynchronous write to previously opened file once it has opened
auto writefile1(dispatcher->write(async_data_op_req<vector<char>>(mkfile, buffer, 0)));

// Schedule an asynchronous fsync() once the previous write has completed
auto sync1(dispatcher->sync(writefile1));

// Schedule an asynchronous write to previously opened file once the previous fsync() completes
auto writefile2(dispatcher->write(async_data_op_req<vector<char>>(sync1, buffer, 0)));

// Schedule an asynchronous close of the previously opened file once the previous write completes
auto closefile(dispatcher->close(writefile2));

// Schedule an asynchronous deletion of a file once the previous file close completes
auto delfile(dispatcher->rmfile(async_path_op_req(closefile, "testdir/foo")));

// Schedule an asynchronous deletion of a directory once the previous file deletion completes
auto deldir(dispatcher->rmdir(async_path_op_req(delfile, "testdir")));

// Create a future representing the op or iterator range of ops passed to when_all(), and wait for a result. This will return any exceptions thrown from only what is passed to it, so if you pass deldir, only an exception from that and that alone will appear here. You can add more items to retrieve more error states.
when_all(deldir).wait();