llfio_v2_xxx::section_handle Class Reference

A handle to a source of mapped memory. More...

#include "map_handle.hpp"

Inheritance diagram for llfio_v2_xxx::section_handle:

Public Types
using	extent_type = handle::extent_type
using	size_type = handle::size_type
enum	mode : unsigned char {   unchanged = 0, mode::none = 2, mode::attr_read = 4, mode::attr_write = 5,   mode::read = 6, mode::write = 7, mode::append = 9 }
	The behaviour of the handle: does it read, read and write, or atomic append? More...
enum	creation : unsigned char {   creation::open_existing = 0, creation::only_if_not_exist, creation::if_needed, creation::truncate_existing,   creation::always_new }
	On opening, do we also create a new file or truncate an existing one? More...
enum	caching : unsigned char {   unchanged = 0, caching::none = 1, caching::only_metadata = 2, caching::reads = 3,   caching::reads_and_metadata = 5, caching::all = 6, caching::safety_barriers = 7, caching::temporary = 8 }
	What i/o on the handle may complete immediately due to kernel caching. More...
using	path_type = filesystem::path
	The path type used by this handle.

Public Member Functions
	QUICKCPPLIB_BITFIELD_BEGIN (flag)
	The behaviour of the memory section. More...
	QUICKCPPLIB_BITFIELD_END (flag)
virtual result< void >	close () noexcept override
	Immediately close the native handle type managed by this handle.
constexpr	section_handle ()
	Default constructor.
	section_handle (native_handle_type sectionh, file_handle *backing, file_handle anonymous, flag __flag)
	Construct a section handle using the given native handle type for the section and the given i/o handle for the backing storage.
constexpr	section_handle (section_handle &&o) noexcept
	Implicit move construction of section_handle permitted.
	section_handle (const section_handle &)=delete
	No copy construction (use clone())
section_handle &	operator= (section_handle &&o) noexcept
	Move assignment of section_handle permitted.
section_handle &	operator= (const section_handle &)=delete
	No copy assignment.
void	swap (section_handle &o) noexcept
	Swap with another instance.
flag	section_flags () const noexcept
	Returns the memory section's flags.
bool	is_nvram () const noexcept
	True if the section reflects non-volatile RAM.
file_handle *	backing () const noexcept
	Returns the borrowed handle backing this section, if any.
void	set_backing (file_handle *fh) noexcept
	Sets the borrowed handle backing this section, if any.
native_handle_type	backing_native_handle () const noexcept
	Returns the borrowed native handle backing this section.
result< extent_type >	length () const noexcept
	Return the current length of the memory section.
result< extent_type >	truncate (extent_type newsize=0) noexcept
void	swap (handle &o) noexcept
	Swap with another instance.
virtual result< path_type >	current_path () const noexcept
result< handle >	clone () const noexcept
virtual native_handle_type	release () noexcept
	Release the native handle type managed by this handle.
bool	is_valid () const noexcept
	True if the handle is valid (and usually open)
bool	is_readable () const noexcept
	True if the handle is readable.
bool	is_writable () const noexcept
	True if the handle is writable.
bool	is_append_only () const noexcept
	True if the handle is append only.
virtual result< void >	set_append_only (bool enable) noexcept
	EXTENSION: Changes whether this handle is append only or not. More...
bool	is_overlapped () const noexcept
	True if overlapped.
bool	is_seekable () const noexcept
	True if seekable.
bool	requires_aligned_io () const noexcept
	True if requires aligned i/o.
bool	is_regular () const noexcept
	True if a regular file or device.
bool	is_directory () const noexcept
	True if a directory.
bool	is_symlink () const noexcept
	True if a symlink.
bool	is_multiplexer () const noexcept
	True if a multiplexer like BSD kqueues, Linux epoll or Windows IOCP.
bool	is_process () const noexcept
	True if a process.
bool	is_section () const noexcept
	True if a memory section.
caching	kernel_caching () const noexcept
	Kernel cache strategy used by this handle.
bool	are_reads_from_cache () const noexcept
	True if the handle uses the kernel page cache for reads.
bool	are_writes_durable () const noexcept
	True if writes are safely on storage on completion.
bool	are_safety_barriers_issued () const noexcept
	True if issuing safety fsyncs is on.
flag	flags () const noexcept
	The flags this handle was opened with.
native_handle_type	native_handle () const noexcept
	The native handle used by this handle.

Static Public Member Functions
static result< section_handle >	section (file_handle &backing, extent_type maximum_size, flag _flag) noexcept
	Create a memory section backed by a file. More...
static result< section_handle >	section (file_handle &backing, extent_type bytes=0) noexcept
	Create a memory section backed by a file. More...
static result< section_handle >	section (extent_type bytes, const path_handle &dirh=path_discovery::storage_backed_temporary_files_directory(), flag _flag=flag::read|flag::write) noexcept
	Create a memory section backed by an anonymous, managed file. More...

Protected Attributes
file_handle *	_backing {nullptr}
file_handle	_anonymous
flag	_flag {flag::none}
caching	_caching {caching::none}
flag	_flags {flag::none}
native_handle_type	_v

Detailed Description

A handle to a source of mapped memory.

There are two configurations of section handle, one where the user supplies the file backing for the section, and the other where an internal file descriptor to an unnamed inode in a tmpfs or ramfs based temporary directory is kept and managed. The latter is merely a convenience for creating an anonymous source of memory which can be resized whilst preserving contents: see algorithm::trivial_vector<T>.

On Windows the native handle of this handle is that of the NT kernel section object. On POSIX it is a cloned file descriptor of the backing storage if there is backing storage, else it will be the aforementioned file descriptor to an unnamed inode.

Member Enumeration Documentation

caching

enum llfio_v2_xxx::handle::caching : unsigned char

stronginherited

What i/o on the handle may complete immediately due to kernel caching.

Enumerator
none	No caching whatsoever, all reads and writes come from storage (i.e. O_DIRECT|O_SYNC). Align all i/o to 4Kb boundaries for this to work. disable_safety_barriers can be used here.
only_metadata	Cache reads and writes of metadata but avoid caching data (O_DIRECT), thus i/o here does not affect other cached data for other handles. Align all i/o to 4Kb boundaries for this to work.
reads	Cache reads only. Writes of data and metadata do not complete until reaching storage (O_SYNC). disable_safety_barriers can be used here.
reads_and_metadata	Cache reads and writes of metadata, but writes of data do not complete until reaching storage (O_DSYNC). disable_safety_barriers can be used here.
all	Cache reads and writes of data and metadata so they complete immediately, sending writes to storage at some point when the kernel decides (this is the default file system caching on a system).
safety_barriers	Cache reads and writes of data and metadata so they complete immediately, but issue safety barriers at certain points. See documentation for disable_safety_barriers.
temporary	Cache reads and writes of data and metadata so they complete immediately, only sending any updates to storage on last handle close in the system or if memory becomes tight as this file is expected to be temporary (Windows and FreeBSD only).

                     : unsigned char  // bit 0 set means safety barriers enabled
  {
    unchanged = 0,
    none = 1,                //!< No caching whatsoever, all reads and writes come from storage (i.e. <tt>O_DIRECT|O_SYNC</tt>). Align all i/o to 4Kb boundaries for this to work. <tt>disable_safety_barriers</tt> can be used here.
    only_metadata = 2,       //!< Cache reads and writes of metadata but avoid caching data (<tt>O_DIRECT</tt>), thus i/o here does not affect other cached data for other handles. Align all i/o to 4Kb boundaries for this to work.
    reads = 3,               //!< Cache reads only. Writes of data and metadata do not complete until reaching storage (<tt>O_SYNC</tt>). <tt>disable_safety_barriers</tt> can be used here.
    reads_and_metadata = 5,  //!< Cache reads and writes of metadata, but writes of data do not complete until reaching storage (<tt>O_DSYNC</tt>). <tt>disable_safety_barriers</tt> can be used here.
    all = 6,                 //!< Cache reads and writes of data and metadata so they complete immediately, sending writes to storage at some point when the kernel decides (this is the default file system caching on a system).
    safety_barriers = 7,     //!< Cache reads and writes of data and metadata so they complete immediately, but issue safety barriers at certain points. See documentation for <tt>disable_safety_barriers</tt>.
    temporary = 8            //!< Cache reads and writes of data and metadata so they complete immediately, only sending any updates to storage on last handle close in the system or if memory becomes tight as this file is expected to be temporary (Windows and FreeBSD only).
                             // NOTE: IF UPDATING THIS UPDATE THE std::ostream PRINTER BELOW!!!
  };

creation

enum llfio_v2_xxx::handle::creation : unsigned char

stronginherited

On opening, do we also create a new file or truncate an existing one?

Enumerator
open_existing	Filesystem entry must already exist.
only_if_not_exist	Filesystem entry must NOT exist, and is atomically created by the success of this operation.
if_needed	If filesystem entry exists that is used, else one is created.
truncate_existing	Filesystem entry must already exist. It is atomically truncated on open, leaving creation date and unique identifier unmodified.
always_new	If filesystem entry exists, it is atomically replaced with a new inode, else a new entry is created.

                      : unsigned char
  {
    open_existing = 0,  //!< Filesystem entry must already exist
    only_if_not_exist,  //!< Filesystem entry must NOT exist, and is atomically created by the success of this operation
    if_needed,          //!< If filesystem entry exists that is used, else one is created
    truncate_existing,  //!< Filesystem entry must already exist. It is atomically truncated on open, leaving creation date and unique identifier unmodified.
    always_new          //!< If filesystem entry exists, it is atomically replaced with a new inode, else a new entry is created.
                        // NOTE: IF UPDATING THIS UPDATE THE std::ostream PRINTER BELOW!!!
  };

mode

enum llfio_v2_xxx::handle::mode : unsigned char

stronginherited

The behaviour of the handle: does it read, read and write, or atomic append?

Enumerator
none	No ability to read or write anything, but can synchronise (SYNCHRONIZE or 0)
attr_read	Ability to read attributes (FILE_READ_ATTRIBUTES|SYNCHRONIZE or O_RDONLY)
attr_write	Ability to read and write attributes (FILE_READ_ATTRIBUTES|FILE_WRITE_ATTRIBUTES|SYNCHRONIZE or O_RDONLY)
read	Ability to read (READ_CONTROL|FILE_READ_DATA|FILE_READ_ATTRIBUTES|FILE_READ_EA|SYNCHRONISE or O_RDONLY)
write	Ability to read and write (READ_CONTROL|FILE_READ_DATA|FILE_READ_ATTRIBUTES|FILE_READ_EA|FILE_WRITE_DATA|FILE_WRITE_ATTRIBUTES|FILE_WRITE_EA|FILE_APPEND_DATA|SYNCHRONISE or O_RDWR)
append	All mainstream OSs and CIFS guarantee this is atomic with respect to all other appenders (FILE_APPEND_DATA|SYNCHRONISE or O_APPEND)

                  : unsigned char  // bit 0 set means writable
  {
    unchanged = 0,
    none = 2,        //!< No ability to read or write anything, but can synchronise (SYNCHRONIZE or 0)
    attr_read = 4,   //!< Ability to read attributes (FILE_READ_ATTRIBUTES|SYNCHRONIZE or O_RDONLY)
    attr_write = 5,  //!< Ability to read and write attributes (FILE_READ_ATTRIBUTES|FILE_WRITE_ATTRIBUTES|SYNCHRONIZE or O_RDONLY)
    read = 6,        //!< Ability to read (READ_CONTROL|FILE_READ_DATA|FILE_READ_ATTRIBUTES|FILE_READ_EA|SYNCHRONISE or O_RDONLY)
    write = 7,       //!< Ability to read and write (READ_CONTROL|FILE_READ_DATA|FILE_READ_ATTRIBUTES|FILE_READ_EA|FILE_WRITE_DATA|FILE_WRITE_ATTRIBUTES|FILE_WRITE_EA|FILE_APPEND_DATA|SYNCHRONISE or O_RDWR)
    append = 9       //!< All mainstream OSs and CIFS guarantee this is atomic with respect to all other appenders (FILE_APPEND_DATA|SYNCHRONISE or O_APPEND)
                     // NOTE: IF UPDATING THIS UPDATE THE std::ostream PRINTER BELOW!!!
  };

Member Function Documentation

clone()

result<handle> llfio_v2_xxx::handle::clone ( ) const

inlinenoexceptinherited

Clone this handle (copy constructor is disabled to avoid accidental copying)

Errors returnable

Any of the values POSIX dup() or DuplicateHandle() can return.

current_path()

virtual result<path_type> llfio_v2_xxx::handle::current_path ( ) const

inlinevirtualnoexceptinherited

Returns the current path of the open handle as said by the operating system. Note that you are NOT guaranteed that any path refreshed bears any resemblance to the original, some operating systems will return some different path which still reaches the same inode via some other route e.g. hardlinks, dereferenced symbolic links, etc. Windows and Linux correctly track changes to the specific path the handle was opened with, not getting confused by other hard links. MacOS nearly gets it right, but under some circumstances e.g. renaming may switch to a different hard link's path which is almost certainly a bug.

If LLFIO was not able to determine the current path for this open handle e.g. the inode has been unlinked, it returns an empty path. Be aware that FreeBSD can return an empty (deleted) path for file inodes no longer cached by the kernel path cache, LLFIO cannot detect the difference. FreeBSD will also return any path leading to the inode if it is hard linked. FreeBSD does implement path retrieval for directory inodes correctly however, and see algorithm::cached_parent_handle_adapter<T> for a handle adapter which makes use of that.

On Linux if /proc is not mounted, this call fails with an error. All APIs in LLFIO which require the use of current_path() can be told to not use it e.g. flag::disable_safety_unlinks. It is up to you to detect if current_path() is not working, and to change how you call LLFIO appropriately.

Warning

This call is expensive, it always asks the kernel for the current path, and no checking is done to ensure what the kernel returns is accurate or even sensible. Be aware that despite these precautions, paths are unstable and can change randomly at any moment. Most code written to use absolute file systems paths is racy, so don't do it, use path_handle to fix a base location on the file system and work from that anchor instead!

Memory Allocations

At least one malloc for the path_type, likely several more.

See also

algorithm::cached_parent_handle_adapter<T> which overrides this with an implementation based on retrieving the current path of a cached handle to the parent directory. On platforms with instability or failure to retrieve the correct current path for regular files, the cached parent handle adapter works around the problem by taking advantage of directory inodes not having the same instability problems on any platform.

Reimplemented in llfio_v2_xxx::symlink_handle.

QUICKCPPLIB_BITFIELD_BEGIN()

llfio_v2_xxx::section_handle::QUICKCPPLIB_BITFIELD_BEGIN ( flag  )

inline

The behaviour of the memory section.

< No flags

< Memory views can be read

< Memory views can be written

< Memory views can be copy on written

< Memory views can execute code

< Don't allocate space for this memory in the system immediately

< Prefault, as if by reading every page, any views of memory upon creation.

< The backing storage is in fact an executable program binary.

< A single instance of this section is to be shared by all processes using the same backing file.

< Maps of this section, if writable, issue a barrier() when destructed blocking until data (not metadata) reaches physical storage.

< This section is of non-volatile RAM

< Use utils::page_sizes()[1] sized pages, or fail.

< Use utils::page_sizes()[2] sized pages, or fail.

< Use utils::page_sizes()[3] sized pages, or fail.

                                  {none = 0U,           //!< No flags
                                   read = 1U << 0U,     //!< Memory views can be read
                                   write = 1U << 1U,    //!< Memory views can be written
                                   cow = 1U << 2U,      //!< Memory views can be copy on written
                                   execute = 1U << 3U,  //!< Memory views can execute code

                                   nocommit = 1U << 8U,     //!< Don't allocate space for this memory in the system immediately
                                   prefault = 1U << 9U,     //!< Prefault, as if by reading every page, any views of memory upon creation.
                                   executable = 1U << 10U,  //!< The backing storage is in fact an executable program binary.
                                   singleton = 1U << 11U,   //!< A single instance of this section is to be shared by all processes using the same backing file.

                                   barrier_on_close = 1U << 16U,  //!< Maps of this section, if writable, issue a `barrier()` when destructed blocking until data (not metadata) reaches physical storage.
                                   nvram = 1U << 17U,             //!< This section is of non-volatile RAM

                                   page_sizes_1 = 1U << 24U,  //!< Use `utils::page_sizes()[1]` sized pages, or fail.
                                   page_sizes_2 = 2U << 24U,  //!< Use `utils::page_sizes()[2]` sized pages, or fail.
                                   page_sizes_3 = 3U << 24U,  //!< Use `utils::page_sizes()[3]` sized pages, or fail.

                                   // NOTE: IF UPDATING THIS UPDATE THE std::ostream PRINTER BELOW!!!

                                   readwrite = (read | write)};

section() [1/3]

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

inlinestaticnoexcept

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

Any of the values POSIX dup(), open() or NtCreateSection() can return.

section() [2/3]

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

inlinestaticnoexcept

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

Any of the values POSIX dup(), open() or NtCreateSection() can return.

{ return section(backing, bytes, backing.is_writable() ? (flag::readwrite) : (flag::read)); }

section() [3/3]

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

inlinestaticnoexcept

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

Any of the values POSIX dup(), open() or NtCreateSection() can return.

set_append_only()

virtual result<void> llfio_v2_xxx::handle::set_append_only ( bool  enable )

inlinevirtualnoexceptinherited

EXTENSION: Changes whether this handle is append only or not.

Warning

On Windows this is implemented as a bit of a hack to make it fast like on POSIX, so make sure you open the handle for read/write originally. Note unlike on POSIX the append_only disposition will be the only one toggled, seekable and readable will remain turned on.

Errors returnable

Whatever POSIX fcntl() returns. On Windows nothing is changed on the handle.

Memory Allocations

No memory allocation.

truncate()

result<extent_type> llfio_v2_xxx::section_handle::truncate ( extent_type  newsize = 0 )

inlinenoexcept

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

Parameters

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

Any of the values NtExtendSection() or ftruncate() can return.

---

The documentation for this class was generated from the following file:

• include/llfio/v2.0/map_handle.hpp