AFIO  v2.00 late alpha
afio_v2_xxx::fs_handle Class Referenceabstract

A handle to something with a device and inode number. More...

#include "fs_handle.hpp"

Inheritance diagram for afio_v2_xxx::fs_handle:
afio_v2_xxx::directory_handle afio_v2_xxx::file_handle afio_v2_xxx::async_file_handle afio_v2_xxx::mapped_file_handle

Public Types

using dev_t = uint64_t
 
using ino_t = uint64_t
 
using path_view_type = path_view
 The path view type used by this handle.
 
using unique_id_type = QUICKCPPLIB_NAMESPACE::integers128::uint128
 The unique identifier type used by this handle.
 

Public Member Functions

dev_t st_dev () const noexcept
 Unless flag::disable_safety_unlinks is set, the device id of the file when opened.
 
ino_t st_ino () const noexcept
 Unless flag::disable_safety_unlinks is set, the inode of the file when opened. When combined with st_dev(), forms a unique identifer on this system.
 
unique_id_type unique_id () const noexcept
 A unique identifier for this handle across the entire system. Can be used in hash tables etc.
 
virtual result< path_handleparent_path_handle (deadline d=std::chrono::seconds(30)) const noexcept
 
virtual result< void > relink (const path_handle &base, path_view_type path, bool atomic_replace=true, deadline d=std::chrono::seconds(30)) noexcept
 
virtual result< void > unlink (deadline d=std::chrono::seconds(30)) noexcept
 

Protected Member Functions

result< void > _fetch_inode () noexcept
 Fill in _devid and _inode from the handle via fstat()
 
virtual const handle_get_handle () const noexcept=0
 
constexpr fs_handle ()
 Default constructor.
 
constexpr fs_handle (dev_t devid, ino_t inode)
 Construct a handle.
 
 fs_handle (const fs_handle &)=delete
 No copy construction (use clone())
 
fs_handleoperator= (const fs_handle &o)=delete
 No copy assignment.
 
constexpr fs_handle (fs_handle &&o) noexcept
 Implicit move construction of fs_handle permitted.
 
fs_handleoperator= (fs_handle &&o) noexcept
 Move assignment of fs_handle permitted.
 

Protected Attributes

dev_t _devid {0}
 
ino_t _inode {0}
 

Detailed Description

A handle to something with a device and inode number.

See also
algorithm::cached_parent_handle_adapter<T>

Member Function Documentation

◆ parent_path_handle()

virtual result<path_handle> afio_v2_xxx::fs_handle::parent_path_handle ( deadline  d = std::chrono::seconds(30)) const
inlinevirtualnoexcept

Obtain a handle to the path currently containing this handle's file entry.

Warning
This call is racy and can result in the wrong path handle being returned. Note that unless flag::disable_safety_unlinks is set, this implementation opens a path_handle to the source containing directory, then checks if the file entry within has the same inode as the open file handle. It will retry this matching until success until the deadline given.
Memory Allocations
Calls current_path() and thus is both expensive and calls malloc many times.
See also
algorithm::cached_parent_handle_adapter<T> which overrides this with a zero cost implementation, thus making unlinking and relinking very considerably quicker.

◆ relink()

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

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
baseBase for any relative path.
pathThe relative or absolute new path to relink to.
atomic_replaceAtomically replace the destination if a file entry already is present there. Choosing false for this will fail if a file entry is already present at the destination, and may not be an atomic operation on some platforms (i.e. both the old and new names may be linked to the same inode for a very short period of time). Windows and recent Linuxes are always atomic.
dThe deadline by which the matching of the containing directory to the open handle's inode must succeed, else std::errc::timed_out will be returned.
Memory Allocations
Except on platforms with race free syscalls for renaming open handles (Windows), calls current_path() via parent_path_handle() and thus is both expensive and calls malloc many times.

◆ unlink()

virtual result<void> afio_v2_xxx::fs_handle::unlink ( deadline  d = std::chrono::seconds(30))
inlinevirtualnoexcept

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
dThe deadline by which the matching of the containing directory to the open handle's inode must succeed, else std::errc::timed_out will be returned.
Memory Allocations
Except on platforms with race free syscalls for unlinking open handles (Windows), calls current_path() and thus is both expensive and calls malloc many times. On Windows, also calls current_path() if flag::disable_safety_unlinks is not set.

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