#include <DiskFile.h>

Inheritance diagram for vrs::AtomicDiskFile:

Public Member Functions
int	create (const string &newFilePath, const map< string, string > &options={}) override

int	close () override

void	abort ()

Public Member Functions inherited from vrs::DiskFileT< FileChunk >
std::unique_ptr< FileHandler >	makeNew () const override
	Make a new DiskFile object, with a default state.

const string &	getFileHandlerName () const override

int	openSpec (const FileSpec &fileSpec) override
	Open a file in read-only mode.

bool	isOpened () const override
	Tell if a file is actually open.

int	create (const string &newFilePath, const map< string, string > &options={}) override
	Create a new file.

void	forgetFurtherChunks (int64_t fileSize) override
	Call this method to forget any chunk beyond this file size.

int64_t	getTotalSize () const override
	Get the total size of all the chunks considered.

vector< std::pair< string, int64_t > >	getFileChunks () const override
	Get the list of chunks, path + size.

int	close () override
	Close the file.

int	skipForward (int64_t offset) override
	Skip a number of bytes further in the file, in a chunk aware way.

int	setPos (int64_t offset) override
	Set the file position at an arbitrary position, in a chunk aware way.

int	read (void *buffer, size_t length) override
	Read a number of bytes, in a chunk aware way.

template<typename T , std::enable_if_t< std::is_trivially_copyable< T >::value, int > = 0>
int	read (T &object)
	Helper to read trivially copyable objects, in a chunk aware way.

size_t	getLastRWSize () const override
	Get the number of bytes actually moved by the last read or write operation.

bool	reopenForUpdatesSupported () const override
	Tell if modifying files is supported by this FileHandler implementation.

int	reopenForUpdates () override
	Switch from read-only to read-write mode.

bool	isReadOnly () const override
	Find out if the file is in read-only mode.

int	write (const void *buffer, size_t length) override
	Write to the current chunk, possibly expanding it.

template<typename T , std::enable_if_t< std::is_trivially_copyable< T >::value, int > = 0>
int	write (const T &object)
	Helper for trivially copyable objects.

int	overwrite (const void *buffer, size_t length) override

template<typename T , std::enable_if_t< std::is_trivially_copyable< T >::value, int > = 0>
int	overwrite (const T &object)
	Helper for trivially copyable objects.

int	addChunk () override
	Append a new chunk to the current file.

int	truncate () override
	Truncate chunk to the current file position. Use with care.

int	getLastError () const override
	Get the last error code. 0 means no error.

bool	isEof () const override
	Tell if we are at the end of the last chunk.

int64_t	getPos () const override
	Get the absolute position in the file, in a chunk aware way.

int64_t	getChunkPos () const override
	Get position in the current chunk.

int	getChunkRange (int64_t &outChunkOffset, int64_t &outChunkSize) const override
	Get range of the current chunk.

bool	getCurrentChunk (string &outChunkPath, size_t &outChunkIndex) const override
	Get the path of the current chunk, or an empty string if no chunk is open.

bool	isRemoteFileSystem () const override

template<typename T , std::enable_if_t< std::is_trivially_copyable< T >::value, int > = 0>
int	writeZstdFile (const string &path, const T &object)

template<typename T , std::enable_if_t< std::is_trivially_copyable< T >::value, int > = 0>
int	writeZstdFile (const string &path, const vector< T > &v)

template<typename T , std::enable_if_t< std::is_trivially_copyable< T >::value, int > = 0>
int	readZstdFile (const string &path, T &object)

int	parseUri (FileSpec &inOutFileSpec, size_t colonIndex) const override

const string &	staticName ()

Public Member Functions inherited from vrs::WriteFileHandler
virtual int	create (const FileSpec &spec)

virtual int	createSplitFile (const FileSpec &spec, const string &initialFilePath)

virtual void	addSplitHead (MAYBE_UNUSED FileSpec &inOutSpec)

template<typename T , std::enable_if_t< std::is_trivially_copyable< T >::value, int > = 0>
int	write (const T &object)
	Helper for trivially copyable objects.

template<typename T , std::enable_if_t< std::is_trivially_copyable< T >::value, int > = 0>
int	overwrite (const T &object)
	Helper for trivially copyable objects.

Public Member Functions inherited from vrs::FileHandler
virtual const string &	getWriteFileHandlerName () const

virtual int	open (const string &filePath)

int	delegateOpen (const FileSpec &fileSpec, unique_ptr< FileHandler > &outNewDelegate) override

virtual bool	isAvailableOrPrefetch (MAYBE_UNUSED size_t length)

template<typename T , std::enable_if_t< std::is_trivially_copyable< T >::value, int > = 0>
int	read (T &object)
	Helper to read trivially copyable objects, in a chunk aware way.

virtual bool	setCachingStrategy (CachingStrategy)

virtual CachingStrategy	getCachingStrategy () const

virtual bool	prefetchReadSequence (MAYBE_UNUSED const vector< std::pair< size_t, size_t > > &sequence, MAYBE_UNUSED bool clearSequence=true)

virtual bool	setStatsCallback (const CacheStatsCallbackFunction &)

virtual bool	purgeCache ()

bool	isFileHandlerMatch (const FileSpec &fileSpec) const

virtual bool	showProgress () const
	Tell if the file handler is probably slow, and extra progress information might be useful.

Public Member Functions inherited from vrs::FileDelegator
virtual int	parseUri (FileSpec &inOutFileSpec, MAYBE_UNUSED size_t colonIndex) const

Additional Inherited Members
Public Types inherited from vrs::FileHandler
using	CacheStatsCallbackFunction = std::function< void(const CacheStats &stats)>

Static Public Member Functions inherited from vrs::DiskFileT< FileChunk >
static const std::string &	staticName ()

static int	writeZstdFile (const string &path, const void *data, size_t dataSize)

static int	writeZstdFile (const string &path, const string &string)

static int	readZstdFile (const string &path, vector< char > &outContent)
	Read a compressed buffer or a string (automatically adjusts the size)

static int	readZstdFile (const string &path, string &outString)

static int	readZstdFile (const string &path, void *data, size_t dataSize)
	Read a compressed buffer of an exact size, fails if the size isn't perfectly right.

static string	readTextFile (const string &path)

static int	writeTextFile (const string &path, const string &text)

Static Public Member Functions inherited from vrs::WriteFileHandler
static unique_ptr< WriteFileHandler >	make (const string &fileHandlerName)
	Create a new WriteFileHandler from a name.

Static Public Member Functions inherited from vrs::FileHandler
static unique_ptr< FileHandler >	makeOpen (const string &filePath)
	Open a file in read-only mode. Returns an open file handler, or nullptr on error.

static unique_ptr< FileHandler >	makeOpen (const FileSpec &fileSpec)

Protected Member Functions inherited from vrs::DiskFileT< FileChunk >
int	checkChunks (const vector< string > &chunks)

int	openChunk (FileChunk *chunk)

int	closeChunk (FileChunk *chunk)

int	addChunk (const string &chunkFilePath)

bool	isLastChunk () const

bool	trySetPosInCurrentChunk (int64_t offset)

Protected Attributes inherited from vrs::DiskFileT< FileChunk >
map< string, string >	options_

std::unique_ptr< vector< FileChunk > >	chunks_

FileChunk *	currentChunk_ {}

int	filesOpenCount_ {}

size_t	lastRWSize_ {}

int	lastError_ {}

bool	readOnly_ {true}

Detailed Description

Helper class to create a new file with better chances that the content won't be clobbered by another process creating a file with the same name at the same time. The file will be created using a unique name, then after it's closed, it will be renamed to the name requested originally, possibly deleting/replacing what is there. In practice, it's a best effort atomic file behavior, using a temporary file and late renaming, appropriate when file integrity matters more than file persistence in case of collision. The intent:

if multiple processes try to create a file with the same name at the same time, they don't overwrite each other's data.
if a process tries to read the file at about the same time it is being replaced by one or more other processes, it won't find a file, or it will find an older version of the file, or it will find a new version, but it won't find a partially written version of the file. The actual behavior will depend on the actual file system, how atomic its file rename operations are, and how it handles file locking, but the behavior should be appropriate for storing data for caching purposes, when its better to fail saving a cache entry, than creating a corrupt one.

Member Function Documentation

◆ close()

int vrs::AtomicDiskFile::close ( )

overridevirtual

Close the file & free all the held resources, even if an error occurs.

Returns: A status code for first error while closing, or 0, meaning success.

Implements vrs::FileHandler.

◆ create()

int vrs::AtomicDiskFile::create	(	const string &	newFilePath,
		const map< string, string > &	options = `{}`
	)

overridevirtual

Create a new file for writing.

Parameters

newFilePath	a disk path to create the file.
options	optional parameters to pass when creating the file.

Returns: A status code, 0 meaning success.

Implements vrs::WriteFileHandler.

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

vrs/DiskFile.h
vrs/DiskFile.cpp

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ close()

◆ create()