The FileContentsMap is a class that will minimize the number of times files are accessed from disk. The first time the contents of a file are requested, it will cache the contents the file in memory as a strings. All subsequent requests for the contents of that file will then be delivered without having to go to disk. WARNING: The FileContentsMap will not update the contents that it holds for a file after the first time it loads it, so if the contents change on disk, the FileContentsMap will be out of date. More...

#include <FileContentsMap.hh>

Inheritance diagram for utility::io::FileContentsMap:

[legend]

Public Member Functions
	FileContentsMap ()
	Construct an empty FileContentsMap with both boolean options set to false. More...

	FileContentsMap (std::map< std::string, std::string > const &fcontents)
	Construct and populate a FileContentsMap from an input std::map between file names and file contents. Both boolean options are set to false. fcontents is moved and therefore passed by value. More...

void	delete_contents_at_nread_limit (bool setting)
	Enable or disable the behavior that the FileContentsMap will delete the contents of files from memory after they have been read as many times as they were expected to be read (their read limit). More...

bool	delete_contents_at_nread_limit () const
	Return the boolean value describing whether the FileContentsMap will delete the contents of files from memory after they have reached their read limit. More...

void	refuse_unexpected_files (bool setting)
	Enable or disable the behavior that the FCM will refuse to load a file if a non-zero expected number of reads for that file has not been previously provided. More...

bool	refuse_unexpected_files () const
	Return the boolean value describing whether the FileContentsMap will refuse to load files that it does not expect to load. More...

void	set_nread_limit_for_file (std::string const &fname, platform::Size limit)
	Set the maximum number of reads for a file; if this is zero, then that file can be read an indefinite number of times. More...

void	increment_nread_limit (std::string const &fname)
	Increment the internal nread limit for a file. More...

platform::Size	nreads_for_file (std::string const &fname) const
	Return the number of times a particular file has been read. More...

platform::Size	nread_limit_for_file (std::string const &fname) const
	Return the read limit that has been set for this file; this will return a value of zero even if the file has not had a read limit set. Use has_read_limit to determine if a read limit has been set for a particular file. More...

bool	has_read_limit_for_file (std::string const &fname) const
	Return whether a read limit (even one of zero) has been set for a file. More...

bool	has_file_contents (std::string const &fname) const
	Return whether or not the FileContentsMap has the contents of a file in memory. More...

void	set_file_contents (std::string const &fname, std::string const &contents)
	Set the contents of a file from an input string thereby avoiding a read from disk. More...

void	delete_file_contents (std::string const &fname)
	Delete the contents of a particular file from memory. More...

void	clear ()
	Delete the contents of all files and file-read counts from memory. More...

std::string	get_file_contents (std::string const &fname)
	Return the string contents of a file, possibly loading the contents of that file into memory for the first time, always updating internal data, and possibly deleting the contents of a file if it is expected to no longer be needed. More...

std::string const &	get_file_contents_ref (std::string const &fname)
	Return a reference to the string contents of a file, possibly loading the contents of that file into memory for the first time, but not deleting the contents of that file. More...

Public Member Functions inherited from utility::VirtualBase
	VirtualBase ()=default
	Default constructor. More...

virtual	~VirtualBase ()=default
	The virtual destructor is one of the main reasons for the VirtualBase class. More...

	VirtualBase (VirtualBase const &)=default

	VirtualBase (VirtualBase &&)=default

VirtualBase &	operator= (VirtualBase const &)=default

VirtualBase &	operator= (VirtualBase &&)=default

Private Attributes
bool	delete_contents_at_nread_limit_

bool	refuse_unexpected_files_

std::map< std::string, platform::Size >	read_limit_

std::map< std::string, platform::Size >	read_counts_

std::map< std::string, std::string >	file_contents_

Detailed Description

The FileContentsMap is a class that will minimize the number of times files are accessed from disk. The first time the contents of a file are requested, it will cache the contents the file in memory as a strings. All subsequent requests for the contents of that file will then be delivered without having to go to disk. WARNING: The FileContentsMap will not update the contents that it holds for a file after the first time it loads it, so if the contents change on disk, the FileContentsMap will be out of date.

The FileContentsMap offers two settings that are both off by default.

1) You can set whether it should delete files when they reach a "read limit," which in turn requires that you first define a read limit for the file. This can prevent the FileContentsMap from loading too much into memory as long as the utility of a file is expected to be short (i.e. it's read several times in a short period and then never again). Setting a file's read limit to zero signals that the contents of the file should never be deleted from memory i.e. that it has an infinite read limit. If the contents of a file is requested before read limit has been set, then the read limit is set to zero (i.e. infinity).

2) You can set whether it should refuse to load unexpected files. Before you request the contents of a file, you must provide a read limit (zero is an acceptible value here; see above) for that file, or the FileContentsMap will throw an exception when you request that file.

Constructor & Destructor Documentation

◆ FileContentsMap() [1/2]

utility::io::FileContentsMap::FileContentsMap ( )

Construct an empty FileContentsMap with both boolean options set to false.

◆ FileContentsMap() [2/2]

utility::io::FileContentsMap::FileContentsMap ( std::map< std::string, std::string > const & fcontents )

Construct and populate a FileContentsMap from an input std::map between file names and file contents. Both boolean options are set to false. fcontents is moved and therefore passed by value.

Member Function Documentation

◆ clear()

void utility::io::FileContentsMap::clear ( )

Delete the contents of all files and file-read counts from memory.

References file_contents_, read_counts_, and read_limit_.

Referenced by pyrosetta.bindings.pose.ResidueLabelAccessor::discard().

◆ delete_contents_at_nread_limit() [1/2]

bool utility::io::FileContentsMap::delete_contents_at_nread_limit ( ) const

Return the boolean value describing whether the FileContentsMap will delete the contents of files from memory after they have reached their read limit.

References delete_contents_at_nread_limit_.

◆ delete_contents_at_nread_limit() [2/2]

void utility::io::FileContentsMap::delete_contents_at_nread_limit ( bool setting )

Enable or disable the behavior that the FileContentsMap will delete the contents of files from memory after they have been read as many times as they were expected to be read (their read limit).

References delete_contents_at_nread_limit_.

◆ delete_file_contents()

void utility::io::FileContentsMap::delete_file_contents ( std::string const & fname )

Delete the contents of a particular file from memory.

References file_contents_, and PREcst::fname.

◆ get_file_contents()

std::string utility::io::FileContentsMap::get_file_contents ( std::string const & filename )

Return the string contents of a file, possibly loading the contents of that file into memory for the first time, always updating internal data, and possibly deleting the contents of a file if it is expected to no longer be needed.

Exceptions

Relies on utility::file_contents which throws a utility::excn::EXCN_Msg_Exception if the desired file cannot be found. It will also throw an exception if the FileContentsMap has the "refuse unexpected files" setting as true and the file that's requested does not have a read limit that's been set.

References CREATE_EXCEPTION, delete_contents_at_nread_limit_, utility::file_contents(), file_contents_, utility::filename(), read_counts_, read_limit_, and refuse_unexpected_files_.

◆ get_file_contents_ref()

std::string const & utility::io::FileContentsMap::get_file_contents_ref ( std::string const & filename )

Return a reference to the string contents of a file, possibly loading the contents of that file into memory for the first time, but not deleting the contents of that file.

Exceptions

Relies on utility::file_contents which throws a utility::excn::EXCN_Msg_Exception if the desired file cannot be found.

References utility::file_contents(), file_contents_, utility::filename(), read_counts_, and read_limit_.

◆ has_file_contents()

bool utility::io::FileContentsMap::has_file_contents ( std::string const & fname ) const

Return whether or not the FileContentsMap has the contents of a file in memory.

References file_contents_, and PREcst::fname.

◆ has_read_limit_for_file()

bool utility::io::FileContentsMap::has_read_limit_for_file ( std::string const & fname ) const

Return whether a read limit (even one of zero) has been set for a file.

References PREcst::fname, and read_limit_.

◆ increment_nread_limit()

void utility::io::FileContentsMap::increment_nread_limit ( std::string const & fname )

Increment the internal nread limit for a file.

References PREcst::fname, read_counts_, and read_limit_.

◆ nread_limit_for_file()

platform::Size utility::io::FileContentsMap::nread_limit_for_file ( std::string const & fname ) const

Return the read limit that has been set for this file; this will return a value of zero even if the file has not had a read limit set. Use has_read_limit to determine if a read limit has been set for a particular file.

References PREcst::fname, and read_limit_.

◆ nreads_for_file()

platform::Size utility::io::FileContentsMap::nreads_for_file ( std::string const & fname ) const

Return the number of times a particular file has been read.

References PREcst::fname, and read_counts_.

◆ refuse_unexpected_files() [1/2]

bool utility::io::FileContentsMap::refuse_unexpected_files ( ) const

Return the boolean value describing whether the FileContentsMap will refuse to load files that it does not expect to load.

References refuse_unexpected_files_.

◆ refuse_unexpected_files() [2/2]

void utility::io::FileContentsMap::refuse_unexpected_files ( bool setting )

Enable or disable the behavior that the FCM will refuse to load a file if a non-zero expected number of reads for that file has not been previously provided.

References refuse_unexpected_files_.