vitrio::file_image_writer_provider Class Reference

A provider that writes files. Its files are explicitly declared and closed by the client. More...

#include <vitrio/file_image_writer_provider.hpp>

Inheritance diagram for vitrio::file_image_writer_provider:

Collaboration diagram for vitrio::file_image_writer_provider:

Public Member Functions
	file_image_writer_provider (std::shared_ptr< const image_file_write_format_selector > formats)
	Construct a provider creating files through a format selector.
void	declare (std::string key, image_descriptor descriptor, const image_metadata &metadata)
	Make a file writable.
void	close (const std::string &key)
	Finish a file.
void	flush ()
	Make everything written to the files reach the storage.
std::size_t	get_file_count () const noexcept
	Get how many files are declared.
std::shared_ptr< image_writer >	acquire (const std::string &key) override
	Get the writer a key names.
Public Member Functions inherited from vitrio::image_writer_provider
	image_writer_provider (const image_writer_provider &other)=delete
	image_writer_provider (image_writer_provider &&other)=delete
image_writer_provider &	operator= (const image_writer_provider &other)=delete
image_writer_provider &	operator= (image_writer_provider &&other)=delete

Detailed Description

A provider that writes files. Its files are explicitly declared and closed by the client.

Creating a file replaces whatever was there, so a writer dropped and reopened would truncate everything already written to it, and no eviction policy can decide when that is safe. Which files exist and when each is finished is instead said outright, through declare and close.

Each file therefore has one lifecycle, declare, acquire as often as needed, close:

• A declared file is created, through the format selector, the first time it is acquired, so declaring many files costs no file descriptor until each is reached. Every later acquire returns that same writer until the file is closed, and a key never declared is refused with std::out_of_range.
• close flushes and drops the writer, which is what gives its file descriptor back.
• flush flushes every writer created so far, and creates none: a declared file never acquired stays uncreated.

Thread safety

Every method may be called concurrently. The lock is held while a file is created, since two concurrent calls creating one file would otherwise each replace it, and only long enough to look it up when it is already open.

See also

file_image_reader_provider

image_file_write_format_selector

Constructor & Destructor Documentation

file_image_writer_provider()

vitrio::file_image_writer_provider::file_image_writer_provider ( std::shared_ptr< const image_file_write_format_selector >  formats )

explicit

Construct a provider creating files through a format selector.

Parameters

formats

The formats a file may be created with.

Exceptions

std::invalid_argument

If formats is null.

Member Function Documentation

acquire()

std::shared_ptr< image_writer > vitrio::file_image_writer_provider::acquire ( const std::string &  key )

overridevirtual

Get the writer a key names.

Shared ownership rather than a reference, so that a writer the provider stops keeping stays alive for as long as it is still written through.

Parameters

key	Key of the file to write, such as its path.

Returns

std::shared_ptr<image_writer> The writer, never null.

Exceptions

std::out_of_range	If this provider serves no such file.
unsupported_operation_error	If no format can create the file, or the chosen one can not represent it.
image_file_error	If the file could not be created.

Implements vitrio::image_writer_provider.

close()

void vitrio::file_image_writer_provider::close

(

const std::string &

key

)

Finish a file.

Flushes the writer if the file was ever acquired, drops it, and forgets the declaration. Acquiring that key afterwards throws as an undeclared one does, and declaring it again creates the file afresh.

Closing a file that was declared but never acquired creates nothing and simply forgets it.

Parameters

key	Key of the file to finish.

Exceptions

std::out_of_range	If that key is not declared.
image_file_error	If the pending writes could not be completed.

declare()

void vitrio::file_image_writer_provider::declare	(	std::string	key,
		image_descriptor	descriptor,
		const image_metadata &	metadata
	)

Make a file writable.

Records the descriptor and metadata the file will be created with. Nothing is created until the file is first acquired, so this costs no file descriptor and can not fail on anything the file system has to say.

A key that is still declared is refused rather than replaced, because replacing it would silently strand whatever had been written to the file it names. close it first, which says so.

Parameters

key	Key of the file to create, which is handed to the format selector as its path.
descriptor	What the file holds.
metadata	How its samples map onto physical space.

Exceptions

std::logic_error

If that key is already declared.

flush()

void vitrio::file_image_writer_provider::flush

(

)

Make everything written to the files reach the storage.

Flushes the writer of every file acquired so far and creates none: a file declared and never acquired stays uncreated. Every file stays declared and writable.

Exceptions

image_file_error

If the pending writes could not be completed.

get_file_count()

std::size_t vitrio::file_image_writer_provider::get_file_count ( ) const

noexcept

Get how many files are declared.

Counts what has been declared and not yet closed, whether or not it has been acquired.

Returns

std::size_t The number of files.

---

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

• vitrio/file_image_writer_provider.hpp