arm_start_transaction (3) Linux Manual Page

NAME

arm_start_transaction – start transaction

SYNOPSIS

#include <arm4.h>

arm_error_t
arm_start_transaction(

 const arm_app_start_handle_t app_handle, 

 const arm_id_t *tran_id, 

 const arm_correlator_t *parent_correlator, 

 const arm_int32_t flags, 

 const arm_buffer4_t *buffer4, 

 arm_tran_start_handle_t *tran_handle,

 arm_correlator_t *current_correlator);

DESCRIPTION

arm_start_transaction() is used to indicate that a transaction is beginning execution.

Call arm_start_transaction() just prior to a transaction beginning execution. arm_start_transaction() signals the ARM library to start timing the transaction response time. There is one exception: when arm_get_arrival_time() is used to get a start time before arm_start_transaction() executes. See arm_get_arrival_time() to understand this usage.
  arm_start_transaction() is also the means to pass to ARM the correlation token (called a "correlator" in ARM) from a caller – the "parent" – and to request a correlator that can be passed to transactions called by this transaction. The correlation token may be used to establish a calling hierarchy across processes and systems. A correlator contains a two-byte length field, a one-byte format ID, a one-byte flag field, plus it may contain other data that is used to uniquely identify an instance of a transaction. Applications do not need to understand correlator internals. The maximum length of a correlator is 512 (ARM_CORR_MAX_LENGTH) bytes. (In ARM 2.0 it was 168 bytes.)

app_handle is a handle returned in an out parameter from an arm_start_application() call in the same process.

buffer4 is a pointer to the user data buffer, if any. If the pointer is null (ARM_BUF4_NONE), there is no buffer. The sub-buffers that may be used are arm_subbuffer_arrival_time_t, arm_subbuffer_metric_values_t, arm_subbuffer_tran_context_t, and arm_subbuffer_user_t.

current_correlator is a pointer to a buffer into which the ARM implementation will store a correlator for the transaction instance, if any. The length of the buffer should be (at least) 512 (ARM_CORR_MAX_LENGTH) bytes.
  If the pointer is null (ARM_CORR_NONE), the application is not requesting that a correlator be created.

If the pointer is not null, the application is requesting that a correlator be created. In this case the ARM implementation may (but need not) create a correlator in the buffer. It may not create a correlator if it does not support the function or if it is configured to not create a correlator.
  After arm_start_transaction() completes, the application tests the length field using arm_get_correlator_length() to determine whether a correlator has been stored. If the length is still zero, no correlator has been stored. The ARM implementation must store zero in the length field if it does not generate a correlator.

flags contains 32-bit flags. These may be combined using a binary or (|) operation. Three flags are defined:
 

0x00000001

(ARM_FLAG_TRACE_REQUEST) is set if the application requests/suggests a trace.
 

0x00000002

(ARM_FLAG_BIND_THREAD) is set if the started transaction is bound to this thread. Setting this flag is equivalent to immediately calling arm_bind_thread() after the arm_start_transaction() completes, except the timing is a little more accurate and the extra call is avoided.
 

0x00000004

(ARM_FLAG_CORR_IN_PROCESS) is set if the application is stating that it will not send the correlator outside the current process. An ARM implementation may be able to optimize correlator handling if it knows this, because it may be able to avoid serialization to create the correlator. parent_correlator is a pointer to the parent correlator, if any. The pointer may be null (ARM_CORR_NONE).

tran_handle is a pointer to an arm_int64_t into which the ARM library will store the value of the handle that will represent the transaction instance in all calls, up to and including the arm_stop_transaction() that indicates that the instance has completed executing. The scope of the handle is the process in which the arm_start_transaction() is executed.
  There are no defined behaviors for the value returned – it is implementation defined. Note that the returned value will always be a value that the application can use in future calls that take a handle [arm_bind_thread(), arm_block_transaction(), arm_stop_transaction(), arm_unbind_thread(), arm_unblock_transaction(), and arm_update()].
  tran_id is a transaction ID returned in an out parameter from an arm_register_transaction() call in the same process.

RETURN VALUE

On success, the function returns ARM_SUCCESS. A non-zero value indicates an error.

ERRORS

If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred – the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging.

The following errors are recognized by this implementation, but may not be portable to other implementations:

ARM_FAILURE_NULL_ARGUMENT

The tran_handle pointer must not be null.

ARM_FAILURE_INVALID_ARGUMENT

A valid tran_id and app_handle must be provided.

ARM_FAILURE_INTERNAL_ERROR

An internal error has occurred that prevented the operation from completing. Check your system log for more details.

CONFORMING TO

ARM Issue 4.0 C Language Bindings, Version 2

EXAMPLE

None.

SEE ALSO

arm_bind_thread(3), arm_block_transaction(3), arm_get_arrival_time(3), arm_get_correlator_length(3), arm_register_transaction(3), arm_start_application(3), arm_stop_transaction(3), arm_unbind_thread(3), arm_unblock_transaction(3), arm_update_transaction(3)

Index