#include <ringfilecache.H>

Classes
class	Pointer

Public Member Functions
string	to_string () const

T	read (const Pointer &ptr)

void	write (const Pointer &ptr, const T &item)

bool	is_initialized () const

size_t	size () const noexcept
	Returns the number of entries stored in the cache.

size_t	capacity () const noexcept
	Returns the maximum capacity.

size_t	avail () const noexcept
	Returns the number of available entries.

size_t	head_pos () const noexcept
	Returns the current head position.

size_t	tail_pos () const noexcept
	return the current tail position

bool	is_empty () const noexcept
	Returns true if the cache is empty.

	RingFileCache (const string &pars_fname)

	RingFileCache ()

void	init (const string &pars_fname)

bool	put (const T &item)

bool	read (T entries[], const size_t m=1)

T	read_first ()
	Read the oldest entry in the set.

T	read_last ()
	Read the youngest entry in the set.

T	youngest ()

T	oldest ()

T	oldest (size_t i)

Array< T >	read_all ()

Array< T >	read_from (const size_t pos, const size_t m)

Array< T >	read_from (const Pointer &ptr, const size_t m)

bool	get (const size_t m=1) noexcept

void	empty ()
	empties the cache; all the entries are deleted

void	flush ()

void	close ()

void	resize (const size_t sz)

auto	get_it ()

Static Public Member Functions
static void	create (const string &pars_file_name, const string &cache_file_name, const size_t num_entries)

static bool	test (const string &pars_fname)

Friends
ostream &	operator<< (ostream &out, const RingFileCache &cache)

Detailed Description

template<typename T>
class RingFileCache< T >

Ring cache stored in a file.

Author: Leandro Rabindranath Leon

Constructor & Destructor Documentation

◆ RingFileCache() [1/2]

template<typename T>

RingFileCache< T >::RingFileCache ( const string & pars_fname )

inline

Initialize a cache previously built.

The internal state of cache is represented by a file specified with the parameters file called pars_file_name and passed during create() static method. The name of cache is also passed to create(), but this one is stored in the parameters file.

So, in order to instantiate a cache, it is enough to pass the parameters file name.

Parameters

[in] pars_fname name of cache parameters file

Exceptions

domain_error	if any file cannot be opened
std::ios_base::failure	if there is a failure in any file.

◆ RingFileCache() [2/2]

template<typename T>

RingFileCache< T >::RingFileCache ( )

inline

Default constructor.

This constructor is given for avoiding dependences of files creation.

Warning: The constructed cache is in an invalid state

See also: init()

Here is the caller graph for this function:

Member Function Documentation

◆ create()

template<typename T>

static void RingFileCache< T >::create	(	const string &	pars_file_name,
		const string &	cache_file_name,
		const size_t	num_entries
	)

inlinestatic

Create a cache with parameters file stored in pars_file_name file, cache file in cache_file_name and with capacity for num_entries entries.

This is the very first function to be called for creating and initializing a new cache. Basically, the function create two new files:

pars_file_name where the cache parameters (its internal state) is saved
cache_file_name: where the data entries to be cached will be stored. This file is created for storing num_entries.

After cache creation these files are created. The internal state of cache is stored in the file pars_file_name, included the cache file.

Parameters

[in]	pars_file_name	name of parameters file
[in]	pars_file_name	name of cache file where the entries are stored.
[in]	num_entries	number of entries to be stored in the cache

Exceptions

domain_error	if any file cannot be open, read o written
bad_alloc	if there is no enough memory

◆ flush()

template<typename T>

void RingFileCache< T >::flush ( )

inline

Flushes to the disk all the internal cache state.

Use this method wisely, Many calls could be very time expensive, but with very few calls the persistence reward of this class is lost.

Here is the caller graph for this function:

◆ get()

template<typename T>

bool RingFileCache< T >::get ( const size_t m = 1 )

inlinenoexcept

Extracts (deletes) from the cache the n most older inserted items.

Parameters

[in] m number of items to be extracted

Returns: true if the m items were extracted

◆ init()

template<typename T>

void RingFileCache< T >::init ( const string & pars_fname )

inline

Initialize a cache constructed with the default contructor.

Warning: : behaviour is unpredictable if a valid cache has already been constructed.

Parameters

[in] pars_fname name of cache parameters file

Exceptions

domain_error	if a pars file is already opened
std::ios_base::failure	if there is a failure in any file.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ put()

template<typename T>

bool RingFileCache< T >::put ( const T & item )

inline

Insert an item into the cache.

recall that the cache obeys to a FIFO discipline. So, the entry is inserted at the tail.

Parameters

[in] item to be inserted into the queue

Returns: true if the 'item' was correctly inserted; false otherwise

Exceptions

std::ios_base::failure if there is a failure in any file.

◆ read()

template<typename T>

bool RingFileCache< T >::read	(	T	entries[],
		const size_t	m = `1`
	)

inline

Read the m most old entries and load them in a contiguos array.

read() reads the m most old entries, those located on the queue head side and loads them in the contiguous array entries. Of course, entries must be enough large for containing the m entries.

This method does not alter the internal state of the cache, no element is removed.

The expected protocol for using is to read with this method and afterward, if everything was ok, to remove them by invoking get() method.

Parameters

[in]	m	the number of entries to be read from the queue `head` side
[in]	entries	a array where the read entries will be put.

Returns: true if the m entries were read; false otherwise, what only happens if m is greater than the current number of stored elements.

Exceptions

std::ios_base::failure if there is a failure in any file.

See also: get()

◆ read_all()

template<typename T>

Array<T> RingFileCache< T >::read_all ( )

inline

read all the entries

Returns: an dynamic and contiguous array with all the entries of the cache

Here is the call graph for this function:

◆ read_from() [1/2]

template<typename T>

Array<T> RingFileCache< T >::read_from	(	const size_t	pos,
		const size_t	m
	)

inline

read m entries from the pos-th older position.

The returned array size indicates how many entries were effectively read.

Here is the call graph for this function:

◆ read_from() [2/2]

template<typename T>

Array<T> RingFileCache< T >::read_from	(	const Pointer &	ptr,
		const size_t	m
	)

inline

read m entries from the pointer older position.

The returned array size indicates how many entries were effectively read.

Here is the call graph for this function:

◆ resize()

template<typename T>

void RingFileCache< T >::resize ( const size_t sz )

inline

Resize the maximum capacity of the cache.

Currently only the size increase is implemented.

Parameters

[in] sz new capacity

Exceptions

domain_error	if sz is lesser than the current capacity
std::ios_base::failure	if there is a failure in any file

Here is the call graph for this function:

◆ test()

template<typename T>

static bool RingFileCache< T >::test ( const string & pars_fname )

inlinestatic

Tests if pars and cache files have been created.

Parameters

[in] pars_fname name of parameters file

Returns: true if pars_fname exists and its associated cache file exists too.

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

ringfilecache.H

Classes

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

template<typename T> class RingFileCache< T >

Constructor & Destructor Documentation

◆ RingFileCache() [1/2]

◆ RingFileCache() [2/2]

Member Function Documentation

◆ create()

◆ flush()

◆ get()

◆ init()

◆ put()

◆ read()

◆ read_all()

◆ read_from() [1/2]

◆ read_from() [2/2]

◆ resize()

◆ test()

template<typename T>
class RingFileCache< T >