Set of options for snapshot cache manager. More...

Detailed Description

Set of options for snapshot cache manager.

This is a POD struct. Default destructor/copy-constructor/assignment operator work fine.

Definition at line 29 of file cache_options.hpp.

#include <cache_options.hpp>

Inheritance diagram for foedus::cache::CacheOptions:

[legend]

Collaboration diagram for foedus::cache::CacheOptions:

[legend]

Public Types
enum	Constants { kDefaultSnapshotCacheSizeMbPerNode = 1 << 10 }
	Constant values. More...

Public Member Functions
	CacheOptions ()
	Constructs option values with default values. More...

ErrorStack	load (tinyxml2::XMLElement *element) override
	Reads the content of this object from the given XML element. More...

ErrorStack	save (tinyxml2::XMLElement *element) const override
	Writes the content of this object to the given XML element. More...

const char *	get_tag_name () const override
	Returns an XML tag name for this object as a root element. More...

void	assign (const foedus::externalize::Externalizable *other) override
	Polymorphic assign operator. More...

Public Member Functions inherited from foedus::externalize::Externalizable
ErrorStack	load_from_string (const std::string &xml)
	Load the content of this object from the given XML string. More...

void	save_to_stream (std::ostream *ptr) const
	Invokes save() and directs the resulting XML text to the given stream. More...

ErrorStack	load_from_file (const fs::Path &path)
	Load the content of this object from the specified XML file. More...

ErrorStack	save_to_file (const fs::Path &path) const
	Atomically and durably writes out this object to the specified XML file. More...

Public Attributes
bool	snapshot_cache_enabled_
	Whether to cache the read accesses on snapshot files. More...

uint32_t	snapshot_cache_size_mb_per_node_
	Size of the snapshot cache in MB per each NUMA node. More...

uint32_t	private_snapshot_cache_initial_grab_
	How many pages for snapshot cache each NumaCoreMemory initially grabs when it is initialized. More...

float	snapshot_cache_eviction_threshold_
	When to start evicting pages in fraction of snapshot page pool capacity. More...

float	snapshot_cache_urgent_threshold_
	When the cache eviction performs in an urgent mode, which immediately advances the current epoch to release pages. More...

Friends
std::ostream &	operator<< (std::ostream &o, const CacheOptions &v)

Additional Inherited Members
Static Public Member Functions inherited from foedus::externalize::Externalizable
static ErrorStack	insert_comment (tinyxml2::XMLElement *element, const std::string &comment)

static ErrorStack	append_comment (tinyxml2::XMLElement *parent, const std::string &comment)

static ErrorStack	create_element (tinyxml2::XMLElement parent, const std::string &name, tinyxml2::XMLElement *out)

template<typename T >
static ErrorStack	add_element (tinyxml2::XMLElement *parent, const std::string &tag, const std::string &comment, T value)
	Only declaration in header. More...

template<uint MAXLEN, typename CHAR >
static ErrorStack	add_element (tinyxml2::XMLElement *parent, const std::string &tag, const std::string &comment, const assorted::FixedString< MAXLEN, CHAR > &value)

template<typename T >
static ErrorStack	add_element (tinyxml2::XMLElement *parent, const std::string &tag, const std::string &comment, const std::vector< T > &value)
	vector version More...

template<typename ENUM >
static ErrorStack	add_enum_element (tinyxml2::XMLElement *parent, const std::string &tag, const std::string &comment, ENUM value)
	enum version More...

static ErrorStack	add_child_element (tinyxml2::XMLElement *parent, const std::string &tag, const std::string &comment, const Externalizable &child)
	child Externalizable version More...

template<typename T >
static ErrorStack	get_element (tinyxml2::XMLElement parent, const std::string &tag, T out, bool optional=false, T value=0)
	Only declaration in header. More...

static ErrorStack	get_element (tinyxml2::XMLElement parent, const std::string &tag, std::string out, bool optional=false, const char *value="")
	string type is bit special. More...

template<uint MAXLEN, typename CHAR >
static ErrorStack	get_element (tinyxml2::XMLElement parent, const std::string &tag, assorted::FixedString< MAXLEN, CHAR > out, bool optional=false, const assorted::FixedString< MAXLEN, CHAR > &value=assorted::FixedString< MAXLEN, CHAR >())

template<typename ENUM >
static ErrorStack	get_enum_element (tinyxml2::XMLElement parent, const std::string &tag, ENUM out, bool optional=false, ENUM default_value=static_cast< ENUM >(0))
	enum version More...

template<typename T >
static ErrorStack	get_element (tinyxml2::XMLElement parent, const std::string &tag, std::vector< T > out, bool optional=false)
	vector version. More...

static ErrorStack	get_child_element (tinyxml2::XMLElement parent, const std::string &tag, Externalizable child, bool optional=false)
	child Externalizable version More...

Member Enumeration Documentation

enum foedus::cache::CacheOptions::Constants

Constant values.

Enumerator
kDefaultSnapshotCacheSizeMbPerNode	Default value for snapshot_cache_size_mb_per_node_.

Definition at line 31 of file cache_options.hpp.

                  {
     kDefaultSnapshotCacheSizeMbPerNode = 1 << 10,
   };

Constructor & Destructor Documentation

foedus::cache::CacheOptions::CacheOptions ( )

Constructs option values with default values.

Definition at line 24 of file cache_options.cpp.

References kDefaultSnapshotCacheSizeMbPerNode, foedus::memory::PagePoolOffsetChunk::kMaxSize, private_snapshot_cache_initial_grab_, snapshot_cache_enabled_, snapshot_cache_eviction_threshold_, snapshot_cache_size_mb_per_node_, and snapshot_cache_urgent_threshold_.

                            {
   snapshot_cache_enabled_ = true;
   snapshot_cache_size_mb_per_node_ = kDefaultSnapshotCacheSizeMbPerNode;
   private_snapshot_cache_initial_grab_ = memory::PagePoolOffsetChunk::kMaxSize / 2;
   snapshot_cache_eviction_threshold_ = 0.75;
   snapshot_cache_urgent_threshold_ = 0.9;
 }

Member Function Documentation

void foedus::cache::CacheOptions::assign ( const foedus::externalize::Externalizable * other )

inlineoverridevirtual

Polymorphic assign operator.

This should invoke operator= of the derived class.

Parameters

[in] other assigned value. It must be dynamic-castable to the assignee class.

Implements foedus::externalize::Externalizable.

Definition at line 98 of file cache_options.hpp.

const char* foedus::cache::CacheOptions::get_tag_name ( ) const

inlineoverridevirtual

Returns an XML tag name for this object as a root element.

We might want to give a different name for same externalizable objects, so this is used only when it is the root element of xml.

Implements foedus::externalize::Externalizable.

Definition at line 98 of file cache_options.hpp.

ErrorStack foedus::cache::CacheOptions::load ( tinyxml2::XMLElement * element )

overridevirtual

Reads the content of this object from the given XML element.

Parameters

[in] element the XML element that represents this object

Expect errors due to missing-elements, out-of-range values, etc.

Implements foedus::externalize::Externalizable.

Definition at line 31 of file cache_options.cpp.

References ASSERT_ND, EXTERNALIZE_LOAD_ELEMENT, foedus::kRetOk, private_snapshot_cache_initial_grab_, snapshot_cache_enabled_, snapshot_cache_eviction_threshold_, snapshot_cache_size_mb_per_node_, and snapshot_cache_urgent_threshold_.

                                                          {
   EXTERNALIZE_LOAD_ELEMENT(element, snapshot_cache_enabled_);
   EXTERNALIZE_LOAD_ELEMENT(element, snapshot_cache_size_mb_per_node_);
   EXTERNALIZE_LOAD_ELEMENT(element, private_snapshot_cache_initial_grab_);
   EXTERNALIZE_LOAD_ELEMENT(element, snapshot_cache_eviction_threshold_);
   ASSERT_ND(snapshot_cache_eviction_threshold_ > 0);
   ASSERT_ND(snapshot_cache_eviction_threshold_ < 1);
   EXTERNALIZE_LOAD_ELEMENT(element, snapshot_cache_urgent_threshold_);
   ASSERT_ND(snapshot_cache_urgent_threshold_ >= snapshot_cache_eviction_threshold_);
   ASSERT_ND(snapshot_cache_urgent_threshold_ <= 1);
   return kRetOk;
 }

ErrorStack foedus::cache::CacheOptions::save ( tinyxml2::XMLElement * element ) const

overridevirtual

Writes the content of this object to the given XML element.

Parameters

[in] element the XML element that represents this object

Expect only out-of-memory error. We receive the XML element this object will represent, so this method does not determine the XML element name of itself. The parent object determines children's tag names because one parent object might have multiple child objects of the same type with different XML element name.

Implements foedus::externalize::Externalizable.

Definition at line 43 of file cache_options.cpp.

References ASSERT_ND, CHECK_ERROR, EXTERNALIZE_SAVE_ELEMENT, foedus::externalize::Externalizable::insert_comment(), foedus::kRetOk, private_snapshot_cache_initial_grab_, snapshot_cache_enabled_, snapshot_cache_eviction_threshold_, snapshot_cache_size_mb_per_node_, and snapshot_cache_urgent_threshold_.

                                                                {
   CHECK_ERROR(insert_comment(element, "Set of options for snapshot cache manager."));
   EXTERNALIZE_SAVE_ELEMENT(element, snapshot_cache_enabled_,
     "Whether to cache the read accesses on snapshot files.");
   EXTERNALIZE_SAVE_ELEMENT(element, snapshot_cache_size_mb_per_node_,
     "Size of the snapshot cache in MB per each NUMA node.");
   EXTERNALIZE_SAVE_ELEMENT(element, private_snapshot_cache_initial_grab_,
     "How many pages for snapshot cache each NumaCoreMemory initially grabs"
     " when it is initialized.");
   ASSERT_ND(snapshot_cache_eviction_threshold_ > 0);
   ASSERT_ND(snapshot_cache_eviction_threshold_ < 1);
   EXTERNALIZE_SAVE_ELEMENT(
     element,
     snapshot_cache_eviction_threshold_,
     "When to start evicting pages in fraction of snapshot page pool capacity");
   ASSERT_ND(snapshot_cache_urgent_threshold_ >= snapshot_cache_eviction_threshold_);
   ASSERT_ND(snapshot_cache_urgent_threshold_ <= 1);
   EXTERNALIZE_SAVE_ELEMENT(
     element,
     snapshot_cache_urgent_threshold_,
     "When the cache eviction performs in an urgent mode, which immediately advances"
     " the current epoch to release pages");
   return kRetOk;
 }

Here is the call graph for this function:

Friends And Related Function Documentation

std::ostream& operator<<	(	std::ostream &	o,
		const CacheOptions &	v
	)

friend

Definition at line 98 of file cache_options.hpp.

Member Data Documentation

uint32_t foedus::cache::CacheOptions::private_snapshot_cache_initial_grab_

How many pages for snapshot cache each NumaCoreMemory initially grabs when it is initialized.

Default is 50% of PagePoolOffsetChunk::MAX_SIZE. Obviously, private_snapshot_cache_initial_grab_ * kPageSize * number-of-threads-per-node must be within snapshot_cache_size_mb_per_node_ to start up the engine.

Definition at line 68 of file cache_options.hpp.

Referenced by CacheOptions(), load(), and save().

bool foedus::cache::CacheOptions::snapshot_cache_enabled_

Whether to cache the read accesses on snapshot files.

If the storage media is 2x or more slower than DRAM, we should cache it, but otherwise we should turn it off and directly read from snapshot files on it. This property turns on/off the entire snapshot cache module (remember, snapshot cache is a totally optional module unlike bufferpools in traditional databases). Default is ON.

Definition at line 50 of file cache_options.hpp.

Referenced by CacheOptions(), foedus::thread::ThreadPimpl::find_or_read_a_snapshot_page(), foedus::thread::ThreadPimpl::find_or_read_snapshot_pages_batch(), foedus::thread::ThreadPimpl::initialize_once(), load(), and save().

float foedus::cache::CacheOptions::snapshot_cache_eviction_threshold_

When to start evicting pages in fraction of snapshot page pool capacity.

Invariant: between (0, 1)

This is an important tuning parameter. If the snapshot page pool is sufficiently large and the cleaner can perfectly catch up with the speed of free-page consumption by worker threads, this can be 99% to maximize the use of DRAM. However, in most cases the assumptions do not hold, so this should be something like 75%. If it's too large, you will see no-free-pages error in transaction executions. If it's too small, you get more cache misses due to utilizing less DRAM. Probably the latter is less problemetic.

Definition at line 83 of file cache_options.hpp.

Referenced by CacheOptions(), foedus::cache::CacheManagerPimpl::initialize_once(), load(), and save().

uint32_t foedus::cache::CacheOptions::snapshot_cache_size_mb_per_node_

Size of the snapshot cache in MB per each NUMA node.

Must be multiply of 2MB. Default is 1GB. The total amount of memory is page_pool_size_mb_per_node_ *

Definition at line 58 of file cache_options.hpp.

Referenced by CacheOptions(), foedus::EngineOptions::calculate_required_memory(), foedus::memory::NumaNodeMemory::initialize_once(), load(), and save().

float foedus::cache::CacheOptions::snapshot_cache_urgent_threshold_

When the cache eviction performs in an urgent mode, which immediately advances the current epoch to release pages.

Invariant: between [snapshot_cache_eviction_threshold_, 1]

We shouldn't advance current epoch too often as it might run out of the value space and we might need synchronization with worker threads to maintain "low water mark". So, the cleaner usually just passively waits for the new epoch while the grace period. When the system is really running out of free pages, we should do something else. This parameter specifies when to do that.

Definition at line 96 of file cache_options.hpp.

Referenced by CacheOptions(), foedus::cache::CacheManagerPimpl::initialize_once(), load(), and save().

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

/home/shino/foedus_code/foedus-core/include/foedus/cache/cache_options.hpp
/home/shino/foedus_code/foedus-core/src/foedus/cache/cache_options.cpp

Detailed Description

Public Types

Public Member Functions

Public Attributes

Friends

Additional Inherited Members

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation