Rosetta  2020.37
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Public Member Functions | Private Attributes | List of all members
utility::io::FileContentsMap Class Reference

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:
Inheritance graph
[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
 
VirtualBaseoperator= (VirtualBase const &)=default
 
VirtualBaseoperator= (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

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

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

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

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_.

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_.

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_.

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

Delete the contents of a particular file from memory.

References 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
Relieson 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_.

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
Relieson 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_.

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_.

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 read_limit_.

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

Increment the internal nread limit for a file.

References read_counts_, and read_limit_.

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 read_limit_.

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 read_counts_.

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_.

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_.

void utility::io::FileContentsMap::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.

References file_contents_.

void utility::io::FileContentsMap::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.

References read_limit_.

Member Data Documentation

bool utility::io::FileContentsMap::delete_contents_at_nread_limit_
private
std::map< std::string, std::string > utility::io::FileContentsMap::file_contents_
private
std::map< std::string, platform::Size > utility::io::FileContentsMap::read_counts_
private
std::map< std::string, platform::Size > utility::io::FileContentsMap::read_limit_
private
bool utility::io::FileContentsMap::refuse_unexpected_files_
private

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