Transaction

For conceptual usage, see:

• Memory Transactions and Lifecycle

Python binding

This C++ class is also exported into Python as rogue.interfaces.memory.Transaction.

Python API page: - Transaction

objects in C++ are referenced by the following shared pointer typedef:

typedef std::shared_ptr<rogue::interfaces::memory::Transaction> rogue::interfaces::memory::TransactionPtr
[header]

Shared pointer alias for Transaction.

The class description is shown below:

class Transaction : public rogue::EnableSharedFromThis<rogue::interfaces::memory::Transaction>
[header]

Memory transaction container passed between master and slave.

Encapsulates a single memory operation request and completion state while it moves between Master and Slave layers.

Lifecycle and ownership:

• Instances are created internally by Master; callers do not construct them directly.

• A transaction is identified by a unique 32-bit ID.

• Data is accessed through an internal byte iterator and guarded by TransactionLock.

• Completion is signaled via done() or error*() and may be observed by wait logic.

Timeout and completion behavior:

• A per-transaction timeout is captured at creation and used by wait/refresh logic.

• Transactions may expire when timeout is reached before completion.

• Timeout refresh can propagate from parent/peer activity to avoid premature expiration.

Subtransaction behavior:

• A transaction can be split into child subtransactions.

• Parent tracks children in subTranMap_ and completes only after all children complete (or propagates child error to the parent).

Python integration:

• Python buffer-backed transactions are supported when Python APIs are used.

• Accessors such as id(), address(), size(), type(), and expired() are exposed to Python bindings.

Public Types

typedef uint8_t *iterator
[header]

Iterator alias for transaction byte access.

Public Functions

explicit Transaction(struct timeval timeout)
[header] [impl]

Constructs a transaction container.

Create object.

This constructor is a low-level C++ allocation path. Prefer create() for normal transaction lifecycle management. Do not call this constructor directly in normal use; transactions are expected to be created by Master through the internal create() path. That path ensures consistent ownership and integration with transaction request/wait bookkeeping.

Parameters:

timeout – Initial timeout value copied into this transaction.

~Transaction()
[header] [impl]

Destroy object.

std::shared_ptr<rogue::interfaces::memory::TransactionLock> lock()
[header] [impl]

Locks the transaction and returns a lock wrapper.

Get lock.

Exposed as lock() in Python.

Returns:

Transaction lock pointer.

bool expired()
[header] [impl]

Returns whether this transaction has expired.

Get expired state.

Expiration is set by Master when timeout occurs and no further waiting is performed. The lock must be held before checking expiration state. Exposed as expired() in Python.

Returns:

true if transaction is expired; otherwise false.

uint32_t id()
[header] [impl]

Returns the transaction ID.

Get id.

Exposed as id() in Python.

Returns:

32-bit transaction ID.

uint64_t address()
[header] [impl]

Returns the transaction address.

Get address.

Exposed as address() in Python.

Returns:

64-bit transaction address.

uint32_t size()
[header] [impl]

Returns the transaction size.

Get size.

Exposed as size() in Python.

Returns:

32-bit transaction size in bytes.

uint32_t type()
[header] [impl]

Returns the transaction type constant.

Get type.

Type values are defined in rogue/interfaces/memory/Constants.h, including:

• rogue::interfaces::memory::Read

• rogue::interfaces::memory::Write

• rogue::interfaces::memory::Post

• rogue::interfaces::memory::Verify

Exposed as type() in Python.

Returns:

32-bit transaction type.

std::shared_ptr<rogue::interfaces::memory::Transaction> createSubTransaction()
[header] [impl]

Creates a subtransaction linked to this parent transaction.

Create a subtransaction.

Returns:

Pointer to the newly created subtransaction.

void doneSubTransactions()
[header] [impl]

Marks subtransaction creation as complete for this transaction.

void refreshTimer(std::shared_ptr<rogue::interfaces::memory::Transaction> reference)
[header] [impl]

Refreshes the transaction timer.

Refresh the timer.

Timer is refreshed when reference is null or when this transaction start time is later than the reference transaction start time. Not exposed to Python.

Parameters:

reference – Reference transaction.

void done()
[header] [impl]

Marks transaction completion without error.

Complete transaction without error, lock must be held.

The transaction lock must be held before calling this method. Exposed as done() in Python.

void errorStr(std::string error)
[header] [impl]

Marks transaction completion with an error string (Python interface).

Complete transaction with passed error, lock must be held.

The transaction lock must be held before calling this method. Exposed as error() in Python.

Parameters:

error – Transaction error message.

void error(const char *fmt, ...)
[header] [impl]

Marks transaction completion with a formatted C-string error.

Complete transaction with passed error, lock must be held.

The transaction lock must be held before calling this method.

uint8_t *begin()
[header] [impl]

Returns iterator to the beginning of transaction data.

start iterator, caller must lock around access

Not exposed to Python. Lock must be held before calling this method and while updating transaction data.

Returns:

Data iterator.

uint8_t *end()
[header] [impl]

Returns iterator to the end of transaction data.

end iterator, caller must lock around access

Not exposed to Python. Lock must be held before calling this method and while updating transaction data.

Returns:

Data iterator.

void getData(boost::python::object p, uint32_t offset)
[header] [impl]

Copies transaction data into a Python byte-array-like object.

Get transaction data from python.

Exposed to Python as getData(). The copy size is defined by the provided destination buffer size.

Parameters:

• p – Python byte-array-like destination object.

• offset – Offset for transaction data access.

void setData(boost::python::object p, uint32_t offset)
[header] [impl]

Copies data from a Python byte-array-like object into the transaction.

Set transaction data from python.

Exposed to Python as setData(). The copy size is defined by the provided source buffer size.

Parameters:

• p – Python byte-array-like source object.

• offset – Offset for transaction data access.