Interface of file operations. More...

#include <tkrzw_file.h>

Public Types
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 }
	Enumeration of options for Open. More...

Public Member Functions
virtual	~File ()=default
	Destructor. More...

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

virtual Status	Close ()=0
	Closes the file. More...

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

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

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

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

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

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

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

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

virtual Status	Truncate (int64_t size)=0
	Truncates the file. More...

virtual Status	TruncateFakely (int64_t size)=0
	Truncate the file fakely. More...

virtual Status	Synchronize (bool hard)=0
	Synchronizes the content of the file to the file system. More...

virtual Status	GetSize (int64_t *size)=0
	Gets the size of the file. More...

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

virtual Status	SetAllocationStrategy (int64_t init_size, double inc_factor)=0
	Sets allocation strategy. More...

virtual Status	CopyProperties (File *file)=0
	Copies internal properties to another file object. More...

virtual Status	GetPath (std::string *path)=0
	Gets the path of the file. More...

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

virtual Status	Rename (const std::string &new_path)=0
	Renames the file. More...

virtual Status	DisablePathOperations ()=0
	Disables operations related to the path. More...

virtual bool	IsMemoryMapping () const =0
	Checks whether operations are done by memory mapping. More...

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

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

Static Public Attributes
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

Interface of file operations.

Member Enumeration Documentation

◆ OpenOption

enum tkrzw::File::OpenOption : int32_t

Enumeration of options for Open.

Enumerator
OPEN_DEFAULT	The default behavior.
OPEN_TRUNCATE	To truncate the file.
OPEN_NO_CREATE	To omit file creation.
OPEN_NO_WAIT	To fail if the file is locked by another process.
OPEN_NO_LOCK	To omit file locking.

Constructor & Destructor Documentation

◆ ~File()

virtual tkrzw::File::~File ( )

virtualdefault

Destructor.

Member Function Documentation

◆ Open()

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

pure virtual

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.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ Close()

virtual Status tkrzw::File::Close ( )

pure virtual

Closes the file.

Returns: The result status.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ Read()

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

pure virtual

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.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ ReadSimple()

virtual std::string tkrzw::File::ReadSimple	(	int64_t	off,
		size_t	size
	)

virtual

Reads data, in a simple way.

Parameters

off	The offset of a source region.
size	The size of the data to be read.

Returns: A string of the read data. It is empty on failure.

Reimplemented in tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ Write()

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

pure virtual

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.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ WriteSimple()

virtual bool tkrzw::File::WriteSimple	(	int64_t	off,
		std::string_view	data
	)

virtual

Writes data, in a simple way.

Parameters

off	The offset of the destination region.
data	The data to be written.

Returns: True on success or false on failure.

◆ Append()

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

pure virtual

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.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ AppendSimple()

virtual int64_t tkrzw::File::AppendSimple ( const std::string & data )

virtual

Appends data at the end of the file, in a simple way.

Parameters

data	The data to be written.

Returns: The offset at which the data has been put, or -1 on failure.

◆ Expand()

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

pure virtual

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. put. If it is nullptr, it is ignored.

Returns: The result status.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ ExpandSimple()

virtual int64_t tkrzw::File::ExpandSimple ( size_t inc_size )

virtual

Expands the file size without writing data, in a simple way.

Parameters

inc_size The size to increment the file size by.

Returns: The old size of the file, or -1 on failure.

◆ Truncate()

virtual Status tkrzw::File::Truncate ( int64_t size )

pure virtual

Truncates the file.

Parameters

size	The new size of the file.

Returns: The result status. If the file is shrunk, data after the new file end is discarded. If the file is expanded, null codes are filled after the old file end.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ TruncateFakely()

virtual Status tkrzw::File::TruncateFakely ( int64_t size )

pure virtual

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.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ Synchronize()

virtual Status tkrzw::File::Synchronize ( bool hard )

pure virtual

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.

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.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ GetSize()

virtual Status tkrzw::File::GetSize ( int64_t * size )

pure virtual

Gets the size of the file.

Parameters

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

Returns: The result status.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ GetSizeSimple()

virtual int64_t tkrzw::File::GetSizeSimple ( )

virtual

Gets the size of the file, in a simple way.

Returns: The size of the on success, or -1 on failure.

◆ SetAllocationStrategy()

virtual Status tkrzw::File::SetAllocationStrategy	(	int64_t	init_size,
		double	inc_factor
	)

pure virtual

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. This method must be called before the file is opened.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ CopyProperties()

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

pure virtual

Copies internal properties to another file object.

Parameters

file	The other file object.

Returns: The result status.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ GetPath()

virtual Status tkrzw::File::GetPath ( std::string * path )

pure virtual

Gets the path of the file.

Parameters

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

Returns: The result status.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ GetPathSimple()

virtual std::string tkrzw::File::GetPathSimple ( )

virtual

Gets the path of the file, in a simple way.

Returns: The path of the file on success, or an empty string on failure.

◆ Rename()

virtual Status tkrzw::File::Rename ( const std::string & new_path )

pure virtual

Renames the file.

Parameters

new_path A new path of the file.

Returns: The result status.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ DisablePathOperations()

virtual Status tkrzw::File::DisablePathOperations ( )

pure virtual

Disables operations related to the path.

Returns: The result status. This should be called if the file is overwritten by external operations.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ IsMemoryMapping()

virtual bool tkrzw::File::IsMemoryMapping ( ) const

pure virtual

Checks whether operations are done by memory mapping.

Returns: True if operations are done by memory mapping, or false if not.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ IsAtomic()

virtual bool tkrzw::File::IsAtomic ( ) const

pure virtual

Checks whether updating operations are atomic and thread-safe.

Returns: True if every updating operation is atomic and thread-safe, or false any of them are not.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

◆ MakeFile()

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

pure virtual

Makes a new file object of the same concrete class.

Returns: The new file object.

Implemented in tkrzw::StdFile, tkrzw::PositionalAtomicFile, tkrzw::PositionalParallelFile, tkrzw::MemoryMapAtomicFile, and tkrzw::MemoryMapParallelFile.

Member Data Documentation

◆ DEFAULT_ALLOC_INIT_SIZE

constexpr int64_t tkrzw::File::DEFAULT_ALLOC_INIT_SIZE = 1LL << 20

staticconstexpr

The default value of the initial allocation size.

◆ DEFAULT_ALLOC_INC_FACTOR

constexpr double tkrzw::File::DEFAULT_ALLOC_INC_FACTOR = 2.0

staticconstexpr

The default value of the allocation increment factor.

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ OpenOption

Constructor & Destructor Documentation

◆ ~File()

Member Function Documentation

◆ Open()

◆ Close()

◆ Read()

◆ ReadSimple()

◆ Write()

◆ WriteSimple()

◆ Append()

◆ AppendSimple()

◆ Expand()

◆ ExpandSimple()

◆ Truncate()

◆ TruncateFakely()

◆ Synchronize()

◆ GetSize()

◆ GetSizeSimple()

◆ SetAllocationStrategy()

◆ CopyProperties()

◆ GetPath()

◆ GetPathSimple()

◆ Rename()

◆ DisablePathOperations()

◆ IsMemoryMapping()

◆ IsAtomic()

◆ MakeFile()

Member Data Documentation

◆ DEFAULT_ALLOC_INIT_SIZE

◆ DEFAULT_ALLOC_INC_FACTOR