vitrio::indexed_image_scratch Class Reference

A scratch that holds the images that image_location-s can name, each in a slot of its storage. More...

#include <vitrio/indexed_image_scratch.hpp>

Inheritance diagram for vitrio::indexed_image_scratch:

Collaboration diagram for vitrio::indexed_image_scratch:

Public Member Functions
	indexed_image_scratch (const image_location_grouping &locations, image_reader_provider &files, std::shared_ptr< image_scratch_storage > storage, std::size_t run_length, image_scratch_open_mode mode=image_scratch_open_mode::empty)
	Construct a scratch for a grouping of locations.
std::shared_ptr< image_scratch_entry >	find (const std::string &key) override
	Get what is held of a file, to read it and to add to it.
Public Member Functions inherited from vitrio::image_scratch
	image_scratch (const image_scratch &other)=delete
	image_scratch (image_scratch &&other)=delete
image_scratch &	operator= (const image_scratch &other)=delete
image_scratch &	operator= (image_scratch &&other)=delete

Detailed Description

A scratch that holds the images that image_location-s can name, each in a slot of its storage.

What it holds of a file are indices of the first axis of the file, which is what an image_location names: for example the images of a stack. Each held index has a slot in the storage.

It holds the images that a grouping of locations names, as far as they fit in the storage. Each file gets one entry, and the entries are stored one after another. The storage decides where the copies live: in main memory, or in a file mapped into it.

Which images are held is fixed at construction. Entries are loaded from their files when regions are stored into them.

Loading works in runs. A run is a block of consecutive held images of one file. Every run of a file has the same number of images, except the last one, which may have fewer. Storing any image loads its whole run in one read of the file.

The storage also records what is loaded, so that a scratch constructed later over the same storage can continue from it. The storage starts with a fingerprint of how the scratch is laid out: the keys and the held indices, the run length, and the data type and extents of each file. Each run has a flag, which holds the modification time that its file had when the run was loaded. The time is asked of the file system, with the key as the path of the file. A file whose time can not be told is loaded again by every scratch.

Constructor & Destructor Documentation

indexed_image_scratch()

vitrio::indexed_image_scratch::indexed_image_scratch	(	const image_location_grouping &	locations,
		image_reader_provider &	files,
		std::shared_ptr< image_scratch_storage >	storage,
		std::size_t	run_length,
		image_scratch_open_mode	mode = image_scratch_open_mode::empty
	)

Construct a scratch for a grouping of locations.

A location with a stack index names that index of the first axis of its file. A location without one names the whole file.

Files are taken in the order of the grouping, which is ascending order of key. Each is opened once, to learn its shape and data type. If the storage runs out of room, the current file keeps the lowest indices that fit and the remaining files are not opened.

Parameters

locations	The images to hold, grouped by file.
files	Provider used to open the files.
storage	Where the copies are stored. Its size is the capacity of the scratch. It must be aligned for 64-bit integers and for the data types of the files.
run_length	Number of held indices per run. A file that holds no more indices than this is a single run.
mode	Whether the scratch starts empty or resumed. An empty scratch has nothing loaded, and does not read storage. A resumed scratch keeps the runs that an earlier scratch loaded into storage, if that scratch had the same fingerprint. A run is kept only if its file has not been modified since. A file whose modification time can not be read is never kept. If the fingerprint differs, the scratch starts empty. The contents of storage must be defined, which those of newly allocated memory are not.

Exceptions

std::invalid_argument	If storage is null, if it is smaller than a fingerprint, if it is not aligned for 64-bit integers or for the data type of a file, or if run_length is zero.
std::out_of_range	If a location has a stack index that its file does not have.
image_file_error	If a file does not exist or can not be read.
unsupported_operation_error	If no format can read a file.
image_file_format_error	If a file is malformed or truncated.

Member Function Documentation

find()

std::shared_ptr< image_scratch_entry > vitrio::indexed_image_scratch::find ( const std::string &  key )

overridevirtual

Get what is held of a file, to read it and to add to it.

Shared ownership rather than a reference, so that an entry stays alive for as long as it is still read through.

Parameters

key	Key of the file.

Returns

std::shared_ptr<image_scratch_entry> The entry of the file, or null when nothing of it is held.

Implements vitrio::image_scratch.

---

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

• vitrio/indexed_image_scratch.hpp