Skip to content

TransItem Interface

Jump to bottom
Yihe (William) Huang edited this page Feb 13, 2018 · 2 revisions

TransItem is the abstract representation of an entry of the transaction tracking set in STO. All concurrency control operations are invoked on TransItems. A TransItem can be used to represent generic memory words, a row or a tuple in a database, or abstract state such as predicates or the key range of a tree.

The class TransItem is defined and implemented in sto-core/TransItem.hh. Many aspects of the TransItem interface is internal to STO and not used directly by data types. The most important public-facing TransItem-related methods are listed below.

Tracking Set Access

The following method is used to access the transaction tracking set during the transaction:

template <typename T>
TranxProxy& Sto::item(TObject *owner, T key) // Define in sto-core/Transaction.hh

This will also create a new tracking set entry if needed.

Note: the returned TransProxy object contains a reference to the underlying TransItem and should behave mostly like a TransItem object.

Concurrency Control

Transactional data types or other STO applications register read/write accesses with the STO core through calls on TransItem. STO performs concurrency control based on TransItem calls.

acquire_write() Methods

The following methods register write accesses to a given TransItem with STO.

// Define in sto-core/TransItem.hh
template <typename VersImpl>
bool TransItem::acquire_write(VersionBase<VersImpl>& vers);

template <typename VersImpl, typename T>
bool TransItem::acquire_write(VersionBase<VersImpl>& vers, const T& wdata);

template <typename VersImpl, typename T>
bool TransItem::acquire_write(VersionBase<VersImpl>& vers, T&& wdata);

template <typename T, typename VersImpl, typename... Args>
bool TransItem::acquire_write(VersionBase<VersImpl>& vers, Args&&... args);

These methods take reference of a "version number" associated with the TransItem object, and optionally the new data that overwrites the existing data. The version number is added as an argument to support concurrency control mechanisms like TicToc, SwissTM, or eager locking.

The latter three of the four methods support three different ways of constructing the write data that's buffered in a TransItem: copy construction, move construction, or argument forwarding. The latter two require C++11.

VersionBase<VersImpl> is an interface class of all version number implementations. Different version numbers implement different concurrency control mechanisms.

observe() Methods

The following method register read accesses with STO:

template <typename VersImpl>
bool observe(VersionBase<VersImpl>& version);

Again, concurrency control policy is implemented by the version object passed in.

Retrieve Tracking Set Entry Info

The TransItem also provide accessors to important attribute of the object (useful at commit time).

key() Method

Returns the key associated with the TransItem (specified when constructing the TransItem).

template <typename T>
T TransItem::key();

read_value() and write_value()

When invoking TransItem methods, information may be stored in the TransItem (depending on the concurrency control protocol). For example, when using OCC, a copy of the version will be stored in the rdata_ field of the TransItem object, so that we can compare it with the version number at commit time to make sure it hasn't changed. Likewise, buffered writes are stored in wdata_ field of a TransItem. One can access these information during the lifetime of the TransItem using the following methods:

template <typename T>
const T& TransItem::read_value() const;

template <typename T>
T& TransItem::write_value();

Note on Templated Methods and Possible Indirection

You probably notice that many of the methods here are templated, meaning they can accept any type. The size of the TransItem, however, is constant. The fields in TransItem are all 8-byte-wide (sizeof(unsigned long) on 64-bit machines), so if a type larger than 8 bytes is used a level of indirection will be created automatically. This can have impact on performance. Keep keys, rdata and wdata at or below 8 bytes if you can.

Clone this wiki locally