The unit of work representation central to the ARM model. More...

Inheritance diagram for arm4::QArmTransaction:

Public Member Functions
const QArmApplication &	getApplication () const
	gets the contaning application instance.
const QString	getContextURIValue () const
	gets the URI context value.
const QString	getContextValue (int32_t index) const
	gets a context property value.
const QArmCorrelator &	getCorrelator () const
	returns a reference to the correlator for the current transaction.
QArmCorrelator &	getCorrelator ()
	returns a reference to the none constant correlator for the current transaction.
const QArmTransactionDefinition &	getDefinition () const
	gets the definition metadata for this transaction.
const QArmCorrelator &	getParentCorrelator () const
	returns the parent correlator, if set for this transaction.
int32_t	getStatus () const
	returns the last status value set on a `stop()` method.
const QArmUser &	getUser () const
	returns the `QArmUser` currently asociated with this transaction instance.
bool	isTraceRequested () const
	gets the current trace request state.
int32_t	setArrivalTime ()
	sets the actual transaction start time for the next `start()`.
int32_t	setContextURIValue (const QString &value)
	sets the URI context value.
int32_t	setContextValue (int32_t index, const QString &value)
	sets a context property value.
int32_t	setTraceRequested (bool traceState)
	Sets request for tracing this transaction.
int32_t	setUser (const QArmUser &user)
	associates a user to the `QArmTransaction` instance.
int32_t	start (const QArmCorrelator &parentCorr=QArmCorrelator::Null)
	indicates when a transaction begins.
int32_t	update ()
	provides heartbeat and/or metric value update functionality.
int32_t	stop (int32_t status, const QString &diagnosticDetail=NullString)
	indicates when a transaction ends and what the status of the transaction was.
int32_t	reset ()
	Resets a transaction if it is currently executing.
int32_t	bindThread ()
	indicates current thread executing on behalf of this transaction.
int32_t	unbindThread ()
	indicates current thread not executing on behalf of this transaction any more.
int64_t	blocked ()
	indicates that the transaction instance is blocked.
int64_t	blocked (const QArmBlockCause &cause)
	indicates that the transaction instance is blocked.
int32_t	unblocked (int64_t blockHandle)
	indicates that the transaction instance is not blocked any more.
bool	isAutomaticBindThread ()
	gets the current status of the automatic bind thread.
int32_t	setAutomaticBindThread (bool b)
	indicates that a thread is executing on behalf of a transaction at the moment `start()` executes.
int32_t	setMessageEventGroup (const QArmMessageEventGroup &group)
	is used to pass an QArmMessageEventGroup to ARM.
int32_t	setPrestartTimeValue (const QArmTimestamp &timestamp)
	is used in situations in which the context of a transaction is not known when the transaction begins to execute, and for which there is a non-trivial delay before the context is known.

Detailed Description

The unit of work representation central to the ARM model.

For most applications, this is the most important of all the ARM classes, and the most frequently used. Many applications operate only on QArmTransaction objects after some initialization ( QArmApplicationDefinition,QArmApplication and QArmTransactionDefinition). Instances of QArmTransaction represent transactions when they execute. A "transaction" is any unit of work that has a clearly understood beginning and ending point, and which begins and ends in the same process. Examples include a remote procedure call, a database transaction, and a batch job. It is not necessary that an ARM transaction implement robust functions such as commit and rollback.

The application creates as many instances as it needs. This will typically be at least as many as the number of transactions that can be executing simultaneously. An application may create a pool of QArmTransaction objects, take one from the pool to use when a transaction starts, and put it back in the pool after the transaction ends for later reuse. Another strategy is to create one instance of each type per thread, which eliminates the need to manage the pool, handle synchronization if the pool is depleted, etc.

Note:: This ARM 4.0 C++ framework only protect the members of an QArmTransaction object against concurrent access from different threads if QARM4_SINGLETHREADED is not defined and in case of the standard ARM 4.0 C++ framework at least a compiler with C++11 support is needed!

The metadata common to all instances is contained in the QArmTransactionDefinition used to create the object. Each transaction is scoped by an application instance, represented by QArmApplication.

The most frequently (and often the only) used methods are start(),getCorrelator(), and stop(). A typical sequence is as follows:

Just prior to executing a transaction, such as a remote procedure call, call start() to signal to ARM that the measurable transaction is beginning. start() causes ARM to capture the current time. If a correlation token was received when your program was invoked, pass it as a parameter on the start().
Just after executing start(), and just prior to executing the transaction, call getCorrelator() to get a correlation token that can be sent along with the other transaction parameters to the receiver. Not all programs use correlators, but their use is highly recommended, because without them, it is usually impossible to drill down to understand the components of a transaction, where they executed, what resources they used, etc.
Execute the transaction (e.g., make the remote procedure call).
As soon as it ends, call stop(), passing a status to indicate whether the transaction succeeded. stop() causes ARM to capture the current time. The response time is determined by calculating the duration between the start() and stop() events.

See the description of the individual methods below for details about each method. All methods that return an int are returning an error code that the application may but need not test. Refer to QArmInterface and the official ARM 4.0 Java Binding Specification for more information about handling errors.

Author:: ARM Working Group of The Open Group, MyARM GmbH

Member Function Documentation

int32_t arm4::QArmTransaction::bindThread ( )

indicates current thread executing on behalf of this transaction.

This method can be called from any thread to indicate that the thread is executing on behalf of the transaction instance. This is useful when multiple threads execute the same logical (ARM) transaction, because instrumentation of resource consumption at the thread level can be more precise. The thread remains bound to this transaction until unbindThread is executed in this thread or stop() or reset() is executed.

Returns:: 0 on success; otherwise, a non-zero error code is returned (as specified in QArmInterface).

int64_t arm4::QArmTransaction::blocked ( )

indicates that the transaction instance is blocked.

Blocked in this context means that the transaction is waiting on an external transaction (which may or may not be instrumented with ARM) or some other event to complete. It has been found useful to separate out this "blocked" time from the elapsed time between the start() and stop(). unblocked() indicates when the blocking condition has ended. A transaction may be blocked by multiple conditions simultaneously. A "block handle" returned by block() is the input parameter to unblocked() to indicate which blocking condition has ended.

Returns:: handle to be passed to a matching unblocked() method call.

int64_t arm4::QArmTransaction::blocked ( const QArmBlockCause & cause )

indicates that the transaction instance is blocked.

See the description of blocked().

Parameters:

cause

describes the cause of the blocking.

Returns:: handle to be passed to a matching unblocked() method call.

Since:: ARM 4.1

const QArmApplication& arm4::QArmTransaction::getApplication ( ) const

gets the contaning application instance.

Returns the value passed to the QArmTransaction() constructor.

Returns:: the containing QArmApplication.

const QString arm4::QArmTransaction::getContextURIValue ( ) const

gets the URI context value.

See the description of setContextURIValue().

Returns:: the URI context value, or null.

const QString arm4::QArmTransaction::getContextValue ( int32_t index ) const

gets a context property value.

See the description of setContextValue().

Parameters:

index

index into the context properties array.

Returns:: the context value at index index, or NullString.

const QArmCorrelator& arm4::QArmTransaction::getCorrelator ( ) const

returns a reference to the correlator for the current transaction.

It may be a newly created object. It can be executed anytime after start() is executed. Each time it is executed, it will return the same value until the next stop() or reset() is executed. If it is executed at any other time, it will return an QArmCorrelator object, but the data within the QArmCorrelator object is undefined and should not be used.

Returns:: a correlator object. Validity of its content depends on the context of execution, see method description.

QArmCorrelator& arm4::QArmTransaction::getCorrelator ( )

returns a reference to the none constant correlator for the current transaction.

It may be a newly created object. It can be executed anytime after start() is executed. Each time it is executed, it will return the same value until the next stop() or reset() is executed. If it is executed at any other time, it will return an QArmCorrelator object, but the data within the QArmCorrelator object is undefined and should not be used.

Returns:: a correlator object. Validity of its content depends on the context of execution, see method description.

const QArmTransactionDefinition& arm4::QArmTransaction::getDefinition ( ) const

gets the definition metadata for this transaction.

Returns the value passed to the QArmTransaction() constructor.

Returns:: the QArmTransactionDefinition metadata.

const QArmCorrelator& arm4::QArmTransaction::getParentCorrelator ( ) const

returns the parent correlator, if set for this transaction.

Returns the last value set on a start() method. If no value was set on the start() method, or if start() has never executed, it returns QArmCorrelator::Null.

Returns:: the parent correlator, or QArmCorrelator::Null.

int32_t arm4::QArmTransaction::getStatus ( ) const

returns the last status value set on a stop() method.

If stop() has never executed, it returns STATUS_INVALID.

Returns:: one of the status values defined in QArmConstants.

const QArmUser& arm4::QArmTransaction::getUser ( ) const

returns the QArmUser currently asociated with this transaction instance.

See description of setUser().

Returns:: an QArmUser, or QArmUser::Null.

bool arm4::QArmTransaction::isAutomaticBindThread ( )

gets the current status of the automatic bind thread.

Returns:: the current status of the automatic bind thread flag.

Since:: ARM 4.1

bool arm4::QArmTransaction::isTraceRequested ( ) const

gets the current trace request state.

The initial trace request state is false. See description of setTraceRequested().

Returns:: the current trace request state.

int32_t arm4::QArmTransaction::reset ( )

Resets a transaction if it is currently executing.

This can be executed at any time. If a transaction is currently executing [start() executed without a matching stop()], the current transaction is discarded and treated as if the start() never executed. If no transaction is currently executing, the state of the object is unchanged. If there is any doubt about the state of an object, reset() gets the object into a known state in which a start() may be executed. reset() clears the arrival time and the current correlator; it does not change traceRequested or any of the context URI, context values, or user.

Returns:: 0 on success; otherwise, a non-zero error code is returned (as specified in QArmInterface).

int32_t arm4::QArmTransaction::setArrivalTime ( )

sets the actual transaction start time for the next start().

This method can be used in situations in which the context of a transaction is not known when the transaction begins to execute, and for which there is a non-trivial delay before the context is known. ARM requires that the full context of a transaction be known when start() is executed (because the correlator is generated at this time). In ARM 2.0 and 3.0 there is no way to capture any time spent processing the transaction before the context is known. ARM 4.0 introduces the concept of an "arrival time". The "arrival time" is when processing of the transaction commenced. By default it is the moment in time when start() executes. If the delay between the start of processing and the execution of start() is significant, the application can capture the arrival time by invoking setArrivalTime(). This establishes a timestamp that will be used at the next start(), after which the value will be reset within the QArmTransaction object. The reset() and stop() methods also clear the value.

Returns:: 0 on success; otherwise, a non-zero error code is returned (as specified in QArmInterface).

int32_t arm4::QArmTransaction::setAutomaticBindThread ( bool b )

indicates that a thread is executing on behalf of a transaction at the moment start() executes.

It is used in place of bindThread(). The motivation is to avoid needing to make another method call to bindThread() in the common case where each transaction executes as a separate thread. setAutomaticBindThread(false) resets this behavior.

Parameters:

b

new status of the automatic bind thread flag.

Returns:: 0 on success; otherwise, a non-zero error code is returned (as specified in QArmInterface).

Since:: ARM 4.1

int32_t arm4::QArmTransaction::setContextURIValue ( const QString & value )

sets the URI context value.

getContextURIValue() returns the value. In most scenarios, a URI would be used as a transaction identity property or a context property, but not both. The only allowed exception is when the base part of the URI is used as an identity property, and the full URI (e.g., with the parameters) is used as a context property. Any other use of URIs as both identity and context properties is invalid.

Parameters:

value

the URI context value.

Returns:: 0 on success; otherwise, a non-zero error code is returned (as specified in QArmInterface).

int32_t arm4::QArmTransaction::setContextValue	(	int32_t	index,
		const QString &	value
	)

sets a context property value.

This method sets one of the maximum 20 context properties that may change for each transaction instance. getContextValue() returns the value. The "name" part is available via getDefinition().getIdentityProperties().getContextName(). The values are position-sensitive - they match the position in the referenced context name array (see the discussion at QArmIdentityProperties for more details). The context property name at the specified array index must have been set to a non-NullString value when the QArmTransactionDefinition object was created. If the name is a NullString or a zero-length string, both the name and value are ignored. If the value is NullString or a zero-length string, the meaning is that there is no value for this instance. The value should not contain trailing blank characters or consist of only blank characters.

Parameters:

	index	index into the context properties array.
	value	the new context property value.

Returns:: 0 on success; otherwise, a non-zero error code is returned (as specified in QArmInterface).

int32_t arm4::QArmTransaction::setMessageEventGroup ( const QArmMessageEventGroup & group )

is used to pass an QArmMessageEventGroup to ARM.

It is executed before start(), update(), stop(), blocked(), or unblocked(). During the execution of any of these five methods, the QArmMessageEventGroup is processed. After any of these five methods execute, any reference to an QArmMessageEventGroup is set to null, though no change is made to the QArmMessageEventGroup. setMessageEventGroup() must be executed again prior to one of the five listed methods to indicate that the QArmMessageEventGroup should be processed again.

setMessageEventGroup(0) clears any previously setting.

int32_t arm4::QArmTransaction::setPrestartTimeValue ( const QArmTimestamp & timestamp )

is used in situations in which the context of a transaction is not known when the transaction begins to execute, and for which there is a non-trivial delay before the context is known.

ARM requires that the full context of a transaction be known when QArmTransaction’s start() is executed (because the correlator is generated at this time). In ARM 2.0 and 3.0 there is no way to capture any time spent processing the transaction before the context is known. ARM 4.0 introduced the concept of an “arrival time”. The arrival time is when processing of the transaction commenced. By default it is the moment in time when start() executes. If the delay between the start of processing and the execution of start() is significant, the application can measure the time and set the value in QArmTransaction before start() executes using setPrestartTimeValue(). The parameter to setPrestartTimeValue() is one of three types: a count in nanoseconds, a timestamp when the processing began (QArmTimestamp), or the measured mean using QArmPrestartTimeStats. No permanent association is made between QArmTransaction and either QArmTimestamp or QArmPrestartTimeStats – it is a copy by value into QArmTransaction. The copied value is valid for one execution of start(); it will be discarded after start() and must be set again to apply to a later start().

int32_t arm4::QArmTransaction::setTraceRequested ( bool traceState )

Sets request for tracing this transaction.

This method is used to suggest or withdraw a suggestion from an application that a transaction be traced. isTraceRequested() is used to query the current trace request state. The initial state is false. Once set, it remains in that state until set to a different state.

Parameters:

traceState

trace request state.

Returns:: 0 on success; otherwise, a non-zero error code is returned (as specified in QArmInterface).

int32_t arm4::QArmTransaction::setUser ( const QArmUser & user )

associates a user to the QArmTransaction instance.

This user, represented by an instance of QArmUser, is assumed to be the user for all start()/ stop() pairs until the association is changed or cleared.

getUser() returns the last value that was set.

Parameters:

user the user to be associated with this transaction instance. When QArmUser::Null, clears any existing association to an QArmUser

Returns:: 0 on success; otherwise, a non-zero error code is returned (as specified in QArmInterface).

int32_t arm4::QArmTransaction::start ( const QArmCorrelator & parentCorr = QArmCorrelator::Null )

indicates when a transaction begins.

Because the response time depends on when start() executes, it should execute as close to the actual start time as possible. After start() executes, it should not be executed again until reset() or stop() is executed. If start() executes consecutively, the behavior is undefined.

There are four versions of start(), depending on whether a parent correlator is provided, and if one is provided, the format of the input data. The length of the correlator is in the first two bytes of the correlator byte array, with the bytes in network byte order. When the input is a byte array, the length of the array does not matter, as long as it is at least long enough to hold the correlator, based on the two-byte length field.

Parameters:

parentCorr

a parent correlator for this transaction

Returns:: 0 on success; otherwise, a non-zero error code is returned (as specified in QArmInterface).

int32_t arm4::QArmTransaction::stop	(	int32_t	status,
		const QString &	diagnosticDetail = `NullString`
	)

indicates when a transaction ends and what the status of the transaction was.

Because the response time depends on when stop() executes, it should execute as close to the actual stop time as possible. If stop() is erroneously issued when there is no transaction active [start() issued without a matching stop()], it is ignored.

Parameters:

status

one of

diagnosticDetail

string with additional diagnostic details provided by the application

Returns:: 0 on success; otherwise, a non-zero error code is returned (as specified in QArmInterface).

int32_t arm4::QArmTransaction::unbindThread ( )

indicates current thread not executing on behalf of this transaction any more.

See decription of bindThread().

Returns:: 0 on success; otherwise, a non-zero error code is returned (as specified in QArmInterface).

int32_t arm4::QArmTransaction::unblocked ( int64_t blockHandle )

indicates that the transaction instance is not blocked any more.

See the description of blocked().

Parameters:

blockHandle handle returned from a previous blocked() method call.

Returns:: 0 on success; otherwise, a non-zero error code is returned (as specified in QArmInterface).

int32_t arm4::QArmTransaction::update ( )

provides heartbeat and/or metric value update functionality.

After a start() there can be any number of update() calls until a stop(). If it is executed at any other time, it is ignored. The behavior of update() issued at any other time is undefined. It is used for two purposes:

It serves as a heartbeat to show that a transaction is still executing. This is especially useful if the transaction is a long-running job.
When used with QArmTransactionWithMetrics, a subclass of QArmTransaction, any of the metric values can be provided with an update().

Returns:: 0 on success; otherwise, a non-zero error code is returned (as specified in QArmInterface).

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

QArm4/QArmTransaction

All Classes Namespaces Files Functions Variables

MyARM - Application Response Measurement (ARM) supported APIs

arm4::QArmTransaction Class Reference
[ARM 4.0 Transactions]

Public Member Functions

Detailed Description

Member Function Documentation

MyARM - Application Response Measurement (ARM) supported APIs

arm4::QArmTransaction Class Reference [ARM 4.0 Transactions]

Public Member Functions

Detailed Description

Member Function Documentation

arm4::QArmTransaction Class Reference
[ARM 4.0 Transactions]