Implements a portable file access API. More...

#include <file.hpp>

Inheritance diagram for pstore::file::file_handle:

Collaboration diagram for pstore::file::file_handle:

Classes
struct	temporary
	temporary is an empty class type used to disambiguate the overloads of creating a file. More...

struct	unique
	unique is an empty class type used to disambiguate the overloads of creating a file. More...

Public Types
enum	create_mode { create_mode::create_new, create_mode::open_existing, create_mode::open_always }

enum	present_mode { present_mode::allow_not_found, present_mode::must_exist }
	Controls the behavior of the file_handle constructor when passed a path which does not already exist. More...

enum	writable_mode { read_only, read_write }
	Controls whether the file_handle constructor produces a read-only or read/write object. More...

using	memory_mapper = pstore::memory_mapper
	The type which can be used to memory-map instances of physcial files.

using	oshandle = int

Public Types inherited from pstore::file::file_base
enum	blocking_mode { blocking_mode::non_blocking, blocking_mode::blocking }
	Indicates whether the lock() method should block until the lock has been obtained. More...

enum	lock_kind { lock_kind::shared_read, lock_kind::exclusive_write }
	Represents the type of file range lock to be obtained. More...

Public Member Functions
	file_handle (std::string path) noexcept

	file_handle (file_handle const &)=delete

	file_handle (file_handle &&other) noexcept

file_handle &	operator= (file_handle &&rhs) noexcept

file_handle &	operator= (file_handle const &)=delete

void	open (create_mode create, writable_mode writable, present_mode present=present_mode::allow_not_found)

void	open (unique, std::string const &directory)
	Create a new, uniquely named, file in the specified directory.

void	open (temporary const t)
	Creates a temporary file in the system temporary directory.

void	open (temporary, std::string const &directory)
	Creates a temporary file in the specified directory.

bool	is_open () const noexcept override

bool	is_writable () const noexcept override
	Return true if the object was created as writable. More...

std::string	path () const override
	Returns the name of the file originally associated with this file object. More...

void	close () override

void	seek (std::uint64_t position) override
	Sets the file position indicator for the file. More...

std::uint64_t	tell () override
	Obtains the current value of the position indicator for the file.

std::uint64_t	size () override

void	truncate (std::uint64_t size) override

bool	rename (std::string const &new_name)
	Renames a file from one UTF-8 encoded path to another. More...

std::time_t	latest_time () const override

bool	lock (std::uint64_t offset, std::size_t size, lock_kind kind, blocking_mode block) override
	Obtains a shared-read or exclusive-write lock on the file range specified by the 'offset' and size' parameters. More...

void	unlock (std::uint64_t offset, std::size_t size) override
	Unlocks the file bytes specified by 'offset' and 'size'. More...

oshandle	raw_handle () noexcept

Public Member Functions inherited from pstore::file::file_base
	file_base (file_base &&) noexcept=default

	file_base (file_base const &)=default

file_base &	operator= (file_base &&) noexcept=default

file_base &	operator= (file_base const &)=default

template<typename SpanType , typename = typename std::enable_if<std::is_standard_layout< typename SpanType::element_type>::value>::type>
std::size_t	read_span (SpanType const &s)
	Reads instances of a standard-layout type from the file. More...

template<typename T , typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>
void	read (T *const t)
	Reads a series of raw bytes from the file as an instance of type T.

template<typename SpanType , typename = typename std::enable_if<std::is_standard_layout< typename SpanType::element_type>::value>::type>
void	write_span (SpanType const &s)
	Writes instances of a standard-layout type to the file.

template<typename T , typename = typename std::enable_if<std::is_standard_layout<T>::value>::type>
void	write (T const &t)
	Writes 't' as a series of raw bytes to the file.

Static Public Member Functions
static std::string	get_temporary_directory ()
	Returns a UTF-8 encoded string representing the temporary directory. More...

Static Public Attributes
static constexpr oshandle	invalid_oshandle = -1

Additional Inherited Members
Raw file I/O
The following methods are protected because they provide the raw read/write-bytes functions. Use of the read_span(), write_span(), and write() template convenience functions is preferred.

Detailed Description

Implements a portable file access API.

Member Enumeration Documentation

◆ create_mode

enum pstore::file::file_handle::create_mode

strong

Enumerator
create_new	Creates a new file, only if it does not already exist.
open_existing	Opens a file only if it already exists.
open_always	Opens an existing file if present or creates a new file otherwise.

◆ present_mode

enum pstore::file::file_handle::present_mode

strong

Controls the behavior of the file_handle constructor when passed a path which does not already exist.

Enumerator

allow_not_found

If opening a file that does not exist, an exception will not be raised.

The condition can be detected by calling is_open() and testing for a true result. If the file was not found, then any attempt to operate on the file – such as reading, writing, seeking, and so on – will fail with an exception being raised.

must_exist

If attempting to open a file that does not exist, an exception is raised.

This mode is meaningless if used in conjunction with create_mode::create_new..

◆ writable_mode

enum pstore::file::file_handle::writable_mode

strong

Controls whether the file_handle constructor produces a read-only or read/write object.

Member Function Documentation

◆ get_temporary_directory()

std::string pstore::file::file_handle::get_temporary_directory ( )

static

Returns a UTF-8 encoded string representing the temporary directory.

Note: The code determines the temporary directory using the Win32 GetTempPathW() API which performs no validation on the path. The code needs to be prepared for an attempt to create a file in this directory to fail.

◆ is_writable()

bool pstore::file::file_handle::is_writable ( ) const

inlineoverridevirtualnoexcept

Return true if the object was created as writable.

Note: This does not necessarily reflect the underlying file system's read/write flag: this function may return true, but a write() might still fail.

Implements pstore::file::file_base.

◆ latest_time()

std::time_t pstore::file::file_handle::latest_time ( ) const

overridevirtual

The time members of struct stat might be called st_Xtimespec (of type struct timespec) or st_Xtime (and be of type time_t). This macro is defined in the former situation.

Implements pstore::file::file_base.

◆ lock()

bool pstore::file::file_handle::lock	(	std::uint64_t	offset,
		std::size_t	size,
		lock_kind	lt,
		blocking_mode	bl
	)

overridevirtual

Obtains a shared-read or exclusive-write lock on the file range specified by the 'offset' and size' parameters.

If the blocking-mode is 'blocking' and another process has an exclusive_write lock on the specified range, then the call will block execution until the lock is acquired.

Note: lock() is usually not called directly: range_lock, wrapped with std::unique_lock<>, is used to coordinate calls to lock() and unlock().

Parameters

offset	The offset of the first byte of the file to be locked.
size	The number of bytes to be locked.
lt	Specifies the type of lock to be obtained
bl	Indicates whether the function should block until the lock has been obtained or return immediately.

Returns: True if the lock was successfully obtained, false otherwise.

Implements pstore::file::file_base.

◆ path()

std::string pstore::file::file_handle::path ( ) const

inlineoverridevirtual

Returns the name of the file originally associated with this file object.

Note: Depending on the host operating system, if the file was moved or deleted since it was opened, the result may no longer be accurate.

Returns: The name of the file originally associated with the file object.

Implements pstore::file::file_base.

◆ rename()

bool pstore::file::file_handle::rename ( std::string const & new_name )

Renames a file from one UTF-8 encoded path to another.

Returns: True on success, false if the rename failed because the target file already existed.

◆ seek()

void pstore::file::file_handle::seek ( std::uint64_t position )

overridevirtual

Sets the file position indicator for the file.

The new position, measured in bytes, is given by the 'position' parameter.

Parameters

position The file offset to be used as the file position indicator.

Implements pstore::file::file_base.

◆ unlock()

void pstore::file::file_handle::unlock	(	std::uint64_t	offset,
		std::size_t	size
	)

overridevirtual

Unlocks the file bytes specified by 'offset' and 'size'.

The same file range must be locked by the current process, otherwise, the behavior is undefined.

Note: unlock() is usually not called directly: range_lock, wrapped with std::unique_lock<>, is used to coordinate calls to lock() and unlock().

Parameters

offset	The offset of the first byte of the file to be locked.
size	The number of bytes to be locked.

Implements pstore::file::file_base.

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

include/pstore/os/file.hpp
lib/os/file.cpp
lib/os/file_posix.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ create_mode

◆ present_mode

◆ writable_mode

Member Function Documentation

◆ get_temporary_directory()

◆ is_writable()

◆ latest_time()

◆ lock()

◆ path()

◆ rename()

◆ seek()

◆ unlock()