The WriteFileHandler interface adds write operations to the FileHandler interface. More...

#include <WriteFileHandler.h>

Inheritance diagram for vrs::WriteFileHandler:

Public Member Functions
virtual int	create (const FileSpec &spec)

virtual int	create (const string &newFilePath, const map< string, string > &options={})=0

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

virtual void	addSplitHead (MAYBE_UNUSED FileSpec &inOutSpec)

virtual bool	reopenForUpdatesSupported () const =0

virtual int	reopenForUpdates ()=0

bool	isReadOnly () const override=0

virtual int	write (const void *buffer, size_t length)=0

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.

virtual int	overwrite (const void *buffer, size_t length)=0

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.

virtual int	addChunk ()=0

virtual int	truncate ()=0

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

Public Member Functions inherited from vrs::FileHandler
virtual unique_ptr< FileHandler >	makeNew () const =0

virtual const string &	getFileHandlerName () const =0

virtual const string &	getWriteFileHandlerName () const

virtual int	open (const string &filePath)

virtual int	openSpec (const FileSpec &fileSpec)=0

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

virtual bool	isOpened () const =0

virtual int64_t	getTotalSize () const =0

virtual int	close ()=0

virtual int	skipForward (int64_t offset)=0

virtual int	setPos (int64_t offset)=0

virtual bool	isAvailableOrPrefetch (MAYBE_UNUSED size_t length)

virtual int	read (void *buffer, size_t length)=0

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 size_t	getLastRWSize () const =0

virtual vector< std::pair< string, int64_t > >	getFileChunks () const =0

virtual void	forgetFurtherChunks (int64_t maxSize)=0
	Call this method to forget any chunk beyond this file size.

virtual int	getLastError () const =0

virtual bool	isEof () const =0

virtual int64_t	getPos () const =0

virtual int64_t	getChunkPos () const =0

virtual int	getChunkRange (int64_t &outChunkOffset, int64_t &outChunkSize) const =0

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	isRemoteFileSystem () const =0

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

Static Public Member Functions
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)

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

Detailed Description

The WriteFileHandler interface adds write operations to the FileHandler interface.

There are two classes of WriteFileHandler implementations:

the ones that can edit data already written, whether editing a previously created file, or while creating a new one, as typically possible with local files,
the immutable kind, which don't allow for overwriting parts of the file already written. They can append content, maybe concatenate chunks, but not modify previously written content. That's a typical restriction for cloud storage systems.

VRS' DiskFile offers the most comprehensive implementation, because it is designed to fit all the needs of advanced VRS file creations, with chunking, but it can be used with non-VRS files.

On the other hand, network WriteFileHandler implementations often have very specific behaviors designed to accommodate the specificities of the network storage they implement. These implementation details should ideally be abstracted, but in order to optimize cloud VRS file creation, the abstraction is compromised, and cloud WriteFileHandler implementations are not easily reusable for other applications that VRS.

Member Function Documentation

◆ addChunk()

virtual int vrs::WriteFileHandler::addChunk ( )

pure virtual

Append a new chunk to the current file, when in writing to disk. The next write will happen at the beginning of the new chunk.

Returns: A status code, 0 meaning success.

Implemented in vrs::DiskFileT< FileChunk >.

◆ addSplitHead()

virtual void vrs::WriteFileHandler::addSplitHead ( MAYBE_UNUSED FileSpec & inOutSpec )

inlinevirtual

When creating a split-head file, we may need to add a new chunk for the head file.

Parameters

inOutSpec file spec used for the file creation, that will be passed to a DiskFile's create(inOutSpec) to create the head file, and to createSplitFile(inOutSpec, options) to create the body file.

◆ create() [1/2]

virtual int vrs::WriteFileHandler::create ( const FileSpec & spec )

inlinevirtual

Create a new file for writing, using a spec. The path of the file to create is expected to be in the first chunk. Optional URI parameters might be provided in the spec' extras.

◆ create() [2/2]

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

pure virtual

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.

Implemented in vrs::DiskFileT< FileChunk >, and vrs::AtomicDiskFile.

◆ createSplitFile()

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

inlinevirtual

Create a new file for writing, in split-head file mode, the body part.

Parameters

spec	spec as converted already from initialFilePath, if that helps.
initialFilePath	path as given when the file creation was started.

Returns: A status code, 0 meaning success.

◆ getCurrentChunk()

virtual bool vrs::WriteFileHandler::getCurrentChunk	(	string &	outChunkPath,
		size_t &	outChunkIndex
	)		const

pure virtual

Get the path of the current chunk, or an empty string if no chunk is open.

Implemented in vrs::DiskFileT< FileChunk >.

◆ isReadOnly()

bool vrs::WriteFileHandler::isReadOnly ( ) const

overridepure virtual

Find out if the file is currently open in read-only mode.

Returns: True if the file is currently open in read-only mode. Undefined if no file is open.

Reimplemented from vrs::FileHandler.

Implemented in vrs::DiskFileT< FileChunk >.

◆ overwrite()

virtual int vrs::WriteFileHandler::overwrite	(	const void *	buffer,
		size_t	length
	)

pure virtual

Write a number of bytes to the file, in a chunk aware way, only ever extending the file's last chunk.

Parameters

buffer	a pointer to the data bytes to write.
length	the number of bytes to write.

Returns: A status code, 0 meaning success.

Implemented in vrs::DiskFileT< FileChunk >.

◆ reopenForUpdates()

virtual int vrs::WriteFileHandler::reopenForUpdates ( )

pure virtual

Switch from read-only to read-write mode. Reopen the same file for modification writes.

Returns: A status code, 0 meaning success.

Implemented in vrs::DiskFileT< FileChunk >.

◆ reopenForUpdatesSupported()

virtual bool vrs::WriteFileHandler::reopenForUpdatesSupported ( ) const

pure virtual

Tell if modifying files is supported by this FileHandler implementation.

Returns: True if file modification and creation is supported.

Implemented in vrs::DiskFileT< FileChunk >.

◆ truncate()

virtual int vrs::WriteFileHandler::truncate ( )

pure virtual

Truncate chunk to the current file position. Use with care.

Returns: A status code, 0 meaning success.

Implemented in vrs::DiskFileT< FileChunk >.

◆ write()

virtual int vrs::WriteFileHandler::write	(	const void *	buffer,
		size_t	length
	)

pure virtual

Write to the current chunk, possibly expanding it.

Parameters

buffer	a pointer to the data bytes to write.
length	the number of bytes to write.

Returns: A status code, 0 meaning success. In case of error, you can use getLastRWSize() to know how many bytes were really written.

Implemented in vrs::DiskFileT< FileChunk >.

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

vrs/WriteFileHandler.h
vrs/FileHandlerFactory.cpp

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ addChunk()

◆ addSplitHead()

◆ create() [1/2]

◆ create() [2/2]

◆ createSplitFile()

◆ getCurrentChunk()

◆ isReadOnly()

◆ overwrite()

◆ reopenForUpdates()

◆ reopenForUpdatesSupported()

◆ truncate()

◆ write()