Schedule a batch of asynchronous symlink creations and opens after a precondition.

Description

Note that if creating and you don't specify a target, the target for the symlink is the precondition. On Windows directories are symlinked using a reparse point instead of a symlink due to the default lack of the SeCreateSymbolicLinkPrivilege for non-Administrative users. On Windows you can open symlinks as a file and so a valid handle is output, whereas on POSIX except for Linux you cannot do this and an invalid handle is output. 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

future dispatcher::symlink(const std::vector< path_req > & reqs, const std::vector< future<>> & targets = std::vector< future<>>())

Parameters

Returns

A batch of op handles.

Header

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

Race Guarantees

Complexity

Amortised O(N) to dispatch. Amortised O(N/threadpool) to complete if symlink creation is constant time.

Exception Model

Propagates exceptions of any input preconditions 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. Once a batch of input ops has been verified at the point of entry as not errored, you are guaranteed that the batch is atomically scheduled as a whole, unless a failure to allocate memory occurs.

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;
}