File implementation by positional access and locking for parallel operations. More...

#include <tkrzw_file_pos.h>

Public Member Functions
	PositionalParallelFile ()
	Default constructor. More...

	~PositionalParallelFile ()
	Destructor. More...

	PositionalParallelFile (const PositionalParallelFile &rhs)=delete
	Copy and assignment are disabled. More...

PositionalParallelFile &	operator= (const PositionalParallelFile &rhs)=delete

Status	Open (const std::string &path, bool writable, int32_t options=OPEN_DEFAULT) override
	Opens a file. More...

Status	Close () override
	Closes the file. More...

Status	Read (int64_t off, void *buf, size_t size) override
	Reads data. More...

Status	Write (int64_t off, const void *buf, size_t size) override
	Writes data. More...

Status	Append (const void buf, size_t size, int64_t off=nullptr) override
	Appends data at the end of the file. More...

Status	Expand (size_t inc_size, int64_t *old_size=nullptr) override
	Expands the file size without writing data. More...

Status	Truncate (int64_t size) override
	Truncates the file. More...

Status	TruncateFakely (int64_t size) override
	Truncate the file fakely. More...

Status	Synchronize (bool hard, int64_t off=0, int64_t size=0) override
	Synchronizes the content of the file to the file system. More...

Status	GetSize (int64_t *size) override
	Gets the size of the file. More...

Status	SetHeadBuffer (int64_t size) override
	Sets the head buffer to cache the beginning region of the file. More...

Status	SetAccessStrategy (int64_t block_size, int32_t options) override
	Sets access strategy. More...

Status	SetAllocationStrategy (int64_t init_size, double inc_factor) override
	Sets allocation strategy. More...

Status	CopyProperties (File *file) override
	Copies internal properties to another file object. More...

Status	GetPath (std::string *path) override
	Gets the path of the file. More...

Status	Rename (const std::string &new_path) override
	Renames the file. More...

Status	DisablePathOperations () override
	Disables operations related to the path. More...

bool	IsOpen () const override
	Checks whether the file is open. More...

bool	IsMemoryMapping () const override
	Checks whether operations are done by memory mapping. More...

bool	IsAtomic () const override
	Checks whether updating operations are atomic and thread-safe. More...

int64_t	GetBlockSize () const override
	Gets the block size. More...

bool	IsDirectIO () const override
	Checks whether the access mode is direct I/O. More...

std::unique_ptr< File >	MakeFile () const override
	Makes a new file object of the same concrete class. More...

Public Member Functions inherited from tkrzw::PositionalFile
virtual	~PositionalFile ()=default
	Destructor. More...

Public Member Functions inherited from tkrzw::File
virtual	~File ()=default
	Destructor. More...

virtual std::string	ReadSimple (int64_t off, size_t size)
	Reads data, in a simple way. More...

virtual bool	WriteSimple (int64_t off, std::string_view data)
	Writes data, in a simple way. More...

virtual int64_t	AppendSimple (const std::string &data)
	Appends data at the end of the file, in a simple way. More...

virtual int64_t	ExpandSimple (size_t inc_size)
	Expands the file size without writing data, in a simple way. More...

virtual int64_t	GetSizeSimple ()
	Gets the size of the file, in a simple way. More...

virtual std::string	GetPathSimple ()
	Gets the path of the file, in a simple way. More...

const std::type_info &	GetType () const
	Gets the type information of the actual class. More...

Additional Inherited Members
Public Types inherited from tkrzw::PositionalFile
enum	AccessOption : int32_t { ACCESS_DEFAULT = 0 , ACCESS_DIRECT = 1 << 0 , ACCESS_SYNC = 1 << 1 , ACCESS_PADDING = 1 << 2 , ACCESS_PAGECACHE = 1 << 3 }
	Enumeration of options for SetAccessStrategy. More...

Public Types inherited from tkrzw::File
enum	OpenOption : int32_t { OPEN_DEFAULT = 0 , OPEN_TRUNCATE = 1 << 0 , OPEN_NO_CREATE = 1 << 1 , OPEN_NO_WAIT = 1 << 2 , OPEN_NO_LOCK = 1 << 3 , OPEN_SYNC_HARD = 1 << 4 }
	Enumeration of options for Open. More...

Static Public Attributes inherited from tkrzw::File
static constexpr int64_t	DEFAULT_ALLOC_INIT_SIZE = 1LL << 20
	The default value of the initial allocation size. More...

static constexpr double	DEFAULT_ALLOC_INC_FACTOR = 2.0
	The default value of the allocation increment factor. More...

Detailed Description

File implementation by positional access and locking for parallel operations.

Reading and writing operations are thread-safe; Multiple threads can access the same file concurrently. Other operations including Open, Close, Truncate, and Synchronize are not thread-safe. Moreover, locking doesn't assure atomicity of reading and writing operations.

Constructor & Destructor Documentation

◆ PositionalParallelFile() [1/2]

tkrzw::PositionalParallelFile::PositionalParallelFile ( )

Default constructor.

◆ ~PositionalParallelFile()

tkrzw::PositionalParallelFile::~PositionalParallelFile ( )

Destructor.

◆ PositionalParallelFile() [2/2]

tkrzw::PositionalParallelFile::PositionalParallelFile ( const PositionalParallelFile & rhs )

explicitdelete

Copy and assignment are disabled.

Member Function Documentation

◆ Open()

Status tkrzw::PositionalParallelFile::Open	(	const std::string &	path,
		bool	writable,
		int32_t	options = `OPEN_DEFAULT`
	)

overridevirtual

Opens a file.

Parameters

path	A path of the file.
writable	If true, the file is writable. If false, it is read-only.
options	Bit-sum options of File::OpenOption enums.

Returns: The result status.

By default, exclusive locking against other processes is done for a writer and shared locking against other processes is done for a reader.

Implements tkrzw::File.

◆ Close()

Status tkrzw::PositionalParallelFile::Close ( )

overridevirtual

Closes the file.

Returns: The result status.

Implements tkrzw::File.

◆ Read()

Status tkrzw::PositionalParallelFile::Read	(	int64_t	off,
		void *	buf,
		size_t	size
	)

overridevirtual

Reads data.

Parameters

off	The offset of a source region.
buf	The pointer to the destination buffer.
size	The size of the data to be read.

Returns: The result status.

Implements tkrzw::File.

◆ Write()

Status tkrzw::PositionalParallelFile::Write	(	int64_t	off,
		const void *	buf,
		size_t	size
	)

overridevirtual

Writes data.

Parameters

off	The offset of the destination region.
buf	The pointer to the source buffer.
size	The size of the data to be written.

Returns: The result status.

Implements tkrzw::File.

◆ Append()

Status tkrzw::PositionalParallelFile::Append	(	const void *	buf,
		size_t	size,
		int64_t *	off = `nullptr`
	)

overridevirtual

Appends data at the end of the file.

Parameters

buf	The pointer to the source buffer.
size	The size of the data to be written.
off	The pointer to an integer object to contain the offset at which the data has been put. If it is nullptr, it is ignored.

Returns: The result status.

Implements tkrzw::File.

◆ Expand()

Status tkrzw::PositionalParallelFile::Expand	(	size_t	inc_size,
		int64_t *	old_size = `nullptr`
	)

overridevirtual

Expands the file size without writing data.

Parameters

inc_size	The size to increment the file size by.
old_size	The pointer to an integer object to contain the old size of the file. If it is nullptr, it is ignored.

Returns: The result status.

Implements tkrzw::File.

◆ Truncate()

Status tkrzw::PositionalParallelFile::Truncate ( int64_t size )

overridevirtual

Truncates the file.

Parameters

size	The new size of the file.

Returns: The result status.

Implements tkrzw::File.

◆ TruncateFakely()

Status tkrzw::PositionalParallelFile::TruncateFakely ( int64_t size )

overridevirtual

Truncate the file fakely.

Parameters

size	The new size of the file.

Returns: The result status.

This doesn't modify the actual file but modifies the internal length parameter, which affects behavior of Close, Synchronize, Append, Expand, and GetSize. If the specified size is more than the actual file size, the operation fails.

Implements tkrzw::File.

◆ Synchronize()

Status tkrzw::PositionalParallelFile::Synchronize	(	bool	hard,
		int64_t	off = `0`,
		int64_t	size = `0`
	)

overridevirtual

Synchronizes the content of the file to the file system.

Parameters

hard	True to do physical synchronization with the hardware or false to do only logical synchronization with the file system.
off	The offset of the region to be synchronized.
size	The size of the region to be synchronized. If it is zero, the length to the end of file is specified.

Returns: The result status.

The pysical file size can be larger than the logical size in order to improve performance by reducing frequency of allocation. Thus, you should call this function before accessing the file with external tools.

Implements tkrzw::File.

◆ GetSize()

Status tkrzw::PositionalParallelFile::GetSize ( int64_t * size )

overridevirtual

Gets the size of the file.

Parameters

size	The pointer to an integer object to contain the result size.

Returns: The result status.

Implements tkrzw::File.

◆ SetHeadBuffer()

Status tkrzw::PositionalParallelFile::SetHeadBuffer ( int64_t size )

overridevirtual

Sets the head buffer to cache the beginning region of the file.

Parameters

size	The size of the head buffer. If it is not positive, it is not used.

Returns: The result status.

This method must be called after the file is opened.

Implements tkrzw::PositionalFile.

◆ SetAccessStrategy()

Status tkrzw::PositionalParallelFile::SetAccessStrategy	(	int64_t	block_size,
		int32_t	options
	)

overridevirtual

Sets access strategy.

Parameters

block_size	The block size to which all records should be aligned. It must be a multiple of the block size of the underlying file system or device.
options	Bit-sum options of PositionalFile::AccessOption enums;

Returns: The result status.

Implements tkrzw::PositionalFile.

◆ SetAllocationStrategy()

Status tkrzw::PositionalParallelFile::SetAllocationStrategy	(	int64_t	init_size,
		double	inc_factor
	)

overridevirtual

Sets allocation strategy.

Parameters

init_size	An initial size of allocation.
inc_factor	A factor to increase the size of allocation.

Returns: The result status.

By default, the initial size is 1MB and the increasing factor is 2. To fit the file size to the actual data, set the increasing factor zero. This method must be called before the file is opened.

Implements tkrzw::File.

◆ CopyProperties()

Status tkrzw::PositionalParallelFile::CopyProperties ( File * file )

overridevirtual

Copies internal properties to another file object.

Parameters

file	The other file object.

Returns: The result status.

Implements tkrzw::File.

◆ GetPath()

Status tkrzw::PositionalParallelFile::GetPath ( std::string * path )

overridevirtual

Gets the path of the file.

Parameters

path	The pointer to a string object to store the path.

Returns: The result status.

Implements tkrzw::File.

◆ Rename()

Status tkrzw::PositionalParallelFile::Rename ( const std::string & new_path )

overridevirtual

Renames the file.

Parameters

new_path A new path of the file.

Returns: The result status.

Implements tkrzw::File.

◆ DisablePathOperations()

Status tkrzw::PositionalParallelFile::DisablePathOperations ( )

overridevirtual

Disables operations related to the path.

Returns: The result status.

This should be called if the file is overwritten by external operations.

Implements tkrzw::File.

◆ IsOpen()

bool tkrzw::PositionalParallelFile::IsOpen ( ) const

overridevirtual

Checks whether the file is open.

Returns: True if the file is open, or false if not.

Implements tkrzw::File.

◆ IsMemoryMapping()

bool tkrzw::PositionalParallelFile::IsMemoryMapping ( ) const

overridevirtual

Checks whether operations are done by memory mapping.

Returns: Always false. This is slow, but the file size can exceed the virtual memory.

Implements tkrzw::File.

◆ IsAtomic()

bool tkrzw::PositionalParallelFile::IsAtomic ( ) const

overridevirtual

Checks whether updating operations are atomic and thread-safe.

Returns: Always false. Atomicity is not assured. Some operations are not thread-safe.

Implements tkrzw::File.

◆ GetBlockSize()

int64_t tkrzw::PositionalParallelFile::GetBlockSize ( ) const

overridevirtual

Gets the block size.

Returns: The block size.

Implements tkrzw::PositionalFile.

◆ IsDirectIO()

bool tkrzw::PositionalParallelFile::IsDirectIO ( ) const

overridevirtual

Checks whether the access mode is direct I/O.

Returns: True if the access mode is direct I/O, or false if not.

Implements tkrzw::PositionalFile.

◆ MakeFile()

std::unique_ptr<File> tkrzw::PositionalParallelFile::MakeFile ( ) const

overridevirtual

Makes a new file object of the same concrete class.

Returns: The new file object.

Implements tkrzw::File.

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ PositionalParallelFile() [1/2]

◆ ~PositionalParallelFile()

◆ PositionalParallelFile() [2/2]

Member Function Documentation

◆ Open()

◆ Close()

◆ Read()

◆ Write()

◆ Append()

◆ Expand()

◆ Truncate()

◆ TruncateFakely()

◆ Synchronize()

◆ GetSize()

◆ SetHeadBuffer()

◆ SetAccessStrategy()

◆ SetAllocationStrategy()

◆ CopyProperties()

◆ GetPath()

◆ Rename()

◆ DisablePathOperations()

◆ IsOpen()

◆ IsMemoryMapping()

◆ IsAtomic()

◆ GetBlockSize()

◆ IsDirectIO()

◆ MakeFile()