llfio_v2_xxx Namespace Reference

The LLFIO namespace. More...

Namespaces
	algorithm
	Collection of file system based algorithms.
	ip
	Inspired by ASIO's ip namespace.
	path_discovery
	Contains functions used to discover suitable paths for things.
	storage_profile
	YAML databaseable empirical testing of a storage's behaviour.
	this_thread
	Thread local settings.
	utils
	Utility routines often useful when using LLFIO.

Classes
class	byte_io_handle
	A handle to something capable of scatter-gather byte i/o. More...
class	pollable_handle
	A handle type which can be supplied to poll(). More...
class	byte_io_multiplexer
	A multiplexer of byte-orientated i/o. More...
class	byte_socket_handle
	A handle to a byte-orientated socket-like entity. More...
struct	construct< byte_socket_handle >
	Constructor for byte_socket_handle More...
class	listening_socket_handle_buffer_types_injector
	Injects buffer types for a particular kind of listening socket read. More...
class	listening_byte_socket_handle
struct	construct< listening_byte_socket_handle >
	Constructor for listening_byte_socket_handle More...
struct	path_hasher
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...
struct	construct< directory_handle >
	Constructor for directory_handle More...
class	dynamic_thread_pool_group
	Work group within the global dynamic thread pool. More...
class	fast_random_file_handle
	A handle to synthesised, non-cryptographic, pseudo-random data. More...
struct	construct< fast_random_file_handle >
	Constructor for fast_random_file_handle More...
class	file_handle
	A handle to a regular file or device. More...
struct	construct< file_handle >
	Constructor for 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...
struct	construct
	Metaprogramming shim for constructing any handle subclass. More...
class	lockable_byte_io_handle
	A handle to something capable of scatter-gather i/o and which can exclude other concurrent users. Models SharedMutex, though note that the locks are per-handle, not per-thread. More...
class	unique_file_lock
	RAII locker matching std::unique_lock for lockable_byte_io_handle, but untemplated. More...
class	log_level_guard
	RAII class for temporarily adjusting the log level for the current thread. More...
class	section_handle
	A handle to a source of mapped memory. More...
struct	construct< section_handle >
	Constructor for section_handle More...
class	map_handle
	A handle to a memory mapped region of memory, either backed by the system page file or by a section. More...
struct	construct< map_handle >
	Constructor for map_handle More...
class	mapped
	Provides an owning, typed view of memory mapped from a section_handle or a file_handle suitable for feeding to STL algorithms or the Ranges TS. More...
class	mapped_file_handle
	A memory mapped regular file or device. More...
struct	construct< mapped_file_handle >
	Constructor for mapped_file_handle More...
class	read_receiver
	A C++ Receiver of an i/o read for an i/o type of IoHandleType. More...
class	write_receiver
	A C++ Receiver of an i/o write for an i/o type of IoHandleType. More...
class	executor
	Some implementation of a C++ Executor. More...
class	awaitable_handle
	An awaitable handle which attempts to execute the i/o immediately. If the i/o can complete immediately, no coroutine suspension occurs. Only if the i/o would take a while is coroutine suspension performed. 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	construct< path_handle >
	Constructor for path_handle More...
class	path_view_component
	An iterated part of a path_view. More...
class	path_view
	A borrowed view of a path. A lightweight trivial-type alternative to std::filesystem::path. More...
class	pipe_handle
	A handle to a named or anonymous pipe. More...
struct	construct< pipe_handle >
	Constructor for pipe_handle More...
class	process_handle
	A handle to this, or another, process. More...
struct	construct< process_handle >
	Constructor for process_handle 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...
struct	error_info
	The cause of the failure of an operation in LLFIO. More...
class	error
	The exception type synthesised and thrown when an llfio::result or llfio::outcome is no-value observed. More...
class	symlink_handle
	A handle to an inode which redirects to a different path. More...
struct	construct< symlink_handle >
	Constructor for symlink_handle More...
class	tls_socket_handle
	A handle to a TLS secure socket-like entity. More...
class	listening_tls_socket_handle
	A handle to a TLS socket-like entity able to receive incoming connections. More...
class	tls_socket_source
	A source of tls_socket_handle and listening_tls_socket_handle and possibly a byte_io_multiplexer to multiplex i/o on multiple socket instances at the same time. More...
struct	tls_socket_source_implementation_information
	The implementation information returned. More...
class	tls_socket_source_registry
	A process-wide registry of tls_socket_source. More...
struct	construct< algorithm::cached_parent_handle_adapter< T > >
	Constructor for algorithm::::cached_parent_handle_adapter<T> More...

Typedefs
using	byte_io_multiplexer_ptr = std::unique_ptr< byte_io_multiplexer >
	A unique ptr to an i/o multiplexer implementation.
template<class F , size_t callable_storage_bytes = 32 - sizeof(uintptr_t)>
using	function_ptr = QUICKCPPLIB_NAMESPACE::function_ptr::function_ptr< F, callable_storage_bytes >
using	spinlock = QUICKCPPLIB_NAMESPACE::configurable_spinlock::spinlock< uintptr_t >
using	dynamic_thread_pool_group_ptr = std::unique_ptr< dynamic_thread_pool_group >
	A unique ptr to a work group within the global dynamic thread pool.
using	log_level = QUICKCPPLIB_NAMESPACE::ringbuffer_log::level
	Enum for the log level.
using	log_implementation_type = QUICKCPPLIB_NAMESPACE::ringbuffer_log::simple_ringbuffer_log< LLFIO_LOGGING_MEMORY, detail::thread_local_log_level_filter >
	Type of the logger.
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	tls_socket_handle_ptr = std::unique_ptr< tls_socket_handle, detail::tls_socket_handle_deleter >
	A pointer to a TLS socket handle returned by a TLS socket source.
using	listening_tls_socket_handle_ptr = std::unique_ptr< listening_tls_socket_handle, detail::listening_tls_socket_handle_deleter >
	A pointer to a listening TLS socket handle returned by a TLS socket source.
using	tls_socket_source_ptr = std::unique_ptr< tls_socket_source, detail::tls_socket_source_deleter >
	A pointer to a TLS socket source.

Enumerations
enum class	io_operation_state_type {   unknown , read_initialised , read_initiated , read_completed ,   read_finished , write_initialised , write_initiated , barrier_initialised ,   barrier_initiated , write_or_barrier_completed , write_or_barrier_finished }
	The possible states of the i/o operation.
enum class	win32_path_namespace { any , device , dos , guid_volume }
	The kinds of win32 path namespace possible. More...
enum class	lock_kind { unlocked , shared , exclusive }
	The kinds of concurrent user exclusion which can be performed. More...
enum	bitfield__tls_algorithm : unsigned { default_ = (0U) , FIPS_140_2 = (1U << 0U) }
	TLS algorithm categories. More...

Functions
	QUICKCPPLIB_BITFIELD_BEGIN_T (poll_what, uint8_t)
	What to poll. More...
result< size_t >	poll (span< poll_what > out, span< pollable_handle * > handles, span< const poll_what > query, deadline d={}) noexcept
	Polls a list of pollable handles awaiting a change in state. More...
byte_io_handle::io_result< byte_io_handle::buffers_type >	read (byte_io_handle &self, byte_io_handle::io_request< byte_io_handle::buffers_type > reqs, deadline d=deadline()) noexcept
	Read data from the open handle. More...
byte_io_handle::io_result< byte_io_handle::const_buffers_type >	write (byte_io_handle &self, byte_io_handle::io_request< byte_io_handle::const_buffers_type > reqs, deadline d=deadline()) noexcept
	Write data to the open handle. More...
byte_io_handle::io_result< byte_io_handle::size_type >	write (byte_io_handle &self, byte_io_handle::extent_type offset, std::initializer_list< byte_io_handle::const_buffer_type > lst, deadline d=deadline()) noexcept
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
constexpr bool	is_initialised (io_operation_state_type s) noexcept
	True if the i/o operation state is initialised.
constexpr bool	is_initiated (io_operation_state_type s) noexcept
	True if the i/o operation state is initiated.
constexpr bool	is_completed (io_operation_state_type s) noexcept
	True if the i/o operation state is completed.
constexpr bool	is_finished (io_operation_state_type s) noexcept
	True if the i/o operation state is finished.
std::ostream &	operator<< (std::ostream &s, const directory_handle::filter &v)
std::ostream &	operator<< (std::ostream &s, const directory_handle::buffers_type &)
void	swap (directory_handle &self, directory_handle &o) noexcept
	Swap with another instance.
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
result< directory_handle >	uniquely_named_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_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
result< dynamic_thread_pool_group_ptr >	make_dynamic_thread_pool_group () noexcept
	Creates a new work group within the global dynamic thread pool.
void	swap (file_handle &self, file_handle &o) noexcept
	Swap with another instance.
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
result< file_handle >	uniquely_named_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_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_first_close) noexcept
result< file_handle >	temp_inode (const path_handle &dirh=path_discovery::storage_backed_temporary_files_directory(), 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
file_handle::io_result< file_handle::size_type >	read (file_handle &self, file_handle::extent_type offset, std::initializer_list< file_handle::buffer_type > lst, deadline d=deadline()) noexcept
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
result< file_handle::extent_type >	maximum_extent (const file_handle &self) noexcept
result< file_handle::extent_type >	truncate (file_handle &self, file_handle::extent_type newsize) noexcept
result< std::vector< file_handle::extent_pair > >	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< filesystem::path >	to_win32_path (const fs_handle &h, win32_path_namespace mapping=win32_path_namespace::any) noexcept
	Maps the current path of h into a form suitable for Win32 APIs. Passes through unmodified on POSIX, so you can use this in portable code. More...
template<class T , typename std::enable_if<(!std::is_base_of< fs_handle, T >::value &&std::is_base_of< handle, T >::value), bool >::type = true>
result< filesystem::path >	to_win32_path (const T &h, win32_path_namespace mapping=win32_path_namespace::any) noexcept
result< void >	relink (fs_handle &self, const path_handle &base, fs_handle::path_view_type path, 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)
void	swap (handle &self, handle &o) noexcept
	Swap with another instance.
result< void >	close (handle &self) noexcept
	Immediately close the native handle type managed by this handle.
log_implementation_type &	log () noexcept
	The log used by LLFIO.
std::ostream &	operator<< (std::ostream &s, const section_handle::flag &v)
byte_io_handle::const_buffer_type	nvram_barrier (byte_io_handle::const_buffer_type req, bool evict=false) noexcept
template<class T >
constexpr span< T >	in_place_attach (map_handle &mh) noexcept
	Declare map_handle as a suitable source for P1631 attached<T>.
void	swap (section_handle &self, section_handle &o) noexcept
	Swap with another instance.
result< section_handle >	section (file_handle &backing, section_handle::extent_type maximum_size, section_handle::flag _flag) noexcept
	Create a memory section backed by a file. More...
result< section_handle >	section (file_handle &backing, section_handle::extent_type bytes=0) noexcept
	Create a memory section backed by a file. More...
result< section_handle >	section (section_handle::extent_type bytes, const path_handle &dirh=path_discovery::storage_backed_temporary_files_directory(), section_handle::flag _flag=section_handle::flag::read|section_handle::flag::write) noexcept
	Create a memory section backed by an anonymous, managed file. More...
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.
result< map_handle >	map (map_handle::size_type bytes, bool zeroed=false, section_handle::flag _flag=section_handle::flag::readwrite) noexcept
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
map_handle::size_type	length (const map_handle &self) noexcept
	The size of the memory map. This is the accessible size, NOT the reservation size.
result< map_handle::size_type >	truncate (map_handle &self, map_handle::size_type newsize, bool permit_relocation=false) noexcept
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...
template<class T >
constexpr span< T >	in_place_attach (mapped_file_handle &mfh) noexcept
	Declare mapped_file_handle as a suitable source for P1631 attached<T>.
void	swap (mapped_file_handle &self, mapped_file_handle &o) noexcept
	Swap with another instance.
result< mapped_file_handle >	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) noexcept
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
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
result< mapped_file_handle >	mapped_uniquely_named_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_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_first_close) noexcept
result< mapped_file_handle >	mapped_temp_inode (mapped_file_handle::size_type reservation=0, const path_handle &dir=path_discovery::storage_backed_temporary_files_directory(), 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< path_handle >	path (const path_handle &base, path_handle::path_view_type path) noexcept
result< path_handle >	path (path_handle::path_view_type _path) noexcept
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
constexpr bool	operator== (path_view_component x, path_view_component y) noexcept
	Compares identity equality not equivalence i.e. backing storage type must be identical, and backing bytes must be identical. Use compare() if you want something stronger.
constexpr bool	operator== (path_view x, path_view y) noexcept
	Compares individual path view components for identity not equivalence. Use compare() if you want something stronger.
constexpr bool	operator!= (path_view_component x, path_view_component y) noexcept
	Compares identity inequality not disequivalence i.e. backing storage type must be different, or backing bytes must be different. Use compare() if you want something stronger.
constexpr bool	operator< (path_view_component x, path_view_component y) noexcept
	Compares identity for ordering i.e. backing storage type must be different, or backing bytes must be different. Use compare() if you want something stronger.
constexpr bool	operator!= (path_view x, path_view y) noexcept
	Compares individual path view components for non-**identity** not disequivalence. Use compare() if you want something stronger.
constexpr bool	operator< (path_view x, path_view y) noexcept
	Compares individual path view components for ordering. Use compare() if you want something stronger.
constexpr size_t	hash_value (path_view_component view) noexcept
	Hashes a path_view_component.
template<class F >
constexpr auto	visit (path_view_component view, F &&f)
	Visit the underlying source for a path_view_component (LLFIO backwards compatible overload)
template<class F >
constexpr auto	visit (F &&f, path_view_component view)
	Visit the underlying source for a path_view_component (std compatible overload)
std::ostream &	operator<< (std::ostream &s, const path_view_component &v)
constexpr size_t	hash_value (path_view x) noexcept
	Return the combined hash of individual path components.
template<class CharT , typename std::enable_if<(path_view_component::is_source_acceptable< CharT >), bool >::type = true>
constexpr bool	operator== (path_view_component, const CharT *) noexcept
template<class CharT , typename std::enable_if<(path_view_component::is_source_acceptable< CharT >), bool >::type = true>
constexpr bool	operator== (const CharT *, path_view_component) noexcept
template<class CharT , typename std::enable_if<(path_view_component::is_source_acceptable< CharT >), bool >::type = true>
constexpr bool	operator!= (path_view_component, const CharT *) noexcept
template<class CharT , typename std::enable_if<(path_view_component::is_source_acceptable< CharT >), bool >::type = true>
constexpr bool	operator!= (const CharT *, path_view_component) noexcept
template<class CharT , typename std::enable_if<(path_view_component::is_source_acceptable< CharT >), bool >::type = true>
constexpr bool	operator< (path_view_component, const CharT *) noexcept
template<class CharT , typename std::enable_if<(path_view_component::is_source_acceptable< CharT >), bool >::type = true>
constexpr bool	operator< (const CharT *, path_view_component) noexcept
template<class CharT , typename std::enable_if<(path_view::is_source_acceptable< CharT >), bool >::type = true>
constexpr bool	operator== (path_view, const CharT *) noexcept
template<class CharT , typename std::enable_if<(path_view::is_source_acceptable< CharT >), bool >::type = true>
constexpr bool	operator== (const CharT *, path_view) noexcept
template<class CharT , typename std::enable_if<(path_view::is_source_acceptable< CharT >), bool >::type = true>
constexpr bool	operator!= (path_view, const CharT *) noexcept
template<class CharT , typename std::enable_if<(path_view::is_source_acceptable< CharT >), bool >::type = true>
constexpr bool	operator!= (const CharT *, path_view) noexcept
filesystem::path &	operator+= (filesystem::path &a, path_view_component b)
	Append a path view component to a path.
filesystem::path &	operator/= (filesystem::path &a, path_view_component b)
	Append a path view component to a path.
filesystem::path	operator/ (const filesystem::path &a, path_view_component b)
	Append a path view component to a path.
filesystem::path	operator/ (filesystem::path &&a, path_view_component b)
	Append a path view component to a path.
template<class T , typename std::enable_if<(std::is_same< T, path_view_component >::value||std::is_same< T, path_view >::value), bool >::type = true>
filesystem::path	operator/ (T a, path_view_component b)
	Append a path view component to a path view component.
std::ostream &	operator<< (std::ostream &s, const process_handle::flag &v)
std::error_code	make_error_code (error_info ei)
bool	operator== (const error_info &a, const error_info &b)
bool	operator!= (const error_info &a, const error_info &b)
	OUTCOME_TEMPLATE (class ErrorCondEnum) OUTCOME_TREQUIRES(OUTCOME_TPRED(std
std::ostream &	operator<< (std::ostream &s, const error_info &v)
void	outcome_throw_as_system_error_with_payload (const error_info &ei)
error_info	error_from_exception (std::exception_ptr &&ep=std::current_exception(), std::error_code not_matched=std::make_error_code(std::errc::resource_unavailable_try_again)) noexcept
error_info	generic_error (errc c)
	Helper for constructing an error info from an errc.
error_info	posix_error (int c=errno)
	Helper for constructing an error info from a POSIX errno.
	QUICKCPPLIB_BITFIELD_BEGIN_T (tls_socket_source_implementation_features, uint32_t)
	Feature bits for TLS socket sources. More...
std::ostream &	operator<< (std::ostream &s, const tls_socket_source_implementation_information &v)

Detailed Description

The LLFIO namespace.

Todo:

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

Enumeration Type Documentation

bitfield__tls_algorithm

enum llfio_v2_xxx::bitfield__tls_algorithm : unsigned

TLS algorithm categories.

Enumerator
default_	The default set of TLS algorithms offered during handshake is a short list of strong ciphers (typically 128 - 256 bits for the symmetric cipher) to suit embedded and low end devices, ordered by strength-cpuload e.g. ChaCha20 would be chosen preferentially to AES, if the CPUs do not have hardware accelerated AES, and longer key sizes would come before shorter key sizes.
FIPS_140_2	The set of TLS algorithms compliant with the FIPS 140-2 standard. Implementations may refuse to work if this is configured.

{                                          //
 /*! The default set of TLS algorithms offered during handshake is a short list
 of strong ciphers (typically 128 - 256 bits for the symmetric cipher)
 to suit embedded and low end devices, ordered by strength-cpuload e.g. ChaCha20
 would be chosen preferentially to AES, **if** the CPUs do not have hardware
 accelerated AES, and longer key sizes would come before shorter key sizes.
 */
 default_ = (0U),
 /*! The set of TLS algorithms compliant with the FIPS 140-2 standard.
 Implementations may refuse to work if this is configured.
 */
 FIPS_140_2 = (1U << 0U)
 
} QUICKCPPLIB_BITFIELD_END(tls_algorithm)

lock_kind

enum llfio_v2_xxx::lock_kind

strong

The kinds of concurrent user exclusion which can be performed.

Enumerator
unlocked	Exclude none.
shared	Exclude only those requesting an exclusive lock on the same inode.
exclusive	Exclude those requesting any kind of lock on the same inode.

{
  unlocked,  //!< Exclude none.
  shared,    //!< Exclude only those requesting an exclusive lock on the same inode.
  exclusive  //!< Exclude those requesting any kind of lock on the same inode.
};

win32_path_namespace

enum llfio_v2_xxx::win32_path_namespace

strong

The kinds of win32 path namespace possible.

Enumerator
any	Map the input path to a valid win32 path as fast as possible for the input. This is currently guid_volume followed by dos, but may change in the future.
device	Map \!!\Device\... form input paths to \\.\... for which it is usually the case there is a mapping, which results in a valid Win32 path, but which legacy code bases may not accept. This efficiently covers the vast majority of what can be returned by handle::current_path() on Windows, but if the input path cannot be mapped, a failure is returned.
dos	Map the input path to a DOS drive letter prefix, possibly with \\?\ prefix to opt out of strict DOS path parsing if the mapped DOS path is incompatible with traditional DOS (e.g. it contains one of the forbidden character sequences such as CON, or it exceeds 260 codepoints, and so on). Well written software will correctly handle \\?\ prefixes, but if the code you are handing the path to is particularly legacy, you ought to ensure that the prefix is not present. Warning There is not a one-one mapping between NT kernel paths (which is what LLFIO returns from handle::current_path()) and DOS style paths, so what you get may be surprising. It is also possible that there is no mapping at all, in which case a failure is returned.
guid_volume	Map the input path replacing the volume as a GUID, such that say an input path of C:\foo\bar might be mapped to \\?\Volume{9f9bd10e-9003-4da5-b146-70584e30854a}\foo\bar. This is a valid Win32 path, but legacy code bases may not accept it. This eliminates problems with drive letters vanishing or being ambiguous, and unlike with dos, there is a guaranteed one-one mapping between NT kernel paths and guid_volume paths. The mapped path is NOT checked for equivalence to the input file.

{
  /*! Map the input path to a valid win32 path as fast as possible for the input.
  This is currently `guid_volume` followed by `dos`, but may change in the future.
  */
  any,
  /*! Map `\!!\Device\...` form input paths to `\\.\...` for which it is _usually_
  the case there is a mapping, which results in a valid Win32 path, but which
  legacy code bases may not accept. This efficiently covers the vast majority of
  what can be returned by `handle::current_path()` on Windows, but if the input
  path cannot be mapped, a failure is returned.
  */
  device,
  /*! Map the input path to a DOS drive letter prefix, possibly with `\\?\` prefix
  to opt out of strict DOS path parsing if the mapped DOS path is incompatible with
  traditional DOS (e.g. it contains one of the forbidden character sequences such
  as `CON`, or it exceeds 260 codepoints, and so on). Well written software will
  correctly handle `\\?\` prefixes, but if the code you are handing the path to is
  particularly legacy, you ought to ensure that the prefix is not present.
 
  \warning There is not a one-one mapping between NT kernel paths (which is what
  LLFIO returns from `handle::current_path()`) and DOS style paths, so what you get
  may be surprising. It is also possible that there is no mapping at all, in which
  case a failure is returned.
  */
  dos,
  /*! Map the input path replacing the volume as a GUID, such that say an input path
  of `C:\foo\bar` might be mapped to `\\?\Volume{9f9bd10e-9003-4da5-b146-70584e30854a}\foo\bar`.
  This is a valid Win32 path, but legacy code bases may not accept it. This eliminates
  problems with drive letters vanishing or being ambiguous, and unlike with `dos`,
  there is a guaranteed one-one mapping between NT kernel paths and `guid_volume` paths.
  The mapped path is NOT checked for equivalence to the input file.
  */
  guid_volume
#if 0
  /*! Map the input path replacing the the whole path as a GUID, such that say an input
  path of `C:\foo\bar` might be mapped to `\\?\Volume{9f9bd10e-9003-4da5-b146-70584e30854a}\{5a13b46c-44b9-40f3-9303-23cf7d918708}`.
  This is a valid Win32 path, but legacy code bases may not accept it. This eliminates
  problems with long paths or if the file could be renamed concurrently. Note this may
  cause the creation of a GUID for the file on some filesystems (NTFS). The mapped path
  is NOT checked for equivalence to the input file.
  */
  guid_all
 
/*
- `win32_path_namespace::guid_all` does the same as `guid_volume`, but additionally
asks Windows for the GUID for the file upon the volume, creating one if one
doesn't exist if necessary. The path returned consists of two GUIDs, and is a
perfectly valid Win32 path which most Win32 APIs will accept.
*/
#endif
};

Function Documentation

directory()

result<directory_handle> llfio_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\n Any of the values POSIX open() or CreateFile() can return.

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

file()

result<file_handle> llfio_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

base	Handle to a base location on the filing system. Pass {} to indicate that path will be absolute.
path	The path relative to base to open.
_mode	How to open the file.
_creation	How to create the file.
_caching	How to ask the kernel to cache the file.
flags	Any additional custom behaviours.

Errors returnable\n Any of the values POSIX open() or CreateFile() can return.

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

map() [1/2]

result<map_handle> llfio_v2_xxx::map ( map_handle::size_type  bytes, bool  zeroed = false, section_handle::flag  _flag = section_handle::flag::readwrite  )

inlinenoexcept

Create new memory and map it into view.

Parameters

bytes	How many bytes to create and map. Typically will be rounded up to a multiple of the page size (see page_size()) on POSIX, 64Kb on Windows.
zeroed	Set to true if only all bits zeroed memory is wanted.
_flag	The permissions with which to map the view. 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\n Any of the values POSIX mmap() or VirtualAlloc() can return.

{
  return map_handle::map(std::forward<decltype(bytes)>(bytes), zeroed, std::forward<decltype(_flag)>(_flag));
}

map() [2/2]

result<map_handle> llfio_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, optionally reserving additional address space for later growth.

Parameters

section	A memory section handle specifying the backing storage to use.
bytes	How many bytes to reserve (0 = the size of the section). Rounded up to nearest 64Kb on Windows.
offset	The offset into the backing storage to map from
_flag	The 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\n Any of the values POSIX mmap() or NtMapViewOfSection() can return.

{
  return map_handle::map(std::forward<decltype(section)>(section), std::forward<decltype(bytes)>(bytes), std::forward<decltype(offset)>(offset),
                         std::forward<decltype(_flag)>(_flag));
}

mapped_file()

result<mapped_file_handle> llfio_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

reservation	The number of bytes to reserve for later expansion when mapping. Zero means reserve only the current file length.
base	Handle to a base location on the filing system. Pass {} to indicate that path will be absolute.
_path	The path relative to base to open.
_mode	How to open the file.
_creation	How to create the file.
_caching	How to ask the kernel to cache the file.
flags	Any 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\n Any of the values which the constructors for file_handle, section_handle and map_handle can return.

{
  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),
                                         std::forward<decltype(flags)>(flags));
}

mapped_temp_file()

result<mapped_file_handle> llfio_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_first_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_uniquely_named_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\n Any of the values POSIX open() or CreateFile() can return.

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

mapped_temp_inode()

result<mapped_file_handle> llfio_v2_xxx::mapped_temp_inode ( mapped_file_handle::size_type  reservation = 0, const path_handle &  dir = path_discovery::storage_backed_temporary_files_directory(), 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

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\n Any of the values POSIX open() or CreateFile() can return.

{
  return mapped_file_handle::mapped_temp_inode(std::forward<decltype(reservation)>(reservation), std::forward<decltype(dir)>(dir),
                                               std::forward<decltype(_mode)>(_mode), std::forward<decltype(_caching)>(_caching),
                                               std::forward<decltype(flags)>(flags));
}

mapped_uniquely_named_file()

result<mapped_file_handle> llfio_v2_xxx::mapped_uniquely_named_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\n Any of the values POSIX open() or CreateFile() can return.

{
  return mapped_file_handle::mapped_uniquely_named_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));
}

maximum_extent()

result<file_handle::extent_type> llfio_v2_xxx::maximum_extent ( const file_handle &  self )

inlinenoexcept

Return the current maximum permitted extent of the file.

Errors returnable\n Any of the values POSIX fstat() or GetFileInformationByHandleEx() can return.

{
  return self.maximum_extent();
}

nvram_barrier()

byte_io_handle::const_buffer_type llfio_v2_xxx::nvram_barrier ( byte_io_handle::const_buffer_type  req, bool  evict = false  )

inlinenoexcept

Lightweight inlined barrier which causes the CPU to write out all buffered writes and dirty cache lines in the request to main memory.

Returns

The cache lines actually barriered. This may be empty. This function does not return an error.

Parameters

req	The range of cache lines to write barrier.
evict	Whether to also evict the cache lines from CPU caches, useful if they will not be used again.

Upon return, one knows that memory in the returned buffer has been barriered (it may be empty if there is no support for this operation in LLFIO, or if the current CPU does not support this operation). You may find the is_nvram() observer of particular use here.

{
  auto *tp = (byte_io_handle::const_buffer_type::pointer) (((uintptr_t) req.data()) & ~63);
  byte_io_handle::const_buffer_type ret{tp, (size_t) (req.data() + 63 + req.size() - tp) & ~63};
  if(memory_flush_none == mem_flush_stores(ret.data(), ret.size(), evict ? memory_flush_evict : memory_flush_retain))
  {
    ret = {tp, 0};
  }
  return ret;
}

path()

result<path_handle> llfio_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\n Any of the values POSIX open() or CreateFile() can return.

{
  return path_handle::path(std::forward<decltype(base)>(base), std::forward<decltype(path)>(path));
}

poll()

result<size_t> llfio_v2_xxx::poll ( span< poll_what >  out, span< pollable_handle * >  handles, span< const poll_what >  query, deadline  d = {}  )

inlinenoexcept

Polls a list of pollable handles awaiting a change in state.

Returns

The number of handles with changed state. Handles not is_kernel_handle() receive poll_what::not_pollable.

Parameters

out	An array of poll_what set with the results of the poll. The bits in this array are NOT cleared by this operation, so you need to clear this manualy before the call if that's what you need.
handles	An array of pointers to handle. Individual pointers can be null if you want to skip them.
query	An array of poll_what to check.
d	An optional timeout.

Errors returnable\n Whatever POSIX poll() or Windows WSAPoll() can return.

Note that the maximum number of handles which can be passed to this function is 1024 (the platform syscall may refuse even that many). Note that this function is O(N) to handle count, so more than a few hundred is a bad idea in any case. If you need to wait on more handles than this, you need to implement a byte_io_multiplexer for your platform.

The sizes of out, handles and query must be the same, or an error is returned.

Note

On POSIX pipe_handle is a pollable_handle, but on Windows it is not. Also, on Windows, you cannot mix socket handles from different networking stacks in the same poll.

QUICKCPPLIB_BITFIELD_BEGIN_T() [1/2]

llfio_v2_xxx::QUICKCPPLIB_BITFIELD_BEGIN_T	(	poll_what	,
		uint8_t
	)

What to poll.

< Query nothing for this handle.

< If this handle is readable.

< If this handle is writable.

< If this handle is errored. This is always set in the output even if not requested.

< If this handle is closed/hung up. This is always set in the output even if not requested.

< This handle is not pollable.

{
none = 0U,  //!< Query nothing for this handle.
 
is_readable = (1U << 0U),  //!< If this handle is readable.
is_writable = (1U << 1U),  //!< If this handle is writable.
is_errored = (1U << 2U),   //!< If this handle is errored. This is always set in the output even if not requested.
is_closed = (1U << 3U),    //!< If this handle is closed/hung up. This is always set in the output even if not requested.
 
not_pollable = (1U << 7U)  //!< This handle is not pollable.
}  //

QUICKCPPLIB_BITFIELD_BEGIN_T() [2/2]

llfio_v2_xxx::QUICKCPPLIB_BITFIELD_BEGIN_T	(	tls_socket_source_implementation_features	,
		uint32_t
	)

Feature bits for TLS socket sources.

< No bits set

< This socket source provides kernel sockets i.e. their native handles will be valid kernel sockets which can be used in poll() etc

< This socket source is the "system" rather than "third party" implementation for TLS sockets

< This socket source provides an i/o multiplexer

< This socket source may be able to wrap third party plain sockets

< This socket source provides FIPS_140_2 compliant algorithms

< All bits set

                                                                                 {
none = 0U,  //!< No bits set
 
kernel_sockets =
(1U << 0U),  //!< This socket source provides kernel sockets i.e. their native handles will be valid kernel sockets which can be used in `poll()` etc
system_implementation = (1U << 1U),  //!< This socket source is the "system" rather than "third party" implementation for TLS sockets
io_multiplexer = (1U << 2U),         //!< This socket source provides an i/o multiplexer
supports_wrap = (1U << 3U),          //!< This socket source may be able to wrap third party plain sockets
 
FIPS_140_2 = (1U << 16U),  //!< This socket source provides FIPS_140_2 compliant algorithms
 
all = 0xffffffff  //!< All bits set
}  //

read() [1/2]

byte_io_handle::io_result<byte_io_handle::buffers_type> llfio_v2_xxx::read ( byte_io_handle &  self, byte_io_handle::io_request< byte_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

self	The object whose member function to call.
reqs	A scatter-gather and offset request.
d	An 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\n 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\n The default synchronous implementation in file_handle performs no memory allocation.

{
  return self.read(std::forward<decltype(reqs)>(reqs), std::forward<decltype(d)>(d));
}

read() [2/2]

map_handle::io_result<map_handle::buffers_type> llfio_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

self	The object whose member function to call.
reqs	A scatter-gather and offset request.
d	Ignored.

Errors returnable\n None, though the various signals and structured exception throws common to using memory maps may occur.

Memory Allocations\n None.

{
  return self.read(std::forward<decltype(reqs)>(reqs), std::forward<decltype(d)>(d));
}

relink()

result<void> llfio_v2_xxx::relink ( fs_handle &  self, const path_handle &  base, fs_handle::path_view_type  path, 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

self	The object whose member function to call.
base	Base for any relative path.
path	The relative or absolute new path to relink to.
atomic_replace	Atomically 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.
d	The deadline by which the matching of the containing directory to the open handle's inode must succeed, else errc::timed_out will be returned.

Memory Allocations\n Except on platforms with race free syscalls for renaming open handles (Windows), calls

current_path() via parent_path_handle() and thus is both expensive and calls malloc many times.

{
  return self.relink(std::forward<decltype(base)>(base), std::forward<decltype(path)>(path), std::forward<decltype(atomic_replace)>(atomic_replace),
                     std::forward<decltype(d)>(d));
}

section() [1/3]

result<section_handle> llfio_v2_xxx::section ( file_handle &  backing, section_handle::extent_type  bytes = 0  )

inlinenoexcept

Create a memory section backed by a file.

Parameters

backing	The handle to use as backing storage.
bytes	The initial size of this section, which cannot be larger than any backing file. Zero means to use backing.maximum_extent().

This convenience overload create a writable section if the backing file is writable, otherwise a read-only section.

Errors returnable\n Any of the values POSIX dup(), open() or NtCreateSection() can return.

{
  return section_handle::section(std::forward<decltype(backing)>(backing), std::forward<decltype(bytes)>(bytes));
}

section() [2/3]

result<section_handle> llfio_v2_xxx::section ( file_handle &  backing, section_handle::extent_type  maximum_size, section_handle::flag  _flag  )

inlinenoexcept

Create a memory section backed by a file.

Parameters

backing	The handle to use as backing storage.
maximum_size	The initial size of this section, which cannot be larger than any backing file. Zero means to use backing.maximum_extent().
_flag	How to create the section.

Errors returnable\n Any of the values POSIX dup(), open() or NtCreateSection() can return.

{
  return section_handle::section(std::forward<decltype(backing)>(backing), std::forward<decltype(maximum_size)>(maximum_size),
                                 std::forward<decltype(_flag)>(_flag));
}

section() [3/3]

result<section_handle> llfio_v2_xxx::section ( section_handle::extent_type  bytes, const path_handle &  dirh = path_discovery::storage_backed_temporary_files_directory(), section_handle::flag  _flag = section_handle::flag::read | section_handle::flag::write  )

inlinenoexcept

Create a memory section backed by an anonymous, managed file.

Parameters

bytes	The initial size of this section. Cannot be zero.
dirh	Where to create the anonymous, managed file.
_flag	How to create the section.

Errors returnable\n Any of the values POSIX dup(), open() or NtCreateSection() can return.

{
  return section_handle::section(std::forward<decltype(bytes)>(bytes), std::forward<decltype(dirh)>(dirh), std::forward<decltype(_flag)>(_flag));
}

temp_directory()

result<directory_handle> llfio_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 uniquely_named_file(path_discovery::storage_backed_temporary_files_directory()) and the creation parameter is ignored.

Errors returnable\n Any of the values POSIX open() or CreateFile() can return.

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

temp_file()

result<file_handle> llfio_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_first_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 uniquely_named_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\n Any of the values POSIX open() or CreateFile() can return.

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

temp_inode()

result<file_handle> llfio_v2_xxx::temp_inode ( const path_handle &  dirh = path_discovery::storage_backed_temporary_files_directory(), 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

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\n Any of the values POSIX open() or CreateFile() can return.

{
  return file_handle::temp_inode(std::forward<decltype(dirh)>(dirh), std::forward<decltype(_mode)>(_mode), std::forward<decltype(_caching)>(_caching),
                                 std::forward<decltype(flags)>(flags));
}

to_win32_path()

result<filesystem::path> llfio_v2_xxx::to_win32_path ( const fs_handle &  h, win32_path_namespace  mapping = win32_path_namespace::any  )

inlinenoexcept

Maps the current path of h into a form suitable for Win32 APIs. Passes through unmodified on POSIX, so you can use this in portable code.

Returns

The mapped current path of h, which may have been validated to refer to the exact same inode via .unique_id() (see below).

Parameters

h	The handle whose .current_path() is to be mapped into a form suitable for Win32 APIs.
mapping	Which Win32 path namespace to map onto.

This implementation may need to validate that the mapping of the current path of h onto the desired Win32 path namespace does indeed refer to the same file:

• win32_path_namespace::device transforms \!!\Device\... => \\.\... and ensures that the mapped file's unique id matches the original, otherwise returning failure.
• win32_path_namespace::dos enumerates all the DOS devices on the system and what those map onto within the NT kernel namespace. This mapping is for obvious reasons quite slow.
• win32_path_namespace::guid_volume simply fetches the GUID of the volume of the handle, and constructs a valid Win32 path from that.
• win32_path_namespace::any means attempt guid_volume first, and if it fails (e.g. your file is on a network share) then it attempts dos. This semantic may change in the future, however any path emitted will always be a valid Win32 path.

  {
    (void) mapping;
    return h._get_handle().current_path();
  }

truncate() [1/3]

result<file_handle::extent_type> llfio_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

self	The object whose member function to call.
newsize	The bytes to truncate the file to.

Errors returnable\n Any of the values POSIX ftruncate() or SetFileInformationByHandle() can return.

{
  return self.truncate(std::forward<decltype(newsize)>(newsize));
}

truncate() [2/3]

result<map_handle::size_type> llfio_v2_xxx::truncate ( map_handle &  self, map_handle::size_type  newsize, bool  permit_relocation = false  )

inlinenoexcept

Resize the reservation of the memory map without changing the address (unless the map was zero sized, in which case a new address will be chosen).

If shrinking, address space is released on POSIX, and on Windows if the new size is zero. If the new size is zero, the address is set to null to prevent surprises. Windows does not support modifying existing mapped regions, so if the new size is not zero, the call will probably fail. Windows should let you truncate a previous extension however, if it is exact.

If expanding, an attempt is made to map in new reservation immediately after the current address reservation, thus extending the reservation. If anything else is mapped in after the current reservation, the function fails.

Note

On all supported platforms apart from OS X, proprietary flags exist to avoid performing a map if a map extension cannot be immediately placed after the current map. On OS X, we hint where we'd like the new map to go, but if something is already there OS X will place the map elsewhere. In this situation, we delete the new map and return failure, which is inefficient, but there is nothing else we can do.

Returns

The bytes actually reserved.

Parameters

self	The object whose member function to call.
newsize	The bytes to truncate the map reservation to. Rounded up to the nearest page size (POSIX) or 64Kb on Windows.
permit_relocation	Permit the address to change (some OSs provide a syscall for resizing a memory map).

Errors returnable\n Any of the values POSIX mremap(), mmap(addr) or VirtualAlloc(addr) can return.

{
  return self.truncate(std::forward<decltype(newsize)>(newsize), std::forward<decltype(permit_relocation)>(permit_relocation));
}

truncate() [3/3]

result<section_handle::extent_type> llfio_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

self	The object whose member function to call.
newsize	The new size of the memory section, which cannot be zero. Specify zero to use backing.maximum_extent(). This cannot exceed the size of any backing file used if that file is not writable.

Errors returnable\n Any of the values NtExtendSection() or ftruncate() can return.

{
  return self.truncate(std::forward<decltype(newsize)>(newsize));
}

uniquely_named_directory()

result<directory_handle> llfio_v2_xxx::uniquely_named_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\n Any of the values POSIX open() or CreateFile() can return.

{
  return directory_handle::uniquely_named_directory(std::forward<decltype(dirpath)>(dirpath), std::forward<decltype(_mode)>(_mode),
                                                    std::forward<decltype(_caching)>(_caching), std::forward<decltype(flags)>(flags));
}

uniquely_named_file()

result<file_handle> llfio_v2_xxx::uniquely_named_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\n Any of the values POSIX open() or CreateFile() can return.

{
  return file_handle::uniquely_named_file(std::forward<decltype(dirpath)>(dirpath), std::forward<decltype(_mode)>(_mode),
                                          std::forward<decltype(_caching)>(_caching), std::forward<decltype(flags)>(flags));
}

unlink()

result<void> llfio_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

self	The object whose member function to call.
d	The deadline by which the matching of the containing directory to the open handle's inode must succeed, else errc::timed_out will be returned.

Memory Allocations\n 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.

{
  return self.unlink(std::forward<decltype(d)>(d));
}

write() [1/2]

byte_io_handle::io_result<byte_io_handle::const_buffers_type> llfio_v2_xxx::write ( byte_io_handle &  self, byte_io_handle::io_request< byte_io_handle::const_buffers_type >  reqs, deadline  d = deadline()  )

inlinenoexcept

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

self	The object whose member function to call.
reqs	A scatter-gather and offset request.
d	An 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\n 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\n The default synchronous implementation in file_handle performs no memory allocation.

{
  return self.write(std::forward<decltype(reqs)>(reqs), std::forward<decltype(d)>(d));
}

write() [2/2]

map_handle::io_result<map_handle::const_buffers_type> llfio_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

self	The object whose member function to call.
reqs	A scatter-gather and offset request.
d	Ignored.

Errors returnable\n None, though the various signals and structured exception throws common to using memory maps may occur.

Memory Allocations\n None.

{
  return self.write(std::forward<decltype(reqs)>(reqs), std::forward<decltype(d)>(d));
}

zero()

result<file_handle::extent_type> llfio_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

self	The object whose member function to call.
offset	The offset to start zeroing from.
bytes	The number of bytes to zero.
d	An 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\n 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\n The default synchronous implementation in file_handle performs no memory allocation.

{
  return self.zero(std::forward<decltype(offset)>(offset), std::forward<decltype(bytes)>(bytes), std::forward<decltype(d)>(d));
}