Memory transaction container passed between master and slave. More...

#include <Transaction.h>

Inheritance diagram for rogue::interfaces::memory::Transaction:

Public Types
typedef uint8_t *	iterator
	Iterator alias for transaction byte access.

Public Member Functions
	Transaction (struct timeval timeout)
	Constructs a transaction container.

	~Transaction ()
	Destroy object.

std::shared_ptr< rogue::interfaces::memory::TransactionLock >	lock ()
	Locks the transaction and returns a lock wrapper.

bool	expired ()
	Returns whether this transaction has expired.

uint32_t	id ()
	Returns the transaction ID.

uint64_t	address ()
	Returns the transaction address.

uint32_t	size ()
	Returns the transaction size.

uint32_t	type ()
	Returns the transaction type constant.

std::shared_ptr< rogue::interfaces::memory::Transaction >	createSubTransaction ()
	Creates a subtransaction linked to this parent transaction.

void	doneSubTransactions ()
	Marks subtransaction creation as complete for this transaction.

void	refreshTimer (std::shared_ptr< rogue::interfaces::memory::Transaction > reference)
	Refreshes the transaction timer.

void	done ()
	Marks transaction completion without error.

void	errorStr (std::string error)
	Marks transaction completion with an error string (Python interface).

void	error (const char *fmt,...)
	Marks transaction completion with a formatted C-string error.

uint8_t *	begin ()
	Returns iterator to the beginning of transaction data.

uint8_t *	end ()
	Returns iterator to the end of transaction data.

void	getData (boost::python::object p, uint32_t offset)
	Copies transaction data into a Python byte-array-like object.

void	setData (boost::python::object p, uint32_t offset)
	Copies data from a Python byte-array-like object into the transaction.

Public Member Functions inherited from rogue::EnableSharedFromThis< rogue::interfaces::memory::Transaction >
std::shared_ptr< rogue::interfaces::memory::Transaction >	shared_from_this ()
	Returns a `shared_ptr<T>` for this instance.

Public Member Functions inherited from rogue::EnableSharedFromThisBase
virtual	~EnableSharedFromThisBase ()
	Virtual destructor for polymorphic base usage.

Static Public Member Functions
static void	setup_python ()

Protected Member Functions
std::string	wait ()
	Wait for the transaction to complete.

Static Protected Member Functions
static std::shared_ptr< rogue::interfaces::memory::Transaction >	create (struct timeval timeout)
	Creates a transaction container.

Protected Attributes
struct timeval	timeout_

struct timeval	endTime_

struct timeval	startTime_

struct timeval	warnTime_

Py_buffer	pyBuf_

bool	pyValid_

iterator	iter_

uint64_t	address_

uint32_t	size_

uint32_t	type_

std::string	error_

uint32_t	id_

bool	done_

std::mutex	lock_

TransactionMap	subTranMap_

bool	doneCreatingSubTransactions_

bool	isSubTransaction_

std::shared_ptr< rogue::Logging >	log_

std::weak_ptr< rogue::interfaces::memory::Transaction >	parentTransaction_

Friends
class	TransactionLock

class	Master

class	Hub

Detailed Description

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.

Definition at line 78 of file Transaction.h.

Member Typedef Documentation

◆ iterator

typedef uint8_t* rogue::interfaces::memory::Transaction::iterator

Iterator alias for transaction byte access.

Definition at line 85 of file Transaction.h.

Constructor & Destructor Documentation

◆ Transaction()

rogue::interfaces::memory::Transaction::Transaction ( struct timeval timeout )

explicit

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.

Definition at line 72 of file Transaction.cpp.

◆ ~Transaction()

rogue::interfaces::memory::Transaction::~Transaction ( )

Destroy object.

Definition at line 102 of file Transaction.cpp.

Member Function Documentation

◆ address()

uint64_t rogue::interfaces::memory::Transaction::address ( )

Returns the transaction address.

Get address.

Exposed as address() in Python.

Returns: 64-bit transaction address.

Definition at line 124 of file Transaction.cpp.

◆ begin()

rogue::interfaces::memory::Transaction::iterator rogue::interfaces::memory::Transaction::begin ( )

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.

Definition at line 288 of file Transaction.cpp.

◆ create()

rogue::interfaces::memory::TransactionPtr rogue::interfaces::memory::Transaction::create ( struct timeval timeout )

staticprotected

Creates a transaction container.

Create a master container.

Private/internal factory used by Master to allocate transaction instances with shared ownership and lifecycle tracking. Parameter semantics are identical to the constructor; see Transaction(). This static factory is the preferred construction path when shared ownership is required across asynchronous request/response paths.

Definition at line 50 of file Transaction.cpp.

◆ createSubTransaction()

rogue::interfaces::memory::TransactionPtr rogue::interfaces::memory::Transaction::createSubTransaction ( )

Creates a subtransaction linked to this parent transaction.

Create a subtransaction.

Returns: Pointer to the newly created subtransaction.

Definition at line 139 of file Transaction.cpp.

◆ done()

void rogue::interfaces::memory::Transaction::done ( )

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.

Definition at line 156 of file Transaction.cpp.

◆ doneSubTransactions()

void rogue::interfaces::memory::Transaction::doneSubTransactions ( )

Marks subtransaction creation as complete for this transaction.

Definition at line 151 of file Transaction.cpp.

◆ end()

rogue::interfaces::memory::Transaction::iterator rogue::interfaces::memory::Transaction::end ( )

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.

Definition at line 294 of file Transaction.cpp.

◆ error()

void rogue::interfaces::memory::Transaction::error	(	const char *	fmt,
			...
	)

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.

Definition at line 214 of file Transaction.cpp.

◆ errorStr()

void rogue::interfaces::memory::Transaction::errorStr ( std::string error )

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.

Definition at line 182 of file Transaction.cpp.

◆ expired()

bool rogue::interfaces::memory::Transaction::expired ( )

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.

Definition at line 110 of file Transaction.cpp.

◆ getData()

void rogue::interfaces::memory::Transaction::getData	(	boost::python::object	p,
		uint32_t	offset
	)

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.

Definition at line 325 of file Transaction.cpp.

◆ id()

uint32_t rogue::interfaces::memory::Transaction::id ( )

Returns the transaction ID.

Get id.

Exposed as id() in Python.

Returns: 32-bit transaction ID.

Definition at line 119 of file Transaction.cpp.

◆ lock()

rogue::interfaces::memory::TransactionLockPtr rogue::interfaces::memory::Transaction::lock ( )

Locks the transaction and returns a lock wrapper.

Get lock.

Exposed as lock() in Python.

Returns: Transaction lock pointer.

Definition at line 105 of file Transaction.cpp.

◆ refreshTimer()

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

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.

Definition at line 262 of file Transaction.cpp.

◆ setData()

void rogue::interfaces::memory::Transaction::setData	(	boost::python::object	p,
		uint32_t	offset
	)

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.

Definition at line 302 of file Transaction.cpp.

◆ setup_python()

void rogue::interfaces::memory::Transaction::setup_python ( )

static

Definition at line 55 of file Transaction.cpp.

◆ size()

uint32_t rogue::interfaces::memory::Transaction::size ( )

Returns the transaction size.

Get size.

Exposed as size() in Python.

Returns: 32-bit transaction size in bytes.

Definition at line 129 of file Transaction.cpp.

◆ type()

uint32_t rogue::interfaces::memory::Transaction::type ( )

Returns the transaction type constant.

Get type.

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

Exposed as type() in Python.

Returns: 32-bit transaction type.

Definition at line 134 of file Transaction.cpp.

◆ wait()

std::string rogue::interfaces::memory::Transaction::wait ( )

protected

Wait for the transaction to complete.

Definition at line 226 of file Transaction.cpp.

Friends And Related Symbol Documentation

◆ Hub

friend class Hub

friend

Definition at line 81 of file Transaction.h.

◆ Master

friend class Master

friend

Definition at line 80 of file Transaction.h.

◆ TransactionLock

friend class TransactionLock

friend

Definition at line 79 of file Transaction.h.

Member Data Documentation

◆ address_

uint64_t rogue::interfaces::memory::Transaction::address_

protected

Definition at line 122 of file Transaction.h.

◆ done_

bool rogue::interfaces::memory::Transaction::done_

protected

Definition at line 137 of file Transaction.h.

◆ doneCreatingSubTransactions_

bool rogue::interfaces::memory::Transaction::doneCreatingSubTransactions_

protected

Definition at line 146 of file Transaction.h.

◆ endTime_

struct timeval rogue::interfaces::memory::Transaction::endTime_

protected

Definition at line 102 of file Transaction.h.

◆ error_

std::string rogue::interfaces::memory::Transaction::error_

protected

Definition at line 131 of file Transaction.h.

◆ id_

uint32_t rogue::interfaces::memory::Transaction::id_

protected

Definition at line 134 of file Transaction.h.

◆ isSubTransaction_

bool rogue::interfaces::memory::Transaction::isSubTransaction_

protected

Definition at line 149 of file Transaction.h.

◆ iter_

iterator rogue::interfaces::memory::Transaction::iter_

protected

Definition at line 119 of file Transaction.h.

◆ lock_

std::mutex rogue::interfaces::memory::Transaction::lock_

protected

Definition at line 140 of file Transaction.h.

◆ log_

std::shared_ptr<rogue::Logging> rogue::interfaces::memory::Transaction::log_

protected

Logger for transaction activity.

Definition at line 152 of file Transaction.h.

◆ parentTransaction_

std::weak_ptr<rogue::interfaces::memory::Transaction> rogue::interfaces::memory::Transaction::parentTransaction_

protected

Definition at line 155 of file Transaction.h.

◆ pyBuf_

Py_buffer rogue::interfaces::memory::Transaction::pyBuf_

protected

Definition at line 112 of file Transaction.h.

◆ pyValid_

bool rogue::interfaces::memory::Transaction::pyValid_

protected

Definition at line 116 of file Transaction.h.

◆ size_

uint32_t rogue::interfaces::memory::Transaction::size_

protected

Definition at line 125 of file Transaction.h.

◆ startTime_

struct timeval rogue::interfaces::memory::Transaction::startTime_

protected

Definition at line 105 of file Transaction.h.

◆ subTranMap_

TransactionMap rogue::interfaces::memory::Transaction::subTranMap_

protected

Definition at line 143 of file Transaction.h.

◆ timeout_

struct timeval rogue::interfaces::memory::Transaction::timeout_

protected

Definition at line 99 of file Transaction.h.

◆ type_

uint32_t rogue::interfaces::memory::Transaction::type_

protected

Definition at line 128 of file Transaction.h.

◆ warnTime_

struct timeval rogue::interfaces::memory::Transaction::warnTime_

protected

Definition at line 108 of file Transaction.h.

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

/home/runner/work/rogue/rogue/include/rogue/interfaces/memory/Transaction.h
/home/runner/work/rogue/rogue/src/rogue/interfaces/memory/Transaction.cpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ iterator

Constructor & Destructor Documentation

◆ Transaction()

◆ ~Transaction()

Member Function Documentation

◆ address()

◆ begin()

◆ create()

◆ createSubTransaction()

◆ done()

◆ doneSubTransactions()

◆ end()

◆ error()

◆ errorStr()

◆ expired()

◆ getData()

◆ id()

◆ lock()

◆ refreshTimer()

◆ setData()

◆ setup_python()

◆ size()

◆ type()

◆ wait()

Friends And Related Symbol Documentation

◆ Hub

◆ Master

◆ TransactionLock

Member Data Documentation

◆ address_

◆ done_

◆ doneCreatingSubTransactions_

◆ endTime_

◆ error_

◆ id_

◆ isSubTransaction_

◆ iter_

◆ lock_

◆ log_

◆ parentTransaction_

◆ pyBuf_

◆ pyValid_

◆ size_

◆ startTime_

◆ subTranMap_

◆ timeout_

◆ type_

◆ warnTime_