creativity::state::Storage Class Reference

Class for state storage access which accesses State values. More...

#include <creativity/state/Storage.hpp>

Classes
class	state_iterator
	Random access iterator class for iterating through states. More...

Public Member Functions
std::shared_ptr< const State >	operator[] (eris::eris_time_t t) const
	Returns the State for the given simulation time period. More...
size_t	size () const
	Returns the number of states currently stored.
void	reserve (size_t capacity)
	Reserves the requested number of states. More...
bool	empty () const
	Returns true if the container is empty.
void	push_back (std::shared_ptr< const State > s)
	Adds a state to this storage container. More...
void	updateSettings ()
	Writes the settings stored in .settings (which is a reference to the CreativitySettings given during construction) to the storage medium (if appropriate). More...
template<class... Args>
void	emplace_back (Args &&... args)
	Constructs a State using the given arguments, wraps it in a shared_ptr, then inserts it by calling push_back.
void	flush (bool flush_buffers=true)
	Flushes changes of the backend storage object. More...
bool	flush_for (long milliseconds, bool flush_buffers=true)
	Attempts to flushes changes of the backend storage object, with a timeout after the given number of milliseconds. More...
StorageBackend &	backend ()
	Accesses the underlying backend storage instance.
	~Storage ()
	Destructor. Calls flush() (unless flush_on_destroy has been set to false).
state_iterator	begin () const
	Returns a Random Access Iterator to the beginning of the storage object's states. More...
state_iterator	end () const
	Returns a Random Access Iterator to the just-past-the-end of the storage object's states. More...

Static Public Member Functions
template<class SB , class... Args>
static std::enable_if< std::is_base_of< StorageBackend, SB >::value, std::shared_ptr< Storage > >::type	create (CreativitySettings &settings, Args &&... args)
	Storage constructor, which can construct a StorageBackend on the fly. More...

Public Attributes
const CreativitySettings &	settings
	Read-only access to the settings object referenced by this object. More...
bool	flush_on_destroy = true
	If true (the default), flush() is called when the object is destroyed. More...

Detailed Description

Class for state storage access which accesses State values.

Instances of this class are creates with a StorageBackend subclass; this class provides a subscript [] operator, size() method, and push_back(&&) method, which are forward to the back-end class.

See also

creativity::state::StorageBackend

creativity::state::MemoryStorage

creativity::state::FileStorage

Member Function Documentation

begin()

state_iterator creativity::state::Storage::begin

(

)

const

Returns a Random Access Iterator to the beginning of the storage object's states.

create()

template<class SB , class... Args>

static std::enable_if<std::is_base_of<StorageBackend, SB>::value, std::shared_ptr<Storage> >::type creativity::state::Storage::create ( CreativitySettings &  settings, Args &&...  args  )

inlinestatic

Storage constructor, which can construct a StorageBackend on the fly.

Parameters

settings	the CreativitySettings reference
args	parameters to forward to the SB constructor

Returns

a shared pointer to the created Storage object.

end()

state_iterator creativity::state::Storage::end

(

)

const

Returns a Random Access Iterator to the just-past-the-end of the storage object's states.

flush()

void creativity::state::Storage::flush

(

bool

flush_buffers = true

)

Flushes changes of the backend storage object.

This typically blocks until all data in the queue has been written to the underlying storage medium. If the argument is true or omitted, the storage device is also instructed to flush any pending writes; if false, this call may return once all states have been sent to the output stream, but without requiring that the output stream be flushed–this is particularly useful if more data is about to be written, and so the flush is unnecessary.

flush() is called automatically during object destruction, unless flush_on_destroy has been set to false.

Parameters

flush_buffers

whether to flush the output buffer (if the backend supports such a concept). Defaults to true if omitted.

flush_for()

bool creativity::state::Storage::flush_for	(	long	milliseconds,
		bool	flush_buffers = true
	)

Attempts to flushes changes of the backend storage object, with a timeout after the given number of milliseconds.

Example usage:

while (!storage.flush_for(250)) {
    std::cout << "Still waiting; " << storage.pending() << " states remaining\n";
}

Parameters

milliseconds	the maximum number of milliseconds to wait for the flush to complete
flush_buffers	whether, in addition to writing out state data, the output stream buffer should also be flushed (if the backend supports such a concept). Defauls to true if omitted.

Returns

true if the flush completed, false if the timeout was reached without the flush completing.

operator[]()

std::shared_ptr<const State> creativity::state::Storage::operator[]

(

eris::eris_time_t

t

)

const

Returns the State for the given simulation time period.

Parameters

t	the simulation period desired.

Returns

A shared pointer to the requested State. The pointed-at object will be cached, but may only weakly; thus this method may require the backend storage object to load the data from the storage medium on a subsequent call for the same index if the returned reference isn't stored anywhere.

Exceptions

std::out_of_range

if t >= size()

push_back()

void creativity::state::Storage::push_back

(

std::shared_ptr< const State >

s

)

Adds a state to this storage container.

Depending on the backend, the object may only be queued for addition by a thread and not immediately written to the storage medium.

See also

flush()

reserve()

void creativity::state::Storage::reserve

(

size_t

capacity

)

Reserves the requested number of states.

By default this does nothing; subclasses should override if they have a useful reserve() implementation.

updateSettings()

void creativity::state::Storage::updateSettings

(

)

Writes the settings stored in .settings (which is a reference to the CreativitySettings given during construction) to the storage medium (if appropriate).

Existing settings are replaced. This should be called after any changes have been made to the settings so as to commit them to the storage medium.

If not called explicitly, this method will be called by the first push_back() call.

Member Data Documentation

flush_on_destroy

bool creativity::state::Storage::flush_on_destroy = true

If true (the default), flush() is called when the object is destroyed.

If false, it is not, which may result in data loss.

settings

const CreativitySettings& creativity::state::Storage::settings

Read-only access to the settings object referenced by this object.

This object references the settings reference given during construction.

Collaboration diagram for creativity::state::Storage:

---

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

• creativity/state/Storage.hpp