Transaction

Overview

Transaction is the unit of work that moves through the Rogue memory bus between Master and Slave objects. It carries:

• transaction metadata (ID, address, size, type),

• data buffer access (iterators/pointers),

• completion/error state,

• timeout tracking information.

Transactions are not normally constructed by user code. They are created by Master when a request is issued.

Lifecycle

Typical flow:

1. A master creates and forwards a transaction.

2. One or more slave/hub layers process it.

3. Completion is signaled with done() or error()/errorStr().

4. Waiting logic observes completion or timeout.

Each transaction has a unique 32-bit ID used for lookup and correlation.

Locking and Data Access

Transaction payload bytes are accessed via begin()/end() and protected using TransactionLock (from lock()). Use the lock wrapper whenever reading/writing transaction data or completion state from asynchronous code paths.

Timeout and Expiration

Timeout is attached to the transaction at creation time. If a transaction is not completed in time, wait logic marks it with a timeout error. Timer refresh logic can extend active transactions in multi-stage flows to reduce false expirations on slow links.

Subtransactions

Hubs and protocol layers can split one parent transaction into multiple child subtransactions. Parent completion is deferred until all children complete. Child errors are propagated back to the parent transaction error state.

Why Subtransactions Exist

Subtransactions exist to preserve a simple upstream API while handling downstream constraints and translation logic.

Common reasons:

• Access-size limits: downstream links may only support smaller transfers than the parent request size.

• Address-window translation: a virtual address operation may need to be broken into multiple physical operations.

• Protocol decomposition: one logical operation may require multiple wire-level transactions.

Using child transactions lets the hub/protocol layer track and retry each piece independently while still presenting a single completion/error result to the caller. This keeps master-side code simple and avoids exposing transport-specific fragmentation details.

Python Integration

Python-facing APIs expose transaction fields and data access helpers. For Python buffer- backed transfers, the transaction may hold temporary Python buffer state until completion.

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

typedef std::shared_ptr<rogue::interfaces::memory::Transaction> rogue::interfaces::memory::TransactionPtr

Shared pointer alias for Transaction.

The class description is shown below:

class Transaction : public rogue::EnableSharedFromThis<rogue::interfaces::memory::Transaction>

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

Iterator alias for transaction byte access.

Public Functions

explicit Transaction(struct timeval timeout)

Constructs a transaction container.

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.

std::shared_ptr<rogue::interfaces::memory::TransactionLock> lock()

Locks the transaction and returns a lock wrapper.

Exposed as lock() in Python.

Returns:

Transaction lock pointer.

bool expired()

Returns whether this transaction has expired.

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()

Returns the transaction ID.

Exposed as id() in Python.

Returns:

32-bit transaction ID.

uint64_t address()

Returns the transaction address.

Exposed as address() in Python.

Returns:

64-bit transaction address.

uint32_t size()

Returns the transaction size.

Exposed as size() in Python.

Returns:

32-bit transaction size in bytes.

uint32_t type()

Returns the transaction type constant.

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()

Creates a subtransaction linked to this parent transaction.

Returns:

Pointer to the newly created subtransaction.

void doneSubTransactions()

Marks subtransaction creation as complete for this transaction.

void refreshTimer(std::shared_ptr<rogue::interfaces::memory::Transaction> reference)

Refreshes the transaction 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()

Marks transaction completion without error.

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

void errorStr(std::string error)

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

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, ...)

Marks transaction completion with a formatted C-string error.

The transaction lock must be held before calling this method.

uint8_t *begin()

Returns iterator to the beginning of transaction data.

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

Returns:

Data iterator.

uint8_t *end()

Returns iterator to the end of transaction data.

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)

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

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)

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

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.