Set of options for xct manager. More...

Detailed Description

Set of options for xct manager.

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

Definition at line 35 of file xct_options.hpp.

#include <xct_options.hpp>

Inheritance diagram for foedus::xct::XctOptions:

[legend]

Collaboration diagram for foedus::xct::XctOptions:

[legend]

Public Types
enum	Constants { kDefaultMaxReadSetSize = 32 << 10, kDefaultMaxWriteSetSize = 8 << 10, kDefaultMaxLockFreeReadSetSize = 1 << 8, kDefaultMaxLockFreeWriteSetSize = 4 << 10, kDefaultLocalWorkMemorySizeMb = 2, kDefaultEpochAdvanceIntervalMs = 20, kMcsImplementationTypeSimple = 0, kMcsImplementationTypeExtended = 1, kDefaultHotThreshold = 256 }
	Constant values. More...

Public Member Functions
	XctOptions ()
	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
uint32_t	max_read_set_size_
	The maximum number of read-set one transaction can have. More...

uint32_t	max_write_set_size_
	The maximum number of write-set one transaction can have. More...

uint32_t	max_lock_free_read_set_size_
	The maximum number of lock-free read-set one transaction can have. More...

uint32_t	max_lock_free_write_set_size_
	The maximum number of lock-free write-set one transaction can have. More...

uint32_t	local_work_memory_size_mb_
	Size of local and temporary work memory one transaction can use during transaction. More...

uint32_t	epoch_advance_interval_ms_
	Intervals in milliseconds between epoch advancements. More...

bool	enable_retrospective_lock_list_
	Whether to use Retrospective Lock List (RLL) after aborts. More...

uint16_t	hot_threshold_for_retrospective_lock_list_
	When we construct Retrospective Lock List (RLL) after aborts, we add read-locks on records whose hotness exceeds this value. More...

bool	force_canonical_xlocks_in_precommit_
	Whether precommit always releases all locks that violate canonical mode before taking X-locks. More...

uint16_t	mcs_implementation_type_
	Defines which implementation of MCS locks to use for RW locks. More...

Friends
std::ostream &	operator<< (std::ostream &o, const XctOptions &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::xct::XctOptions::Constants

Constant values.

Enumerator
kDefaultMaxReadSetSize	Default value for max_read_set_size_.
kDefaultMaxWriteSetSize	Default value for max_write_set_size_.
kDefaultMaxLockFreeReadSetSize	Default value for max_lock_free_read_set_size_.
kDefaultMaxLockFreeWriteSetSize	Default value for max_lock_free_write_set_size_.
kDefaultLocalWorkMemorySizeMb	Default value for local_work_memory_size_mb_.
kDefaultEpochAdvanceIntervalMs	Default value for epoch_advance_interval_ms_.
kMcsImplementationTypeSimple
kMcsImplementationTypeExtended
kDefaultHotThreshold

Definition at line 37 of file xct_options.hpp.

                  {
     kDefaultMaxReadSetSize = 32 << 10,
     kDefaultMaxWriteSetSize = 8 << 10,
     kDefaultMaxLockFreeReadSetSize = 1 << 8,
     kDefaultMaxLockFreeWriteSetSize = 4 << 10,
     kDefaultLocalWorkMemorySizeMb = 2,
     kDefaultEpochAdvanceIntervalMs = 20,
     kMcsImplementationTypeSimple = 0,
     kMcsImplementationTypeExtended = 1,
     kDefaultHotThreshold = 256,  // OCC by default (for test cases and benchamrks that don't set it)
   };

Constructor & Destructor Documentation

foedus::xct::XctOptions::XctOptions ( )

Constructs option values with default values.

Definition at line 22 of file xct_options.cpp.

References enable_retrospective_lock_list_, epoch_advance_interval_ms_, force_canonical_xlocks_in_precommit_, hot_threshold_for_retrospective_lock_list_, kDefaultEpochAdvanceIntervalMs, kDefaultHotThreshold, kDefaultLocalWorkMemorySizeMb, kDefaultMaxLockFreeReadSetSize, kDefaultMaxLockFreeWriteSetSize, kDefaultMaxReadSetSize, kDefaultMaxWriteSetSize, kMcsImplementationTypeSimple, local_work_memory_size_mb_, max_lock_free_read_set_size_, max_lock_free_write_set_size_, max_read_set_size_, max_write_set_size_, and mcs_implementation_type_.

                        {
   max_read_set_size_ = kDefaultMaxReadSetSize;
   max_write_set_size_ = kDefaultMaxWriteSetSize;
   max_lock_free_read_set_size_ = kDefaultMaxLockFreeReadSetSize;
   max_lock_free_write_set_size_ = kDefaultMaxLockFreeWriteSetSize;
   local_work_memory_size_mb_ = kDefaultLocalWorkMemorySizeMb;
   epoch_advance_interval_ms_ = kDefaultEpochAdvanceIntervalMs;
   enable_retrospective_lock_list_ = false;  // TODO(Hideaki) tentative!
   hot_threshold_for_retrospective_lock_list_ = kDefaultHotThreshold;
   force_canonical_xlocks_in_precommit_ = true;  // TODO(Hideaki) tentative!
   mcs_implementation_type_ = kMcsImplementationTypeSimple;
 }

Member Function Documentation

void foedus::xct::XctOptions::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 60 of file xct_options.hpp.

const char* foedus::xct::XctOptions::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 60 of file xct_options.hpp.

ErrorStack foedus::xct::XctOptions::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 35 of file xct_options.cpp.

References enable_retrospective_lock_list_, epoch_advance_interval_ms_, EXTERNALIZE_LOAD_ELEMENT, force_canonical_xlocks_in_precommit_, hot_threshold_for_retrospective_lock_list_, foedus::kRetOk, local_work_memory_size_mb_, max_lock_free_read_set_size_, max_lock_free_write_set_size_, max_read_set_size_, max_write_set_size_, and mcs_implementation_type_.

                                                        {
   EXTERNALIZE_LOAD_ELEMENT(element, max_read_set_size_);
   EXTERNALIZE_LOAD_ELEMENT(element, max_write_set_size_);
   EXTERNALIZE_LOAD_ELEMENT(element, max_lock_free_read_set_size_);
   EXTERNALIZE_LOAD_ELEMENT(element, max_lock_free_write_set_size_);
   EXTERNALIZE_LOAD_ELEMENT(element, local_work_memory_size_mb_);
   EXTERNALIZE_LOAD_ELEMENT(element, epoch_advance_interval_ms_);
   EXTERNALIZE_LOAD_ELEMENT(element, enable_retrospective_lock_list_);
   EXTERNALIZE_LOAD_ELEMENT(element, hot_threshold_for_retrospective_lock_list_);
   EXTERNALIZE_LOAD_ELEMENT(element, force_canonical_xlocks_in_precommit_);
   EXTERNALIZE_LOAD_ELEMENT(element, mcs_implementation_type_);
   return kRetOk;
 }

ErrorStack foedus::xct::XctOptions::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 49 of file xct_options.cpp.

References CHECK_ERROR, enable_retrospective_lock_list_, epoch_advance_interval_ms_, EXTERNALIZE_SAVE_ELEMENT, force_canonical_xlocks_in_precommit_, hot_threshold_for_retrospective_lock_list_, foedus::externalize::Externalizable::insert_comment(), foedus::kRetOk, local_work_memory_size_mb_, max_lock_free_read_set_size_, max_lock_free_write_set_size_, max_read_set_size_, max_write_set_size_, and mcs_implementation_type_.

                                                              {
   CHECK_ERROR(insert_comment(element, "Set of options for xct manager"));
 
   EXTERNALIZE_SAVE_ELEMENT(element, max_read_set_size_,
     "The maximum number of read-set one transaction can have. Default is 64K records.\n"
     " We pre-allocate this much memory for each NumaCoreMemory. So, don't make it too large.");
   EXTERNALIZE_SAVE_ELEMENT(element, max_write_set_size_,
     "The maximum number of write-set one transaction can have. Default is 16K records.\n"
     " We pre-allocate this much memory for each NumaCoreMemory. So, don't make it too large.");
   EXTERNALIZE_SAVE_ELEMENT(element, max_lock_free_read_set_size_,
     "The maximum number of lock-free read-set one transaction can have.\n"
     " Default is very small (256) because this is the number of sequential storages\n"
     " a xct accesses, not the number of records.");
   EXTERNALIZE_SAVE_ELEMENT(element, max_lock_free_write_set_size_,
     "The maximum number of lock-free write-set one transaction can have. Default is 8K records.\n"
     " We pre-allocate this much memory for each NumaCoreMemory. So, don't make it too large.");
   EXTERNALIZE_SAVE_ELEMENT(element, local_work_memory_size_mb_,
     "Local work memory is used for various purposes during a transaction."
     " We avoid allocating such temporary memory for each transaction and pre-allocate this"
     " size at start up.");
   EXTERNALIZE_SAVE_ELEMENT(element, epoch_advance_interval_ms_,
     "Intervals in milliseconds between epoch advancements. Default is 20 ms\n"
     " Too frequent epoch advancement might become bottleneck because we synchronously write.\n"
     " out savepoint file for each non-empty epoch. However, too infrequent epoch advancement\n"
     " would increase the latency of queries because transactions are not deemed as commit"
     " until the epoch advances.");
   EXTERNALIZE_SAVE_ELEMENT(element, enable_retrospective_lock_list_,
     "When enabled, we remember read/write-sets on abort and use it as RLL on next run.");
   EXTERNALIZE_SAVE_ELEMENT(element, hot_threshold_for_retrospective_lock_list_,
     "When we construct Retrospective Lock List (RLL) after aborts, we add"
     " read-locks on records whose hotness exceeds this value.");
   EXTERNALIZE_SAVE_ELEMENT(element, force_canonical_xlocks_in_precommit_,
     "Whether precommit always releases all locks that violate canonical mode before"
     " taking X-locks.");
   EXTERNALIZE_SAVE_ELEMENT(element, mcs_implementation_type_,
     "Defines which implementation of MCS locks to use for RW locks."
     " So far we allow kMcsImplementationTypeSimple and kMcsImplementationTypeExtended.");
   return kRetOk;
 }

Here is the call graph for this function:

Friends And Related Function Documentation

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

friend

Definition at line 60 of file xct_options.hpp.

Member Data Documentation

bool foedus::xct::XctOptions::enable_retrospective_lock_list_

Whether to use Retrospective Lock List (RLL) after aborts.

Default is true. When enabled, we remember read/write-sets on abort and use it as RLL on next run. This is a system-wide setting, which can be overwritten by individual transactions. See Xct::enable_rll_for_this_xct_. In short, this is a default value for that one. Retrospective Lock List

Definition at line 123 of file xct_options.hpp.

Referenced by foedus::thread::ThreadPimpl::handle_tasks(), foedus::xct::Xct::initialize(), load(), save(), and XctOptions().

uint32_t foedus::xct::XctOptions::epoch_advance_interval_ms_

Intervals in milliseconds between epoch advancements.

Default is 20 ms. Too frequent epoch advancement might become bottleneck because we synchronously write out savepoint file for each non-empty epoch. However, too infrequent epoch advancement would increase the latency of queries because transactions are not deemed as commit until the epoch advances.

Definition at line 112 of file xct_options.hpp.

Referenced by foedus::xct::XctManagerPimpl::handle_epoch_chime(), load(), save(), and XctOptions().

bool foedus::xct::XctOptions::force_canonical_xlocks_in_precommit_

Whether precommit always releases all locks that violate canonical mode before taking X-locks.

Default is (so far) true. This option has pros and cons. We need to keep an eye on which is better. When true, precommit_lock function releases all locks (S or X) that are after any of X-locks we are going to take. In worst case, a subtle page split, which slightly violates canonical order, triggers releaseing a large number of X-locks that need to be taken again and a large number of S-locks that would have reduced the chance of abort. Wasted effort!

However, on the other hand, this allows us to take all X-locks unconditionally without any fear of deadlocks or false conflicts. Otherwise we have to try some X-locks conditionally and abort if couldn't immediately acquire the lock. In some cases, this would avoid unnecessary RaceAbort. So... really not sure which is better. The default value is so far true because the policy is simpler. Retrospective Lock List

Definition at line 155 of file xct_options.hpp.

Referenced by load(), foedus::xct::XctManagerPimpl::precommit_xct_lock(), save(), and XctOptions().

uint16_t foedus::xct::XctOptions::hot_threshold_for_retrospective_lock_list_

When we construct Retrospective Lock List (RLL) after aborts, we add read-locks on records whose hotness exceeds this value.

This value should be a bit lower than the threshold we trigger read-locks without RLL (StorageOptions::hot_threshold_). Otherwise, the next run might often take a read-lock the RLL discarded due to a concurrent abort, which might violate canonical order. Retrospective Lock List

Definition at line 135 of file xct_options.hpp.

Referenced by foedus::thread::ThreadPimpl::handle_tasks(), foedus::xct::Xct::initialize(), load(), save(), and XctOptions().

uint32_t foedus::xct::XctOptions::local_work_memory_size_mb_

Size of local and temporary work memory one transaction can use during transaction.

Local work memory is used for various purposes during a transaction. We avoid allocating such temporary memory for each transaction and pre-allocate this size at start up.

Definition at line 101 of file xct_options.hpp.

Referenced by foedus::EngineOptions::calculate_required_memory(), load(), save(), and XctOptions().

uint32_t foedus::xct::XctOptions::max_lock_free_read_set_size_

The maximum number of lock-free read-set one transaction can have.

Default is very small (256) because this is the number of sequential storages a xct accesses, not the number of records.

Definition at line 84 of file xct_options.hpp.

Referenced by foedus::memory::NumaCoreMemory::calculate_local_small_memory_size(), foedus::xct::Xct::initialize(), load(), save(), and XctOptions().

uint32_t foedus::xct::XctOptions::max_lock_free_write_set_size_

The maximum number of lock-free write-set one transaction can have.

Default is 8K records. We pre-allocate this much memory for each NumaCoreMemory. So, don't make it too large.

Definition at line 92 of file xct_options.hpp.

Referenced by foedus::memory::NumaCoreMemory::calculate_local_small_memory_size(), foedus::xct::Xct::initialize(), load(), save(), and XctOptions().