AFIO  v2.00 late alpha
afio_v2_xxx Namespace Reference

The AFIO namespace. More...

Namespaces

 algorithm
 Collection of file system based algorithms.
 
 path_discovery
 Contains functions used to discover suitable paths for things.
 
 storage_profile
 YAML databaseable empirical testing of a storage's behaviour.
 
 utils
 Utility routines often useful when using AFIO.
 

Classes

class  async_file_handle
 An asynchronous handle to an open something. More...
 
struct  construct
 Metaprogramming shim for constructing any handle subclass. More...
 
struct  construct< algorithm::cached_parent_handle_adapter< T > >
 Constructor for algorithm::cached_parent_handle_adapter<T> More...
 
struct  construct< async_file_handle >
 Constructor for async_file_handle More...
 
struct  construct< directory_handle >
 Constructor for directory_handle More...
 
struct  construct< file_handle >
 Constructor for file_handle More...
 
struct  construct< map_handle >
 Constructor for map_handle More...
 
struct  construct< mapped_file_handle >
 Constructor for mapped_file_handle More...
 
struct  construct< path_handle >
 Constructor for path_handle More...
 
struct  construct< section_handle >
 Constructor for section_handle More...
 
struct  deadline
 A time deadline in either relative-to-now or absolute (system clock) terms. More...
 
struct  directory_entry
 
class  directory_handle
 A handle to a directory which can be enumerated. More...
 
class  error
 The exception type synthesised and thrown when an afio::result or afio::outcome is no-value observed. More...
 
struct  error_info
 The cause of the failure of an operation in AFIO. More...
 
class  file_handle
 A handle to a regular file or device, kept data layout compatible with async_file_handle. More...
 
class  fs_handle
 A handle to something with a device and inode number. More...
 
class  handle
 A native_handle_type which is managed by the lifetime of this object instance. More...
 
class  io_handle
 A handle to something capable of scatter-gather i/o. More...
 
class  io_service
 An asynchronous i/o multiplexer service. More...
 
class  log_level_guard
 RAII class for temporarily adjusting the log level. More...
 
class  map_handle
 A handle to a memory mapped region of memory. More...
 
class  mapped_file_handle
 A memory mapped regular file or device. More...
 
struct  native_handle_type
 A native handle type used for wrapping file descriptors, process ids or HANDLEs. Unmanaged, wrap in a handle object to manage. More...
 
class  path_handle
 A handle to somewhere originally identified by a path on the filing system. Typically used as the lightest weight handle to some location on the filing system which may unpredictably relocate over time. This handle is thus an anchor to a subset island of the filing system, free of any race conditions introduced by third party changes to any part of the path leading to that island. More...
 
struct  path_hasher
 
class  path_view
 A borrowed view of a path. A lightweight trivial-type alternative to std::filesystem::path. More...
 
class  section_handle
 A handle to a source of mapped memory. More...
 
struct  stat_t
 Metadata about a directory entry. More...
 
struct  statfs_t
 Metadata about a filing system. Unsupported entries are all bits set. More...
 

Typedefs

template<class T >
using result = OUTCOME_V2_NAMESPACE::result< T, error_info >
 
template<class T >
using outcome = OUTCOME_V2_NAMESPACE::outcome< T, error_info >
 
using log_level = QUICKCPPLIB_NAMESPACE::ringbuffer_log::level
 Enum for the log level.
 

Functions

void swap (async_file_handle &self, async_file_handle &o) noexcept
 Swap with another instance.
 
result< async_file_handleasync_file (io_service &service, const path_handle &base, async_file_handle::path_view_type _path, async_file_handle::mode _mode=async_file_handle::mode::read, async_file_handle::creation _creation=async_file_handle::creation::open_existing, async_file_handle::caching _caching=async_file_handle::caching::only_metadata, async_file_handle::flag flags=async_file_handle::flag::none) noexcept
 
result< async_file_handleasync_random_file (io_service &service, const path_handle &dirpath, async_file_handle::mode _mode=async_file_handle::mode::write, async_file_handle::caching _caching=async_file_handle::caching::only_metadata, async_file_handle::flag flags=async_file_handle::flag::none) noexcept
 
result< async_file_handleasync_temp_file (io_service &service, async_file_handle::path_view_type name=async_file_handle::path_view_type(), async_file_handle::mode _mode=async_file_handle::mode::write, async_file_handle::creation _creation=async_file_handle::creation::if_needed, async_file_handle::caching _caching=async_file_handle::caching::only_metadata, async_file_handle::flag flags=async_file_handle::flag::unlink_on_close) noexcept
 
result< async_file_handleasync_temp_inode (io_service &service, const path_handle &dir=path_discovery::storage_backed_temporary_files_directory(), async_file_handle::mode _mode=async_file_handle::mode::write, async_file_handle::flag flags=async_file_handle::flag::none) noexcept
 
async_file_handle::io_result< async_file_handle::const_buffers_type > barrier (async_file_handle &self, async_file_handle::io_request< async_file_handle::const_buffers_type > reqs=async_file_handle::io_request< async_file_handle::const_buffers_type >(), bool wait_for_device=false, bool and_metadata=false, deadline d=deadline()) noexcept
 
result< async_file_handle::awaitable< async_file_handle::buffers_type > > co_read (async_file_handle &self, async_file_handle::io_request< async_file_handle::buffers_type > reqs) noexcept
 Schedule a read to occur asynchronously. More...
 
result< async_file_handle::awaitable< async_file_handle::const_buffers_type > > co_write (async_file_handle &self, async_file_handle::io_request< async_file_handle::const_buffers_type > reqs) noexcept
 Schedule a write to occur asynchronously. More...
 
bool operator== (const error_info &a, const error_info &b)
 
bool operator!= (const error_info &a, const error_info &b)
 
std::ostream & operator<< (std::ostream &s, const error_info &v)
 
std::error_code make_error_code (error_info ei)
 
void throw_as_system_error_with_payload (const error_info &ei)
 
QUICKCPPLIB_NAMESPACE::ringbuffer_log::simple_ringbuffer_log< AFIO_LOGGING_MEMORY > & log () noexcept
 The log used by AFIO.
 
std::ostream & operator<< (std::ostream &s, const directory_handle::filter &v)
 
std::ostream & operator<< (std::ostream &s, const directory_handle::enumerate_info &)
 
void swap (directory_handle &self, directory_handle &o) noexcept
 Swap with another instance.
 
result< directory_handledirectory (const path_handle &base, directory_handle::path_view_type _path, directory_handle::mode _mode=directory_handle::mode::read, directory_handle::creation _creation=directory_handle::creation::open_existing, directory_handle::caching _caching=directory_handle::caching::all, directory_handle::flag flags=directory_handle::flag::none) noexcept
 
result< directory_handlerandom_directory (const path_handle &dirpath, directory_handle::mode _mode=directory_handle::mode::write, directory_handle::caching _caching=directory_handle::caching::temporary, directory_handle::flag flags=directory_handle::flag::none) noexcept
 
result< directory_handletemp_directory (directory_handle::path_view_type name=directory_handle::path_view_type(), directory_handle::mode _mode=directory_handle::mode::write, directory_handle::creation _creation=directory_handle::creation::if_needed, directory_handle::caching _caching=directory_handle::caching::all, directory_handle::flag flags=directory_handle::flag::none) noexcept
 
result< directory_handle::enumerate_infoenumerate (const directory_handle &self, directory_handle::buffers_type &&tofill, directory_handle::path_view_type glob=directory_handle::path_view_type(), directory_handle::filter filtering=directory_handle::filter::fastdeleted, span< char > kernelbuffer=span< char >()) noexcept
 
void swap (file_handle &self, file_handle &o) noexcept
 Swap with another instance.
 
result< file_handlefile (const path_handle &base, file_handle::path_view_type _path, file_handle::mode _mode=file_handle::mode::read, file_handle::creation _creation=file_handle::creation::open_existing, file_handle::caching _caching=file_handle::caching::all, file_handle::flag flags=file_handle::flag::none) noexcept
 
result< file_handlerandom_file (const path_handle &dirpath, file_handle::mode _mode=file_handle::mode::write, file_handle::caching _caching=file_handle::caching::temporary, file_handle::flag flags=file_handle::flag::none) noexcept
 
result< file_handletemp_file (file_handle::path_view_type name=file_handle::path_view_type(), file_handle::mode _mode=file_handle::mode::write, file_handle::creation _creation=file_handle::creation::if_needed, file_handle::caching _caching=file_handle::caching::temporary, file_handle::flag flags=file_handle::flag::unlink_on_close) noexcept
 
result< file_handletemp_inode (const path_handle &dir=path_discovery::storage_backed_temporary_files_directory(), file_handle::mode _mode=file_handle::mode::write, file_handle::flag flags=file_handle::flag::none) noexcept
 
result< file_handle::extent_type > length (const file_handle &self) noexcept
 
result< file_handle::extent_type > truncate (file_handle &self, file_handle::extent_type newsize) noexcept
 
result< std::vector< std::pair< file_handle::extent_type, file_handle::extent_type > > > extents (const file_handle &self) noexcept
 Returns a list of currently valid extents for this open file. WARNING: racy!
 
result< file_handle::extent_type > zero (file_handle &self, file_handle::extent_type offset, file_handle::extent_type bytes, deadline d=deadline()) noexcept
 Efficiently zero, and possibly deallocate, data on storage. More...
 
result< void > relink (fs_handle &self, const path_handle &base, fs_handle::path_view_type newpath, bool atomic_replace=true, deadline d=std::chrono::seconds(30)) noexcept
 
result< void > unlink (fs_handle &self, deadline d=std::chrono::seconds(30)) noexcept
 
std::ostream & operator<< (std::ostream &s, const handle &v)
 
std::ostream & operator<< (std::ostream &s, const handle::mode &v)
 
std::ostream & operator<< (std::ostream &s, const handle::creation &v)
 
std::ostream & operator<< (std::ostream &s, const handle::caching &v)
 
std::ostream & operator<< (std::ostream &s, const handle::flag &v)
 
io_handle::io_result< io_handle::buffers_typeread (io_handle &self, io_handle::io_request< io_handle::buffers_type > reqs, deadline d=deadline()) noexcept
 Read data from the open handle. More...
 
io_handle::io_result< io_handle::const_buffers_typewrite (io_handle &self, io_handle::io_request< io_handle::const_buffers_type > reqs, deadline d=deadline()) noexcept
 Write data to the open handle. More...
 
io_handle::io_result< io_handle::const_buffers_typebarrier (io_handle &self, io_handle::io_request< io_handle::const_buffers_type > reqs=io_handle::io_request< io_handle::const_buffers_type >(), bool wait_for_device=false, bool and_metadata=false, deadline d=deadline()) noexcept
 Issue a write reordering barrier such that writes preceding the barrier will reach storage before writes after this barrier. More...
 
void swap (section_handle &self, section_handle &o) noexcept
 Swap with another instance.
 
result< section_handle::extent_type > length (const section_handle &self) noexcept
 Return the current maximum permitted extent of the memory section.
 
result< section_handle::extent_type > truncate (section_handle &self, section_handle::extent_type newsize=0) noexcept
 
void swap (map_handle &self, map_handle &o) noexcept
 Swap with another instance.
 
result< void > close (map_handle &self) noexcept
 Unmap the mapped view.
 
map_handle::io_result< map_handle::const_buffers_type > barrier (map_handle &self, map_handle::io_request< map_handle::const_buffers_type > reqs=map_handle::io_request< map_handle::const_buffers_type >(), bool wait_for_device=false, bool and_metadata=false, deadline d=deadline()) noexcept
 
result< map_handlemap (map_handle::size_type bytes, section_handle::flag _flag=section_handle::flag::readwrite) noexcept
 
result< map_handlemap (section_handle &section, map_handle::size_type bytes=0, map_handle::extent_type offset=0, section_handle::flag _flag=section_handle::flag::readwrite) noexcept
 
map_handle::size_type length (const map_handle &self) noexcept
 The size of the memory map.
 
map_handle::io_result< map_handle::buffers_type > read (map_handle &self, map_handle::io_request< map_handle::buffers_type > reqs, deadline d=deadline()) noexcept
 Read data from the mapped view. More...
 
map_handle::io_result< map_handle::const_buffers_type > write (map_handle &self, map_handle::io_request< map_handle::const_buffers_type > reqs, deadline d=deadline()) noexcept
 Write data to the mapped view. More...
 
void swap (mapped_file_handle &self, mapped_file_handle &o) noexcept
 Swap with another instance.
 
result< mapped_file_handlemapped_file (mapped_file_handle::size_type reservation, const path_handle &base, mapped_file_handle::path_view_type _path, mapped_file_handle::mode _mode=mapped_file_handle::mode::read, mapped_file_handle::creation _creation=mapped_file_handle::creation::open_existing, mapped_file_handle::caching _caching=mapped_file_handle::caching::all, mapped_file_handle::flag flags=mapped_file_handle::flag::none) noexcept
 
result< mapped_file_handlemapped_file (const path_handle &base, mapped_file_handle::path_view_type _path, mapped_file_handle::mode _mode=mapped_file_handle::mode::read, mapped_file_handle::creation _creation=mapped_file_handle::creation::open_existing, mapped_file_handle::caching _caching=mapped_file_handle::caching::all, mapped_file_handle::flag flags=mapped_file_handle::flag::none) noexcept
 
result< mapped_file_handlemapped_random_file (mapped_file_handle::size_type reservation, const path_handle &dirpath, mapped_file_handle::mode _mode=mapped_file_handle::mode::write, mapped_file_handle::caching _caching=mapped_file_handle::caching::temporary, mapped_file_handle::flag flags=mapped_file_handle::flag::none) noexcept
 
result< mapped_file_handlemapped_temp_file (mapped_file_handle::size_type reservation, mapped_file_handle::path_view_type name=mapped_file_handle::path_view_type(), mapped_file_handle::mode _mode=mapped_file_handle::mode::write, mapped_file_handle::creation _creation=mapped_file_handle::creation::if_needed, mapped_file_handle::caching _caching=mapped_file_handle::caching::temporary, mapped_file_handle::flag flags=mapped_file_handle::flag::unlink_on_close) noexcept
 
result< mapped_file_handlemapped_temp_inode (const path_handle &dir=path_discovery::storage_backed_temporary_files_directory(), mapped_file_handle::mode _mode=mapped_file_handle::mode::write, mapped_file_handle::flag flags=mapped_file_handle::flag::none) noexcept
 
result< path_handlepath (const path_handle &base, path_handle::path_view_type _path) noexcept
 
result< path_handlepath (path_handle::path_view_type _path) noexcept
 
constexpr bool operator== (path_view x, path_view y) noexcept
 
constexpr bool operator!= (path_view x, path_view y) noexcept
 
constexpr bool operator< (path_view x, path_view y) noexcept
 
constexpr bool operator> (path_view x, path_view y) noexcept
 
constexpr bool operator<= (path_view x, path_view y) noexcept
 
constexpr bool operator>= (path_view x, path_view y) noexcept
 
std::ostream & operator<< (std::ostream &s, const path_view &v)
 

Detailed Description

The AFIO namespace.

Todo:
TODO FIXME Replace in-memory log with memory map file backed log.

Function Documentation

◆ async_file()

result<async_file_handle> afio_v2_xxx::async_file ( io_service service,
const path_handle base,
async_file_handle::path_view_type  _path,
async_file_handle::mode  _mode = async_file_handle::mode::read,
async_file_handle::creation  _creation = async_file_handle::creation::open_existing,
async_file_handle::caching  _caching = async_file_handle::caching::only_metadata,
async_file_handle::flag  flags = async_file_handle::flag::none 
)
inlinenoexcept

Create an async file handle opening access to a file on path using the given io_service.

Parameters
serviceThe io_service to use.
baseHandle to a base location on the filing system. Pass {} to indicate that path will be absolute.
_pathThe path relative to base to open.
_modeHow to open the file.
_creationHow to create the file.
_cachingHow to ask the kernel to cache the file.
flagsAny additional custom behaviours.
Errors returnable
Any of the values POSIX open() or CreateFile() can return.
590 {
591  return async_file_handle::async_file(std::forward<decltype(service)>(service), std::forward<decltype(base)>(base), std::forward<decltype(_path)>(_path), std::forward<decltype(_mode)>(_mode), std::forward<decltype(_creation)>(_creation), std::forward<decltype(_caching)>(_caching),
592  std::forward<decltype(flags)>(flags));
593 }
result< async_file_handle > async_file(io_service &service, const path_handle &base, async_file_handle::path_view_type _path, async_file_handle::mode _mode=async_file_handle::mode::read, async_file_handle::creation _creation=async_file_handle::creation::open_existing, async_file_handle::caching _caching=async_file_handle::caching::only_metadata, async_file_handle::flag flags=async_file_handle::flag::none) noexcept
Definition: async_file_handle.hpp:588

◆ async_random_file()

result<async_file_handle> afio_v2_xxx::async_random_file ( io_service service,
const path_handle dirpath,
async_file_handle::mode  _mode = async_file_handle::mode::write,
async_file_handle::caching  _caching = async_file_handle::caching::only_metadata,
async_file_handle::flag  flags = async_file_handle::flag::none 
)
inlinenoexcept

Create an async file handle creating a randomly named file on a path. The file is opened exclusively with creation::only_if_not_exist so it will never collide with nor overwrite any existing file.

Errors returnable
Any of the values POSIX open() or CreateFile() can return.
601 {
602  return async_file_handle::async_random_file(std::forward<decltype(service)>(service), std::forward<decltype(dirpath)>(dirpath), std::forward<decltype(_mode)>(_mode), std::forward<decltype(_caching)>(_caching), std::forward<decltype(flags)>(flags));
603 }
result< async_file_handle > async_random_file(io_service &service, const path_handle &dirpath, async_file_handle::mode _mode=async_file_handle::mode::write, async_file_handle::caching _caching=async_file_handle::caching::only_metadata, async_file_handle::flag flags=async_file_handle::flag::none) noexcept
Definition: async_file_handle.hpp:600

◆ async_temp_file()

result<async_file_handle> afio_v2_xxx::async_temp_file ( io_service service,
async_file_handle::path_view_type  name = async_file_handle::path_view_type(),
async_file_handle::mode  _mode = async_file_handle::mode::write,
async_file_handle::creation  _creation = async_file_handle::creation::if_needed,
async_file_handle::caching  _caching = async_file_handle::caching::only_metadata,
async_file_handle::flag  flags = async_file_handle::flag::unlink_on_close 
)
inlinenoexcept

Create an async file handle creating the named file on some path which the OS declares to be suitable for temporary files. Most OSs are very lazy about flushing changes made to these temporary files. Note the default flags are to have the newly created file deleted on first handle close. Note also that an empty name is equivalent to calling async_random_file(path_discovery::storage_backed_temporary_files_directory()) and the creation parameter is ignored.

Note
If the temporary file you are creating is not going to have its path sent to another process for usage, this is the WRONG function to use. Use temp_inode() instead, it is far more secure.
Errors returnable
Any of the values POSIX open() or CreateFile() can return.
621 {
622  return async_file_handle::async_temp_file(std::forward<decltype(service)>(service), std::forward<decltype(name)>(name), std::forward<decltype(_mode)>(_mode), std::forward<decltype(_creation)>(_creation), std::forward<decltype(_caching)>(_caching), std::forward<decltype(flags)>(flags));
623 }
result< async_file_handle > async_temp_file(io_service &service, async_file_handle::path_view_type name=async_file_handle::path_view_type(), async_file_handle::mode _mode=async_file_handle::mode::write, async_file_handle::creation _creation=async_file_handle::creation::if_needed, async_file_handle::caching _caching=async_file_handle::caching::only_metadata, async_file_handle::flag flags=async_file_handle::flag::unlink_on_close) noexcept
Definition: async_file_handle.hpp:619

◆ async_temp_inode()

result<async_file_handle> afio_v2_xxx::async_temp_inode ( io_service service,
const path_handle dir = path_discovery::storage_backed_temporary_files_directory(),
async_file_handle::mode  _mode = async_file_handle::mode::write,
async_file_handle::flag  flags = async_file_handle::flag::none 
)
inlinenoexcept

Securely create an async file handle creating a temporary anonymous inode in the filesystem referred to by dirpath. The inode created has no name nor accessible path on the filing system and ceases to exist as soon as the last handle is closed, making it ideal for use as a temporary file where other processes do not need to have access to its contents via some path on the filing system (a classic use case is for backing shared memory maps).

Errors returnable
Any of the values POSIX open() or CreateFile() can return.
635 {
636  return async_file_handle::async_temp_inode(std::forward<decltype(service)>(service), std::forward<decltype(dir)>(dir), std::forward<decltype(_mode)>(_mode), std::forward<decltype(flags)>(flags));
637 }
result< async_file_handle > async_temp_inode(io_service &service, const path_handle &dir=path_discovery::storage_backed_temporary_files_directory(), async_file_handle::mode _mode=async_file_handle::mode::write, async_file_handle::flag flags=async_file_handle::flag::none) noexcept
Definition: async_file_handle.hpp:634

◆ barrier()

io_handle::io_result<io_handle::const_buffers_type> afio_v2_xxx::barrier ( io_handle self,
io_handle::io_request< io_handle::const_buffers_type reqs = io_handle::io_request<io_handle::const_buffers_type>(),
bool  wait_for_device = false,
bool  and_metadata = false,
deadline  d = deadline() 
)
inlinenoexcept

Issue a write reordering barrier such that writes preceding the barrier will reach storage before writes after this barrier.

Warning
Assume that this call is a no-op. It is not reliably implemented in many common use cases, for example if your code is running inside a LXC container, or if the user has mounted the filing system with non-default options. Instead open the handle with caching::reads which means that all writes form a strict sequential order not completing until acknowledged by the storage device. Filing system can and do use different algorithms to give much better performance with caching::reads, some (e.g. ZFS) spectacularly better.
Let me repeat again: consider this call to be a hint to poke the kernel with a stick to go start to do some work sooner rather than later. It may be ignored entirely.
For portability, you can only assume that barriers write order for a single handle instance. You cannot assume that barriers write order across multiple handles to the same inode, or across processes.
Returns
The buffers barriered, which may not be the buffers input. The size of each scatter-gather buffer is updated with the number of bytes of that buffer barriered.
Parameters
selfThe object whose member function to call.
reqsA scatter-gather and offset request for what range to barrier. May be ignored on some platforms which always write barrier the entire file. Supplying a default initialised reqs write barriers the entire file.
wait_for_deviceTrue if you want the call to wait until data reaches storage and that storage has acknowledged the data is physically written. Slow.
and_metadataTrue if you want the call to sync the metadata for retrieving the writes before the barrier after a sudden power loss event. Slow.
dAn optional deadline by which the i/o must complete, else it is cancelled. Note function may return significantly after this deadline if the i/o takes long to cancel.
Errors returnable
Any of the values POSIX fdatasync() or Windows NtFlushBuffersFileEx() can return.
Memory Allocations
None.
529 {
530  return self.barrier(std::forward<decltype(reqs)>(reqs), std::forward<decltype(wait_for_device)>(wait_for_device), std::forward<decltype(and_metadata)>(and_metadata), std::forward<decltype(d)>(d));
531 }

◆ co_read()

result<async_file_handle::awaitable<async_file_handle::buffers_type> > afio_v2_xxx::co_read ( async_file_handle self,
async_file_handle::io_request< async_file_handle::buffers_type >  reqs 
)
inlinenoexcept

Schedule a read to occur asynchronously.

Returns
An awaitable, which when co_awaited upon, suspends execution of the coroutine until the operation has completed, resuming with the buffers read, which may not be the buffers input. The size of each scatter-gather buffer is updated with the number of bytes of that buffer transferred, and the pointer to the data may be completely different to what was submitted (e.g. it may point into a memory map).
Parameters
selfThe object whose member function to call.
reqsA scatter-gather and offset request.
Errors returnable
As for read(), plus ENOMEM.
Memory Allocations
One calloc, one free.
657 {
658  return self.co_read(std::forward<decltype(reqs)>(reqs));
659 }

◆ co_write()

result<async_file_handle::awaitable<async_file_handle::const_buffers_type> > afio_v2_xxx::co_write ( async_file_handle self,
async_file_handle::io_request< async_file_handle::const_buffers_type >  reqs 
)
inlinenoexcept

Schedule a write to occur asynchronously.

Returns
An awaitable, which when co_awaited upon, suspends execution of the coroutine until the operation has completed, resuming with the buffers written, which may not be the buffers input. The size of each scatter-gather buffer is updated with the number of bytes of that buffer transferred.
Parameters
selfThe object whose member function to call.
reqsA scatter-gather and offset request.
Errors returnable
As for write(), plus ENOMEM.
Memory Allocations
One calloc, one free.
672 {
673  return self.co_write(std::forward<decltype(reqs)>(reqs));
674 }

◆ directory()

result<directory_handle> afio_v2_xxx::directory ( const path_handle base,
directory_handle::path_view_type  _path,
directory_handle::mode  _mode = directory_handle::mode::read,
directory_handle::creation  _creation = directory_handle::creation::open_existing,
directory_handle::caching  _caching = directory_handle::caching::all,
directory_handle::flag  flags = directory_handle::flag::none 
)
inlinenoexcept

Create a handle opening access to a directory on path.

Errors returnable
Any of the values POSIX open() or CreateFile() can return.
307 {
308  return directory_handle::directory(std::forward<decltype(base)>(base), std::forward<decltype(_path)>(_path), std::forward<decltype(_mode)>(_mode), std::forward<decltype(_creation)>(_creation), std::forward<decltype(_caching)>(_caching), std::forward<decltype(flags)>(flags));
309 }
result< directory_handle > directory(const path_handle &base, directory_handle::path_view_type _path, directory_handle::mode _mode=directory_handle::mode::read, directory_handle::creation _creation=directory_handle::creation::open_existing, directory_handle::caching _caching=directory_handle::caching::all, directory_handle::flag flags=directory_handle::flag::none) noexcept
Definition: directory_handle.hpp:305

◆ enumerate()

result<directory_handle::enumerate_info> afio_v2_xxx::enumerate ( const directory_handle self,
directory_handle::buffers_type &&  tofill,
directory_handle::path_view_type  glob = directory_handle::path_view_type(),
directory_handle::filter  filtering = directory_handle::filter::fastdeleted,
span< char >  kernelbuffer = span<char>() 
)
inlinenoexcept

Fill the buffers type with as many directory entries as will fit.

Returns
Returns the buffers filled, what metadata was filled in and whether the entire directory was read into tofill.
Parameters
selfThe object whose member function to call.
tofillThe buffers to fill, returned to you on exit.
globAn optional shell glob by which to filter the items filled. Done kernel side on Windows, user side on POSIX.
filteringWhether to filter out fake-deleted files on Windows or not.
kernelbufferA buffer to use for the kernel to fill. If left defaulted, a kernel buffer is allocated internally and stored into tofill which needs to not be destructed until one is no longer using any items within (leafnames are views onto the original kernel data).
Errors returnable
todo
Memory Allocations
If the kernelbuffer parameter is set on entry, no memory allocations. If unset, at least one memory allocation, possibly more is performed.
350 {
351  return self.enumerate(std::forward<decltype(tofill)>(tofill), std::forward<decltype(glob)>(glob), std::forward<decltype(filtering)>(filtering), std::forward<decltype(kernelbuffer)>(kernelbuffer));
352 }

◆ file()

result<file_handle> afio_v2_xxx::file ( const path_handle base,
file_handle::path_view_type  _path,
file_handle::mode  _mode = file_handle::mode::read,
file_handle::creation  _creation = file_handle::creation::open_existing,
file_handle::caching  _caching = file_handle::caching::all,
file_handle::flag  flags = file_handle::flag::none 
)
inlinenoexcept

Create a file handle opening access to a file on path

Parameters
baseHandle to a base location on the filing system. Pass {} to indicate that path will be absolute.
_pathThe path relative to base to open.
_modeHow to open the file.
_creationHow to create the file.
_cachingHow to ask the kernel to cache the file.
flagsAny additional custom behaviours.
Errors returnable
Any of the values POSIX open() or CreateFile() can return.
307 {
308  return file_handle::file(std::forward<decltype(base)>(base), std::forward<decltype(_path)>(_path), std::forward<decltype(_mode)>(_mode), std::forward<decltype(_creation)>(_creation), std::forward<decltype(_caching)>(_caching), std::forward<decltype(flags)>(flags));
309 }
result< file_handle > file(const path_handle &base, file_handle::path_view_type _path, file_handle::mode _mode=file_handle::mode::read, file_handle::creation _creation=file_handle::creation::open_existing, file_handle::caching _caching=file_handle::caching::all, file_handle::flag flags=file_handle::flag::none) noexcept
Definition: file_handle.hpp:305

◆ length()

result<file_handle::extent_type> afio_v2_xxx::length ( const file_handle self)
inlinenoexcept

Return the current maximum permitted extent of the file.

Errors returnable
Any of the values POSIX fstat() or GetFileInformationByHandleEx() can return.
361 {
362  return self.length();
363 }

◆ map() [1/2]

result<map_handle> afio_v2_xxx::map ( map_handle::size_type  bytes,
section_handle::flag  _flag = section_handle::flag::readwrite 
)
inlinenoexcept

Create new memory and map it into view.

Parameters
bytesHow many bytes to create and map. Typically will be rounded to a multiple of the page size (see utils::page_sizes()).
_flagThe permissions with which to map the view which are constrained by the permissions of the memory section. flag::none can be useful for reserving virtual address space without committing system resources, use commit() to later change availability of memory.
Note
On Microsoft Windows this constructor uses the faster VirtualAlloc() which creates less versatile page backed memory. If you want anonymous memory allocated from a paging file backed section instead, create a page file backed section and then a mapped view from that using the other constructor. This makes available all those very useful VM tricks Windows can do with section mapped memory which VirtualAlloc() memory cannot do.
Errors returnable
Any of the values POSIX mmap() or VirtualAlloc() can return.
473 {
474  return map_handle::map(std::forward<decltype(bytes)>(bytes), std::forward<decltype(_flag)>(_flag));
475 }
result< map_handle > map(section_handle &section, map_handle::size_type bytes=0, map_handle::extent_type offset=0, section_handle::flag _flag=section_handle::flag::readwrite) noexcept
Definition: map_handle.hpp:484

◆ map() [2/2]

result<map_handle> afio_v2_xxx::map ( section_handle section,
map_handle::size_type  bytes = 0,
map_handle::extent_type  offset = 0,
section_handle::flag  _flag = section_handle::flag::readwrite 
)
inlinenoexcept

Create a memory mapped view of a backing storage.

Parameters
sectionA memory section handle specifying the backing storage to use.
bytesHow many bytes to map (0 = the size of the memory section). Typically will be rounded to a multiple of the page size (see utils::page_sizes()).
offsetThe offset into the backing storage to map from. Typically needs to be at least a multiple of the page size (see utils::page_sizes()), on Windows it needs to be a multiple of the kernel memory allocation granularity (typically 64Kb).
_flagThe permissions with which to map the view which are constrained by the permissions of the memory section. flag::none can be useful for reserving virtual address space without committing system resources, use commit() to later change availability of memory.
Errors returnable
Any of the values POSIX mmap() or NtMapViewOfSection() can return.
485 {
486  return map_handle::map(std::forward<decltype(section)>(section), std::forward<decltype(bytes)>(bytes), std::forward<decltype(offset)>(offset), std::forward<decltype(_flag)>(_flag));
487 }
result< map_handle > map(section_handle &section, map_handle::size_type bytes=0, map_handle::extent_type offset=0, section_handle::flag _flag=section_handle::flag::readwrite) noexcept
Definition: map_handle.hpp:484

◆ mapped_file() [1/2]

result<mapped_file_handle> afio_v2_xxx::mapped_file ( mapped_file_handle::size_type  reservation,
const path_handle base,
mapped_file_handle::path_view_type  _path,
mapped_file_handle::mode  _mode = mapped_file_handle::mode::read,
mapped_file_handle::creation  _creation = mapped_file_handle::creation::open_existing,
mapped_file_handle::caching  _caching = mapped_file_handle::caching::all,
mapped_file_handle::flag  flags = mapped_file_handle::flag::none 
)
inlinenoexcept

Create a memory mapped file handle opening access to a file on path.

Parameters
reservationThe number of bytes to reserve for later expansion when mapping. Zero means reserve only the current file length.
baseHandle to a base location on the filing system. Pass {} to indicate that path will be absolute.
_pathThe path relative to base to open.
_modeHow to open the file.
_creationHow to create the file.
_cachingHow to ask the kernel to cache the file.
flagsAny additional custom behaviours.

Note that if the file is currently zero sized, no mapping occurs now, but later when truncate() or update_map() is called.

Errors returnable
Any of the values which the constructors for file_handle, section_handle and map_handle can return.
432 {
433  return mapped_file_handle::mapped_file(std::forward<decltype(reservation)>(reservation), std::forward<decltype(base)>(base), std::forward<decltype(_path)>(_path), std::forward<decltype(_mode)>(_mode), std::forward<decltype(_creation)>(_creation), std::forward<decltype(_caching)>(_caching),
434  std::forward<decltype(flags)>(flags));
435 }
result< mapped_file_handle > mapped_file(const path_handle &base, mapped_file_handle::path_view_type _path, mapped_file_handle::mode _mode=mapped_file_handle::mode::read, mapped_file_handle::creation _creation=mapped_file_handle::creation::open_existing, mapped_file_handle::caching _caching=mapped_file_handle::caching::all, mapped_file_handle::flag flags=mapped_file_handle::flag::none) noexcept
Definition: mapped_file_handle.hpp:437

◆ mapped_file() [2/2]

result<mapped_file_handle> afio_v2_xxx::mapped_file ( const path_handle base,
mapped_file_handle::path_view_type  _path,
mapped_file_handle::mode  _mode = mapped_file_handle::mode::read,
mapped_file_handle::creation  _creation = mapped_file_handle::creation::open_existing,
mapped_file_handle::caching  _caching = mapped_file_handle::caching::all,
mapped_file_handle::flag  flags = mapped_file_handle::flag::none 
)
inlinenoexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

439 {
440  return mapped_file_handle::mapped_file(std::forward<decltype(base)>(base), std::forward<decltype(_path)>(_path), std::forward<decltype(_mode)>(_mode), std::forward<decltype(_creation)>(_creation), std::forward<decltype(_caching)>(_caching), std::forward<decltype(flags)>(flags));
441 }
result< mapped_file_handle > mapped_file(const path_handle &base, mapped_file_handle::path_view_type _path, mapped_file_handle::mode _mode=mapped_file_handle::mode::read, mapped_file_handle::creation _creation=mapped_file_handle::creation::open_existing, mapped_file_handle::caching _caching=mapped_file_handle::caching::all, mapped_file_handle::flag flags=mapped_file_handle::flag::none) noexcept
Definition: mapped_file_handle.hpp:437

◆ mapped_random_file()

result<mapped_file_handle> afio_v2_xxx::mapped_random_file ( mapped_file_handle::size_type  reservation,
const path_handle dirpath,
mapped_file_handle::mode  _mode = mapped_file_handle::mode::write,
mapped_file_handle::caching  _caching = mapped_file_handle::caching::temporary,
mapped_file_handle::flag  flags = mapped_file_handle::flag::none 
)
inlinenoexcept

Create an mapped file handle creating a randomly named file on a path. The file is opened exclusively with creation::only_if_not_exist so it will never collide with nor overwrite any existing file. Note also that caching defaults to temporary which hints to the OS to only flush changes to physical storage as lately as possible.

Errors returnable
Any of the values POSIX open() or CreateFile() can return.
452 {
453  return mapped_file_handle::mapped_random_file(std::forward<decltype(reservation)>(reservation), std::forward<decltype(dirpath)>(dirpath), std::forward<decltype(_mode)>(_mode), std::forward<decltype(_caching)>(_caching), std::forward<decltype(flags)>(flags));
454 }
result< mapped_file_handle > mapped_random_file(mapped_file_handle::size_type reservation, const path_handle &dirpath, mapped_file_handle::mode _mode=mapped_file_handle::mode::write, mapped_file_handle::caching _caching=mapped_file_handle::caching::temporary, mapped_file_handle::flag flags=mapped_file_handle::flag::none) noexcept
Definition: mapped_file_handle.hpp:450

◆ mapped_temp_file()

result<mapped_file_handle> afio_v2_xxx::mapped_temp_file ( mapped_file_handle::size_type  reservation,
mapped_file_handle::path_view_type  name = mapped_file_handle::path_view_type(),
mapped_file_handle::mode  _mode = mapped_file_handle::mode::write,
mapped_file_handle::creation  _creation = mapped_file_handle::creation::if_needed,
mapped_file_handle::caching  _caching = mapped_file_handle::caching::temporary,
mapped_file_handle::flag  flags = mapped_file_handle::flag::unlink_on_close 
)
inlinenoexcept

Create a mapped file handle creating the named file on some path which the OS declares to be suitable for temporary files. Most OSs are very lazy about flushing changes made to these temporary files. Note the default flags are to have the newly created file deleted on first handle close. Note also that an empty name is equivalent to calling mapped_random_file(path_discovery::storage_backed_temporary_files_directory()) and the creation parameter is ignored.

Note
If the temporary file you are creating is not going to have its path sent to another process for usage, this is the WRONG function to use. Use temp_inode() instead, it is far more secure.
Errors returnable
Any of the values POSIX open() or CreateFile() can return.
472 {
473  return mapped_file_handle::mapped_temp_file(std::forward<decltype(reservation)>(reservation), std::forward<decltype(name)>(name), std::forward<decltype(_mode)>(_mode), std::forward<decltype(_creation)>(_creation), std::forward<decltype(_caching)>(_caching), std::forward<decltype(flags)>(flags));
474 }
result< mapped_file_handle > mapped_temp_file(mapped_file_handle::size_type reservation, mapped_file_handle::path_view_type name=mapped_file_handle::path_view_type(), mapped_file_handle::mode _mode=mapped_file_handle::mode::write, mapped_file_handle::creation _creation=mapped_file_handle::creation::if_needed, mapped_file_handle::caching _caching=mapped_file_handle::caching::temporary, mapped_file_handle::flag flags=mapped_file_handle::flag::unlink_on_close) noexcept
Definition: mapped_file_handle.hpp:470

◆ mapped_temp_inode()

result<mapped_file_handle> afio_v2_xxx::mapped_temp_inode ( const path_handle dir = path_discovery::storage_backed_temporary_files_directory(),
mapped_file_handle::mode  _mode = mapped_file_handle::mode::write,
mapped_file_handle::flag  flags = mapped_file_handle::flag::none 
)
inlinenoexcept

Securely create a mapped file handle creating a temporary anonymous inode in the filesystem referred to by dirpath. The inode created has no name nor accessible path on the filing system and ceases to exist as soon as the last handle is closed, making it ideal for use as a temporary file where other processes do not need to have access to its contents via some path on the filing system (a classic use case is for backing shared memory maps).

Errors returnable
Any of the values POSIX open() or CreateFile() can return.
486 {
487  return mapped_file_handle::mapped_temp_inode(std::forward<decltype(dir)>(dir), std::forward<decltype(_mode)>(_mode), std::forward<decltype(flags)>(flags));
488 }
result< mapped_file_handle > mapped_temp_inode(const path_handle &dir=path_discovery::storage_backed_temporary_files_directory(), mapped_file_handle::mode _mode=mapped_file_handle::mode::write, mapped_file_handle::flag flags=mapped_file_handle::flag::none) noexcept
Definition: mapped_file_handle.hpp:485

◆ path() [1/2]

result<path_handle> afio_v2_xxx::path ( const path_handle base,
path_handle::path_view_type  _path 
)
inlinenoexcept

Create a path handle opening access to some location on the filing system. Some operating systems provide a particularly lightweight method of doing this (Linux: O_PATH, Windows: no access perms) which is much faster than opening a directory. For other systems, we open a directory with read only permissions.

Errors returnable
Any of the values POSIX open() or CreateFile() can return.
106 {
107  return path_handle::path(std::forward<decltype(base)>(base), std::forward<decltype(_path)>(_path));
108 }
result< path_handle > path(path_handle::path_view_type _path) noexcept
Definition: path_handle.hpp:110

◆ path() [2/2]

result<path_handle> afio_v2_xxx::path ( path_handle::path_view_type  _path)
inlinenoexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

111 {
112  return path_handle::path(std::forward<decltype(_path)>(_path));
113 }
result< path_handle > path(path_handle::path_view_type _path) noexcept
Definition: path_handle.hpp:110

◆ random_directory()

result<directory_handle> afio_v2_xxx::random_directory ( const path_handle dirpath,
directory_handle::mode  _mode = directory_handle::mode::write,
directory_handle::caching  _caching = directory_handle::caching::temporary,
directory_handle::flag  flags = directory_handle::flag::none 
)
inlinenoexcept

Create a directory handle creating a randomly named file on a path. The file is opened exclusively with creation::only_if_not_exist so it will never collide with nor overwrite any existing entry.

Errors returnable
Any of the values POSIX open() or CreateFile() can return.
317 {
318  return directory_handle::random_directory(std::forward<decltype(dirpath)>(dirpath), std::forward<decltype(_mode)>(_mode), std::forward<decltype(_caching)>(_caching), std::forward<decltype(flags)>(flags));
319 }
result< directory_handle > random_directory(const path_handle &dirpath, directory_handle::mode _mode=directory_handle::mode::write, directory_handle::caching _caching=directory_handle::caching::temporary, directory_handle::flag flags=directory_handle::flag::none) noexcept
Definition: directory_handle.hpp:316

◆ random_file()

result<file_handle> afio_v2_xxx::random_file ( const path_handle dirpath,
file_handle::mode  _mode = file_handle::mode::write,
file_handle::caching  _caching = file_handle::caching::temporary,
file_handle::flag  flags = file_handle::flag::none 
)
inlinenoexcept

Create a file handle creating a randomly named file on a path. The file is opened exclusively with creation::only_if_not_exist so it will never collide with nor overwrite any existing file. Note also that caching defaults to temporary which hints to the OS to only flush changes to physical storage as lately as possible.

Errors returnable
Any of the values POSIX open() or CreateFile() can return.
319 {
320  return file_handle::random_file(std::forward<decltype(dirpath)>(dirpath), std::forward<decltype(_mode)>(_mode), std::forward<decltype(_caching)>(_caching), std::forward<decltype(flags)>(flags));
321 }
result< file_handle > random_file(const path_handle &dirpath, file_handle::mode _mode=file_handle::mode::write, file_handle::caching _caching=file_handle::caching::temporary, file_handle::flag flags=file_handle::flag::none) noexcept
Definition: file_handle.hpp:318

◆ read() [1/2]

io_handle::io_result<io_handle::buffers_type> afio_v2_xxx::read ( io_handle self,
io_handle::io_request< io_handle::buffers_type reqs,
deadline  d = deadline() 
)
inlinenoexcept

Read data from the open handle.

Warning
Depending on the implementation backend, very different buffers may be returned than you supplied. You should always use the buffers returned and assume that they point to different memory and that each buffer's size will have changed.
Returns
The buffers read, which may not be the buffers input. The size of each scatter-gather buffer is updated with the number of bytes of that buffer transferred, and the pointer to the data may be completely different to what was submitted (e.g. it may point into a memory map).
Parameters
selfThe object whose member function to call.
reqsA scatter-gather and offset request.
dAn optional deadline by which the i/o must complete, else it is cancelled. Note function may return significantly after this deadline if the i/o takes long to cancel.
Errors returnable
Any of the values POSIX read() can return, errc::timed_out, errc::operation_canceled. errc::not_supported may be returned if deadline i/o is not possible with this particular handle configuration (e.g. reading from regular files on POSIX or reading from a non-overlapped HANDLE on Windows).
Memory Allocations
The default synchronous implementation in file_handle performs no memory allocation. The asynchronous implementation in async_file_handle performs one calloc and one free.
468 {
469  return self.read(std::forward<decltype(reqs)>(reqs), std::forward<decltype(d)>(d));
470 }

◆ read() [2/2]

map_handle::io_result<map_handle::buffers_type> afio_v2_xxx::read ( map_handle self,
map_handle::io_request< map_handle::buffers_type >  reqs,
deadline  d = deadline() 
)
inlinenoexcept

Read data from the mapped view.

Note
Because this implementation never copies memory, you can pass in buffers with a null address.
Returns
The buffers read, which will never be the buffers input because they will point into the mapped view. The size of each scatter-gather buffer is updated with the number of bytes of that buffer transferred.
Parameters
selfThe object whose member function to call.
reqsA scatter-gather and offset request.
dIgnored.
Errors returnable
None, though the various signals and structured exception throws common to using memory maps may occur.
Memory Allocations
None.
506 {
507  return self.read(std::forward<decltype(reqs)>(reqs), std::forward<decltype(d)>(d));
508 }

◆ relink()

result<void> afio_v2_xxx::relink ( fs_handle self,
const path_handle base,
fs_handle::path_view_type  newpath,
bool  atomic_replace = true,
deadline  d = std::chrono::seconds(30) 
)
inlinenoexcept

Relinks the current path of this open handle to the new path specified. If atomic_replace is true, the relink atomically and silently replaces any item at the new path specified. This operation is both atomic and silent matching POSIX behaviour even on Microsoft Windows where no Win32 API can match POSIX semantics.

Warning
Some operating systems provide a race free syscall for renaming an open handle (Windows). On all other operating systems this call is racy and can result in the wrong file entry being relinked. Note that unless flag::disable_safety_unlinks is set, this implementation opens a path_handle to the source containing directory first, then checks before relinking that the item about to be relinked has the same inode as the open file handle. It will retry this matching until success until the deadline given. This should prevent most unmalicious accidental loss of data.
Parameters
selfThe object whose member function to call.
baseBase for any relative path.
newpathThe relative or absolute new path to relink to.
atomic_replaceAtomically replace the destination if a file entry already is present there. Choosing false for this will fail if a file entry is already present at the destination, and may not be an atomic operation on some platforms (i.e. both the old and new names may be linked to the same inode for a very short period of time). Windows and recent Linuxes are always atomic.
dThe deadline by which the matching of the containing directory to the open handle's inode must succeed, else std::errc::timed_out will be returned.
Memory Allocations
Except on platforms with race free syscalls for renaming open handles (Windows), calls current_path() and thus is both expensive and calls malloc many times.
206 {
207  return self.relink(std::forward<decltype(base)>(base), std::forward<decltype(newpath)>(newpath), std::forward<decltype(atomic_replace)>(atomic_replace), std::forward<decltype(d)>(d));
208 }

◆ temp_directory()

result<directory_handle> afio_v2_xxx::temp_directory ( directory_handle::path_view_type  name = directory_handle::path_view_type(),
directory_handle::mode  _mode = directory_handle::mode::write,
directory_handle::creation  _creation = directory_handle::creation::if_needed,
directory_handle::caching  _caching = directory_handle::caching::all,
directory_handle::flag  flags = directory_handle::flag::none 
)
inlinenoexcept

Create a directory handle creating the named directory on some path which the OS declares to be suitable for temporary files. Note also that an empty name is equivalent to calling random_file(path_discovery::storage_backed_temporary_files_directory()) and the creation parameter is ignored.

Errors returnable
Any of the values POSIX open() or CreateFile() can return.
330 {
331  return directory_handle::temp_directory(std::forward<decltype(name)>(name), std::forward<decltype(_mode)>(_mode), std::forward<decltype(_creation)>(_creation), std::forward<decltype(_caching)>(_caching), std::forward<decltype(flags)>(flags));
332 }
result< directory_handle > temp_directory(directory_handle::path_view_type name=directory_handle::path_view_type(), directory_handle::mode _mode=directory_handle::mode::write, directory_handle::creation _creation=directory_handle::creation::if_needed, directory_handle::caching _caching=directory_handle::caching::all, directory_handle::flag flags=directory_handle::flag::none) noexcept
Definition: directory_handle.hpp:328

◆ temp_file()

result<file_handle> afio_v2_xxx::temp_file ( file_handle::path_view_type  name = file_handle::path_view_type(),
file_handle::mode  _mode = file_handle::mode::write,
file_handle::creation  _creation = file_handle::creation::if_needed,
file_handle::caching  _caching = file_handle::caching::temporary,
file_handle::flag  flags = file_handle::flag::unlink_on_close 
)
inlinenoexcept

Create a file handle creating the named file on some path which the OS declares to be suitable for temporary files. Most OSs are very lazy about flushing changes made to these temporary files. Note the default flags are to have the newly created file deleted on first handle close. Note also that an empty name is equivalent to calling random_file(path_discovery::storage_backed_temporary_files_directory()) and the creation parameter is ignored.

Note
If the temporary file you are creating is not going to have its path sent to another process for usage, this is the WRONG function to use. Use temp_inode() instead, it is far more secure.
Errors returnable
Any of the values POSIX open() or CreateFile() can return.
339 {
340  return file_handle::temp_file(std::forward<decltype(name)>(name), std::forward<decltype(_mode)>(_mode), std::forward<decltype(_creation)>(_creation), std::forward<decltype(_caching)>(_caching), std::forward<decltype(flags)>(flags));
341 }
result< file_handle > temp_file(file_handle::path_view_type name=file_handle::path_view_type(), file_handle::mode _mode=file_handle::mode::write, file_handle::creation _creation=file_handle::creation::if_needed, file_handle::caching _caching=file_handle::caching::temporary, file_handle::flag flags=file_handle::flag::unlink_on_close) noexcept
Definition: file_handle.hpp:337

◆ temp_inode()

result<file_handle> afio_v2_xxx::temp_inode ( const path_handle dir = path_discovery::storage_backed_temporary_files_directory(),
file_handle::mode  _mode = file_handle::mode::write,
file_handle::flag  flags = file_handle::flag::none 
)
inlinenoexcept

Securely create a file handle creating a temporary anonymous inode in the filesystem referred to by dirpath. The inode created has no name nor accessible path on the filing system and ceases to exist as soon as the last handle is closed, making it ideal for use as a temporary file where other processes do not need to have access to its contents via some path on the filing system (a classic use case is for backing shared memory maps).

Errors returnable
Any of the values POSIX open() or CreateFile() can return.
353 {
354  return file_handle::temp_inode(std::forward<decltype(dir)>(dir), std::forward<decltype(_mode)>(_mode), std::forward<decltype(flags)>(flags));
355 }
result< file_handle > temp_inode(const path_handle &dir=path_discovery::storage_backed_temporary_files_directory(), file_handle::mode _mode=file_handle::mode::write, file_handle::flag flags=file_handle::flag::none) noexcept
Definition: file_handle.hpp:352

◆ truncate() [1/2]

result<file_handle::extent_type> afio_v2_xxx::truncate ( file_handle self,
file_handle::extent_type  newsize 
)
inlinenoexcept

Resize the current maximum permitted extent of the file to the given extent, avoiding any new allocation of physical storage where supported. Note that on extents based filing systems this will succeed even if there is insufficient free space on the storage medium.

Returns
The bytes actually truncated to.
Parameters
selfThe object whose member function to call.
newsizeThe bytes to truncate the file to.
Errors returnable
Any of the values POSIX ftruncate() or SetFileInformationByHandle() can return.
374 {
375  return self.truncate(std::forward<decltype(newsize)>(newsize));
376 }

◆ truncate() [2/2]

result<section_handle::extent_type> afio_v2_xxx::truncate ( section_handle self,
section_handle::extent_type  newsize = 0 
)
inlinenoexcept

Resize the current maximum permitted extent of the memory section to the given extent.

Parameters
selfThe object whose member function to call.
newsizeThe new size of the memory section. Specify zero to use backing.length(). This cannot exceed the size of any backing file used.
Errors returnable
Any of the values NtExtendSection() can return. On POSIX this is a no op.
444 {
445  return self.truncate(std::forward<decltype(newsize)>(newsize));
446 }

◆ unlink()

result<void> afio_v2_xxx::unlink ( fs_handle self,
deadline  d = std::chrono::seconds(30) 
)
inlinenoexcept

Unlinks the current path of this open handle, causing its entry to immediately disappear from the filing system. On Windows unless flag::win_disable_unlink_emulation is set, this behaviour is simulated by renaming the file to something random and setting its delete-on-last-close flag. Note that Windows may prevent the renaming of a file in use by another process, if so it will NOT be renamed. After the next handle to that file closes, it will become permanently unopenable by anyone else until the last handle is closed, whereupon the entry will be eventually removed by the operating system.

Warning
Some operating systems provide a race free syscall for unlinking an open handle (Windows). On all other operating systems this call is racy and can result in the wrong file entry being unlinked. Note that unless flag::disable_safety_unlinks is set, this implementation opens a path_handle to the containing directory first, then checks that the item about to be unlinked has the same inode as the open file handle. It will retry this matching until success until the deadline given. This should prevent most unmalicious accidental loss of data.
Parameters
selfThe object whose member function to call.
dThe deadline by which the matching of the containing directory to the open handle's inode must succeed, else std::errc::timed_out will be returned.
Memory Allocations
Except on platforms with race free syscalls for unlinking open handles (Windows), calls current_path() and thus is both expensive and calls malloc many times. On Windows, also calls current_path() if flag::disable_safety_unlinks is not set.
233 {
234  return self.unlink(std::forward<decltype(d)>(d));
235 }

◆ write() [1/2]

Write data to the open handle.

Warning
Depending on the implementation backend, not all of the buffers input may be written and the some buffers at the end of the returned buffers may return with zero bytes written. For example, with a zeroed deadline, some backends may only consume as many buffers as the system has available write slots for, thus for those backends this call is "non-blocking" in the sense that it will return immediately even if it could not schedule a single buffer write. Another example is that some implementations will not auto-extend the length of a file when a write exceeds the maximum extent, you will need to issue a truncate(newsize) first.
Returns
The buffers written, which may not be the buffers input. The size of each scatter-gather buffer is updated with the number of bytes of that buffer transferred.
Parameters
selfThe object whose member function to call.
reqsA scatter-gather and offset request.
dAn optional deadline by which the i/o must complete, else it is cancelled. Note function may return significantly after this deadline if the i/o takes long to cancel.
Errors returnable
Any of the values POSIX write() can return, errc::timed_out, errc::operation_canceled. errc::not_supported may be returned if deadline i/o is not possible with this particular handle configuration (e.g. writing to regular files on POSIX or writing to a non-overlapped HANDLE on Windows).
Memory Allocations
The default synchronous implementation in file_handle performs no memory allocation. The asynchronous implementation in async_file_handle performs one calloc and one free.
494 {
495  return self.write(std::forward<decltype(reqs)>(reqs), std::forward<decltype(d)>(d));
496 }

◆ write() [2/2]

map_handle::io_result<map_handle::const_buffers_type> afio_v2_xxx::write ( map_handle self,
map_handle::io_request< map_handle::const_buffers_type >  reqs,
deadline  d = deadline() 
)
inlinenoexcept

Write data to the mapped view.

Returns
The buffers written, which will never be the buffers input because they will point at where the data was copied into the mapped view. The size of each scatter-gather buffer is updated with the number of bytes of that buffer transferred.
Parameters
selfThe object whose member function to call.
reqsA scatter-gather and offset request.
dIgnored.
Errors returnable
None, though the various signals and structured exception throws common to using memory maps may occur.
Memory Allocations
None.
520 {
521  return self.write(std::forward<decltype(reqs)>(reqs), std::forward<decltype(d)>(d));
522 }

◆ zero()

result<file_handle::extent_type> afio_v2_xxx::zero ( file_handle self,
file_handle::extent_type  offset,
file_handle::extent_type  bytes,
deadline  d = deadline() 
)
inlinenoexcept

Efficiently zero, and possibly deallocate, data on storage.

On most major operating systems and with recent filing systems which are "extents based", one can deallocate the physical storage of a file, causing the space deallocated to appear all bits zero. This call attempts to deallocate whole pages (usually 4Kb) entirely, and memset's any excess to all bits zero. This call works on most Linux filing systems with a recent kernel, Microsoft Windows with NTFS, and FreeBSD with ZFS. On other systems it simply writes zeros.

Returns
The bytes zeroed.
Parameters
selfThe object whose member function to call.
offsetThe offset to start zeroing from.
bytesThe number of bytes to zero.
dAn optional deadline by which the i/o must complete, else it is cancelled. Note function may return significantly after this deadline if the i/o takes long to cancel.
Errors returnable
Any of the values POSIX write() can return, errc::timed_out, errc::operation_canceled. errc::not_supported may be returned if deadline i/o is not possible with this particular handle configuration (e.g. writing to regular files on POSIX or writing to a non-overlapped HANDLE on Windows).
Memory Allocations
The default synchronous implementation in file_handle performs no memory allocation. The asynchronous implementation in async_file_handle may perform one calloc and one free.
404 {
405  return self.zero(std::forward<decltype(offset)>(offset), std::forward<decltype(bytes)>(bytes), std::forward<decltype(d)>(d));
406 }