AFIO single page cheat sheet for the very impatient

AFIO models file descriptors/handles as a reference counted std::shared_ptr<handle> (aliased as afio::handle_ptr) where handle is an opaque abstract base class. handle may, or may not, refer to a currently open file descriptor/handle i.e. it is possible to close it before the reference count reaches zero. You can create your own custom implementations of handle.
AFIO models a filesystem as a reference counted std::shared_ptr<dispatcher> (aliased as afio::dispatcher_ptr) where dispatcher is also an opaque abstract base class. When constructed using make_dispatcher() you specify a URI such as file:/// which specifies what namespace the dispatcher will dispatch onto. You can create your own custom dispatcher implementations for some URI regex pattern too.
AFIO provides its own custom future type afio::future<T><T = void> which always represents a future handle_ptr plus an optional T which is usually void (hence defaulting T to void). This custom future type is implemented using Boost.Outcome's lightweight monadic future factory toolkit, and therefore provides all the C++ 1z Concurrency TS and Boost.Thread extensions including continuations and wait composure. Note that lightweight futures can carry an error_code as well as an exception_ptr, and therefore much of the need for non-throwing error_code taking API overloads is not needed (though any function not returning a future still uses that idiom).

AFIO provides its own custom filesystem path type afio::path which is a thin wrap of your STL/Boost Filesystem path. This is done because on Microsoft Windows, AFIO always uses NT kernel paths, never Win32 paths. By skipping the Win32 translation layer one achieves significantly better performance and much closer to POSIX semantics including case sensitivity, plus there are no issues with path length limits. On Windows afio::path (NT kernel paths) will usually auto convert to and from filesystem::path (Win32 paths), however do note there is not always a one to one mapping from a NT kernel path to a Win32 path in which case the Win32 paths to send in will never be the Win32 paths you get out. See the documentation for path.

	Caution
	Until issue #79 is resolved, don't do directory enumerations from an x86 binary on a x64 Windows system. This is due to a bug in Microsoft's WOW64 syscall translation layer which Microsoft have decided is wontfix.

Error reporting always follows the “earliest possible reporting” rule. As absolutely everything is asynchronous in AFIO, that also means that error and exception handling also occurs asynchronously. So if you try to use a future as an input and that future is errored at the point of use, the errored state is immediately rethrown. As futures may become errored asynchronously, that means you must always write code which assumes any API which consumes a future can throw (unless you know for a fact the future is ready and not errored).

	Note
	Gathering error states from many futures at once is made easier using the `when_all_p()` (when all propagating) extended wait composure function from Boost.Outcome — this propagates any error in any of the entry futures into the composed output future, thus saving you having to check the futures for errors by hand.

Handles to directories may ignore requests to close them i.e. handle_ptr->close() is a no-op. This is due to a performance feature called “directory handle caching” which shares read-only directory handles amongst all users unless specifically requested not to do so. You can test for this using the available_to_directory_cache() member function of handle.
As a general rule, AFIO spots when you try to delete a currently open file handle where that is illegal on your platform (Microsoft Windows) and will instead rename the file to a cryptographically strong random name of the form <32 chars of random hex>.afiod and ask the operating system to delete it later when the last handle is closed. Any enumerations of directories containing these randomised named files will omit those entries by default. This emulates POSIX semantics, albeit imperfectly. One caveat is it cannot always do this with directories, though it tries hard to try again later where it can. A future version of AFIO will add tmpfs support which will let us relocate troublesome directories into the temp directory where they can be deleted much later, thus more closely matching POSIX semantics still further.

Boost.AFIO version 1.4 provides the following operations:

Operation	Asynchronous batch `dispatcher` functions	Synchronous `handle` functions	Asynchronous free functions	Synchronous free functions	Related types
Open/create a directory: `dir()`	1		2	4	`path_req`
Delete a directory: `rmdir()`	1		2	4	`path_req`
Open/create a file: `file()`	1		2	4	`path_req`
Delete a file: `rmfile()`	1		2	4	`path_req`
Open/create a symlink: `symlink()`	1		2	4	`path_req`
Delete a symlink: `rmsymlink()`	1		2	4	`path_req`
Synchronise changes to physical storage: `sync()`	1		1	2
Deallocate/zero physical storage: `zero()`	1		1	2
Close a fd/handle: `close()`	1		1	2
Scatter read file contents: `read()`	1		2	4	`io_req`
Gather write file contents: `write()`	1		2	4	`io_req`
Set maximum file extent: `truncate()`	1		1	2
Enumerate directory contents/ fetch file metadata: `enumerate()`	1		3	6	`enumerate_req`, `directory_entry`, `stat_t`
Enumerate file physical storage extents: `extents()`	1		1	2
Examine mounted storage volume: `statfs()`	1		1	2	`statfs_t`
Get current path of an open fd/handle even if other processes are renaming it (Linux, Windows; FreeBSD directories only; not OS X): `path()`		2			`path`
Get open fd/handle metadata: `direntry()`, `lstat()`		2			`directory_entry`, `stat_t`
Get target path of a symlink: `target()`		1
Map a read-only file into memory: `try_mapfile()`		1
Hard link an open fd/handle to a new path: `link()`		1			`path_req`
Unlink an open fd/handle from its existing path (caution!): `unlink()`		1			`path_req`
Strong guaranteed atomically relink an open fd/handle from its existing path to a different path: `atomic_relink()`		1			`path_req`

Planned new operations coming next version of AFIO so you know what's coming next:

Mutual exclusion and locking which works across NFS and Samba:
- The ability to tag many handle's with what locking to do per operation.
- Asynchronous exclusive lock files.
- Asynchronous multi-file byte range locking.
- Individual file change monitoring (needed to implement locking).
tmp:// URI backend for a temporary file filesystem.
Optional inline hashing of file reads and writes with SpookyHash/Blake2b/SHA256.
Maybe Boost.Fiber support to gain coroutines on all compilers.