Asynchronous file creation and open after an optional precondition.

Description

Be aware that any files created are by default sparse if supported on the local filing system. On Windows opening any file for writing converts it to sparse. Use file_flags::no_sparse to prevent this on those filing systems which permit it. Related types: path_req Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by afio::path in NT kernel namespace paths. normalise_path() can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage.

Synopsis

template<class T, typename>
future async_file(T _path, file_flags _flags = file_flags::none)

Parameters

Returns

A future<void>

Header

#include <boost/afio/v2/afio.hpp>

Race Guarantees

Complexity

Amortised O(1) to dispatch. Amortised O(1) to complete if file creation is constant time.

Exception Model

Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a std::invalid_argument if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory.

Example

using namespace BOOST_AFIO_V2_NAMESPACE;
using BOOST_AFIO_V2_NAMESPACE::rmdir;
std::shared_ptr<boost::afio::dispatcher> dispatcher =
boost::afio::make_dispatcher().get();
current_dispatcher_guard h(dispatcher);

// Free function
try
{
  // Schedule creating a directory called testdir
  auto mkdir(async_dir("testdir", boost::afio::file_flags::create));
  // Schedule creating a file called testfile in testdir only when testdir has been
  // created
  auto mkfile(async_file(mkdir, "testfile", boost::afio::file_flags::create));
  // Schedule creating a symbolic link called linktodir to the item referred to by
  // the precondition
  // i.e. testdir. Note that on Windows you can only symbolic link directories.
  auto mklink(
  async_symlink(mkdir, "linktodir", mkdir, boost::afio::file_flags::create));

  // Schedule deleting the symbolic link only after when it has been created
  auto rmlink(async_rmsymlink(mklink));
  // Schedule deleting the file only after when it has been created
  auto rmfile(async_close(async_rmfile(mkfile)));
  // Schedule waiting until both the preceding operations have finished
  auto barrier(dispatcher->barrier({rmlink, rmfile}));
  // Schedule deleting the directory only after the barrier completes
  auto rmdir(async_rmdir(depends(barrier.front(), mkdir)));
  // Check ops for errors
  boost::afio::when_all_p(mkdir, mkfile, mklink, rmlink, rmfile, rmdir).wait();
}
catch(...)
{
  std::cerr << boost::current_exception_diagnostic_information(true) << std::endl;
  throw;
}

// Batch
try
{
  // Schedule creating a directory called testdir
  auto mkdir(
  dispatcher->dir(std::vector<boost::afio::path_req>(
                  1, boost::afio::path_req(
                     "testdir", boost::afio::file_flags::create))).front());
  // Schedule creating a file called testfile in testdir only when testdir has been
  // created
  auto mkfile(dispatcher->file(std::vector<boost::afio::path_req>(
                               1, boost::afio::path_req::relative(
                                  mkdir, "testfile",
                                  boost::afio::file_flags::create))).front());
  // Schedule creating a symbolic link called linktodir to the item referred to by
  // the precondition
  // i.e. testdir. Note that on Windows you can only symbolic link directories.
  // Note that creating
  // symlinks must *always* be as an absolute path, as that is how they are stored.
  auto mklink(dispatcher->symlink(std::vector<boost::afio::path_req>(
                                  1, boost::afio::path_req::absolute(
                                     mkdir, "testdir/linktodir",
                                     boost::afio::file_flags::create))).front());

  // Schedule deleting the symbolic link only after when it has been created
  auto rmlink(dispatcher->close(std::vector<future<>>(
                                1, dispatcher->rmsymlink(mklink))).front());
  // Schedule deleting the file only after when it has been created
  auto rmfile(
  dispatcher->close(std::vector<future<>>(1, dispatcher->rmfile(mkfile))).front());
  // Schedule waiting until both the preceding operations have finished
  auto barrier(dispatcher->barrier({rmlink, rmfile}));
  // Schedule deleting the directory only after the barrier completes
  auto rmdir(
  dispatcher->rmdir(std::vector<path_req>(
                    1, dispatcher->depends(barrier.front(), mkdir))).front());
  // Check ops for errors
  boost::afio::when_all_p(mkdir, mkfile, mklink, rmlink, rmfile, rmdir).wait();
}
catch(...)
{
  std::cerr << boost::current_exception_diagnostic_information(true) << std::endl;
  throw;
}