Implements an in-memory file which provides a file-like API to a chunk of pre-allocated memory. More...

#include <file.hpp>

Inheritance diagram for pstore::file::in_memory:

Collaboration diagram for pstore::file::in_memory:

Public Types
using	memory_mapper = pstore::in_memory_mapper
	The type which can be used to memory-map instances of in_memory files.

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
	in_memory (std::shared_ptr< void > const &buffer, std::uint64_t const length, std::uint64_t const eof=0, bool const writable=true) noexcept

void	close () override

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	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

std::time_t	latest_time () const override

bool	lock (std::uint64_t const, std::size_t const, lock_kind const, blocking_mode const) 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 const, std::size_t const) override
	Unlocks the file bytes specified by 'offset' and 'size'. More...

std::shared_ptr< void >	data ()
	Returns the underlying memory managed by the file object.

std::size_t	read_buffer (gsl::not_null< void *> buffer, std::size_t nbytes) override
	Reads nbytes from the file, storing them at the location given by buffer. More...

void	write_buffer (gsl::not_null< void const *> ptr, std::size_t nbytes) override
	Writes writes nbytes to the file, reading them from the location given by ptr. More...

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.

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 an in-memory file which provides a file-like API to a chunk of pre-allocated memory.

Member Function Documentation

◆ is_writable()

bool pstore::file::in_memory::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.

◆ lock()

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

inlineoverridevirtual

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::in_memory::path ( ) const

overridevirtual

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.

◆ read_buffer()

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

overridevirtual

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.

Note: This member function is protected in the base class. I make it public here for unit testing.

Implements pstore::file::file_base.

◆ seek()

void pstore::file::in_memory::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::in_memory::unlock	(	std::uint64_t	offset,
		std::size_t	size
	)

inlineoverridevirtual

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.

◆ write_buffer()

void pstore::file::in_memory::write_buffer	(	gsl::not_null< void const *>	ptr,
		std::size_t	nbytes
	)

overridevirtual

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

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

Note: This member function is protected in the base class. I make it public here for unit testing.

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

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ is_writable()

◆ lock()

◆ path()

◆ read_buffer()

◆ seek()

◆ unlock()

◆ write_buffer()