An abstract file class. Provides the interface for file access. More...

#include <file.hpp>

Inheritance diagram for pstore::file::file_base:

Public Member Functions
	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

virtual bool	is_open () const noexcept=0

virtual void	close ()=0

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

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

virtual void	seek (std::uint64_t position)=0
	Sets the file position indicator for the file. More...

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

virtual std::time_t	latest_time () const =0

virtual std::uint64_t	size ()=0

virtual void	truncate (std::uint64_t size)=0


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.

Protected Member Functions
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.
virtual std::size_t	read_buffer (gsl::not_null< void *> buffer, std::size_t nbytes)=0
	Reads nbytes from the file, storing them at the location given by buffer. More...

virtual void	write_buffer (gsl::not_null< void const *> buffer, std::size_t nbytes)=0
	Writes nbytes to the file, reading them from the location given by buffer. More...

File range locking
Two kinds of locks are offered: shared locks and exclusive locks. Shared locks can be acquired by a number of processes at the same time, but an exclusive lock can only be acquired by one process, and cannot coexist with a shared lock. To acquire a shared lock, a process must wait until no processes hold any exclusive locks. To acquire an exclusive lock, a process must wait until no processes hold either kind of lock. Shared locks are sometimes called "read locks" and exclusive locks are sometimes called "write locks".
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...

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

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

Detailed Description

An abstract file class. Provides the interface for file access.

Member Enumeration Documentation

◆ blocking_mode

enum pstore::file::file_base::blocking_mode

strong

Indicates whether the lock() method should block until the lock has been obtained.

Enumerator
non_blocking	The call will return immediately.
blocking	The call will block until the lock has been obtained.

◆ lock_kind

enum pstore::file::file_base::lock_kind

strong

Represents the type of file range lock to be obtained.

Enumerator
shared_read	Specifies a read (or shared) lock.
exclusive_write	Specifies a write (or exclusive) lock.

Member Function Documentation

◆ is_writable()

virtual bool pstore::file::file_base::is_writable ( ) const

pure virtualnoexcept

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.

Implemented in pstore::file::file_handle, and pstore::file::in_memory.

◆ lock()

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

pure virtual

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.

Implemented in pstore::file::file_handle, and pstore::file::in_memory.

◆ path()

virtual std::string pstore::file::file_base::path ( ) const

pure virtual

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.

Implemented in pstore::file::file_handle, and pstore::file::in_memory.

◆ read_buffer()

virtual std::size_t pstore::file::file_base::read_buffer	(	gsl::not_null< void *>	buffer,
		std::size_t	nbytes
	)

protectedpure virtual

Reads nbytes from the file, storing them at the location given by buffer.

Returns the number of bytes read. The file position indicator for the file is incremented by the number of bytes read.

Parameters

buffer	A pointer to the memory which will recieve bytes read from the file. There must be at least nbytes available.
nbytes	The number of bytes that are to be read.

Returns: The number of bytes actually read.

Implemented in pstore::file::in_memory.

◆ read_span()

template<typename SpanType , typename = typename std::enable_if<std::is_standard_layout< typename SpanType::element_type>::value>::type>

std::size_t pstore::file::file_base::read_span ( SpanType const & s )

inline

Reads instances of a standard-layout type from the file.

Reads a contigious series of instances of SpanType::element_type, which must be a StandardLayoutType.

Parameters

s	A span of instances which may contain zero or more members.

Returns: The number of bytes read.

◆ seek()

virtual void pstore::file::file_base::seek ( std::uint64_t position )

pure virtual

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.

Implemented in pstore::file::file_handle, and pstore::file::in_memory.

◆ unlock()

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

pure virtual

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.

Implemented in pstore::file::file_handle, and pstore::file::in_memory.

◆ write_buffer()

virtual void pstore::file::file_base::write_buffer	(	gsl::not_null< void const *>	buffer,
		std::size_t	nbytes
	)

protectedpure virtual

Writes nbytes to the file, reading them from the location given by buffer.

The file position indicator for the file is incremented by the number of bytes written.

Parameters

buffer	A pointer to the memory containing the data to be written. At least 'nbytes' must be available.
nbytes	The number of bytes that are to be written.

Implemented in pstore::file::in_memory.

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

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

Public Member Functions

Protected Member Functions

File range locking

Detailed Description

Member Enumeration Documentation

◆ blocking_mode

◆ lock_kind

Member Function Documentation

◆ is_writable()

◆ lock()

◆ path()

◆ read_buffer()

◆ read_span()

◆ seek()

◆ unlock()

◆ write_buffer()