Tkrzw
Public Member Functions | List of all members
tkrzw::PositionalParallelFile Class Referencefinal

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...
 
PositionalParallelFileoperator= (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< FileMakeFile () 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
pathA path of the file.
writableIf true, the file is writable. If false, it is read-only.
optionsBit-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
offThe offset of a source region.
bufThe pointer to the destination buffer.
sizeThe 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
offThe offset of the destination region.
bufThe pointer to the source buffer.
sizeThe 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
bufThe pointer to the source buffer.
sizeThe size of the data to be written.
offThe 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_sizeThe size to increment the file size by.
old_sizeThe 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
sizeThe 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
sizeThe 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
hardTrue to do physical synchronization with the hardware or false to do only logical synchronization with the file system.
offThe offset of the region to be synchronized.
sizeThe 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
sizeThe 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
sizeThe 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_sizeThe 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.
optionsBit-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_sizeAn initial size of allocation.
inc_factorA 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
fileThe 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
pathThe 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_pathA 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.